Skip to end of metadata
Go to start of metadata

Name

Connect-JS7

SYNOPSIS

Connects to the JS7 JOC Cockpit Web Service.

SYNTAX

Connect-JS7 [-Url] <Uri> [[-Credentials] <PSCredential>] [[-Id] <String>] [-AskForCredentials] [-UseDefaultCredentials] [[-ProxyUrl] <Uri>] [[-ProxyCredentials] <PSCredential>] [-ProxyUseDefaultCredentials] [[-Base] <String>] [[-Timeout] <Int32>] [[-SSLProtocol] <String>] [[-Certificate] <X509Certificate2>] [[-CertificateThumbprint] <String>] [[-KeyStorePath] <String>] [[-RootCertificatePath] <String>] [-SkipCertificateCheck] [-ControllerDetails] [<CommonParameters>]

DESCRIPTION

A connection to the JOC Cockpit Web Service is established including support for credentials and use of a proxy.

The cmdlet authenticates a user and returns an access token in case of successful authentication
that is used for subsequent requests to the Web Service.

Caveat:
* This cmdlet calls the Invoke-WebRequest cmdlet that may throw an error "The response content cannot be parsed because the Internet Explorer engine
is not available, or Internet Explorer's first-launch configuration is not complete. Specify the UseBasicParsing parameter and try again."

* This problem is limited to Windows. The reason for this error is a weird PowerShell dependency on IE assemblies.
* If Internet Explorer is not configured then it prompts the user for configuration when being launched.

* To disable IE's first launch configuration window you can modify the Windows registry
** by running a PowerShell script: Set-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Internet Explorer\Main" -Name "DisableFirstRunCustomize" -Value 2
** by using the "regedit" utility and navigating in the HKLM hive to the above key "DisableFirstRunCustomize" and assigning the value "2".
** this operation requires administrative permissions.

PARAMETERS

Url

-Url <Uri>
Specifies the URL to access the Web Service.

Required?true
Position?1
Default value
Accept pipeline input?true (ByValue, ByPropertyName)
Accept wildcard characters?false

Credentials

-Credentials <PSCredential>
Specifies a credentials object that is used to authenticate the account with the JS7 Web Service.

Credentials can be specified in a script:

* PS C:\> $credential = ( New-Object -typename System.Management.Automation.PSCredential -ArgumentList 'root', ( 'root' | ConvertTo-SecureString -AsPlainText -Force) )

Credentials sets can be managed with Windows built-in tools such as:

* PS C:\> cmdkey /generic:JS7 Web Service /user:root /pass:secret
* The Windows Credential Manager that is available Windows Control Panel.

A previously created credentials set can be retrieved by use of the cmdlet:

* PS C:\> $credentials = Get-JS7SystemCredentials -TargetName "JS7 Web Service"

The credentials object can be assigned the -Credentials parameter.

Required?false
Position?2
Default value
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

Id

-Id <String>
Specifies the ID of a JS7 Controller that was used during installation of the product.
If no ID is specified then the first JS7 Controller registered with JOC Cockpit will be used.

Required?false
Position?3
Default value
Accept pipeline input?true (ByValue, ByPropertyName)
Accept wildcard characters?false

AskForCredentials

-AskForCredentials <SwitchParameter>
Specifies that the user is prompted for the account and password that are used for authentication with JS7.

Required?false
Position?named
Default valueFalse
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

UseDefaultCredentials

-UseDefaultCredentials <SwitchParameter>
This parameter currently is not used. It is provided for future versions of JOC Cockpit that support single sign on.

Required?false
Position?named
Default valueFalse
Accept pipeline input?true (ByValue, ByPropertyName)
Accept wildcard characters?false

ProxyUrl

-ProxyUrl <Uri>
If JOC Cockpit is accessed via a proxy server then the proxy server URL is specified with this parameter.

Required?false
Position?4
Default value
Accept pipeline input?false
Accept wildcard characters?false

ProxyCredentials

-ProxyCredentials <PSCredential>
If JOC Cockpit is accessed via a proxy server that requires authentication then the credential set
for the proxy server can be specified with this parameter.

Required?false
Position?5
Default value
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

ProxyUseDefaultCredentials

-ProxyUseDefaultCredentials <SwitchParameter>
This parameter currently is not used. It is provided for future versions of JOC Cockpit that support single sign on.

Required?false
Position?named
Default valueFalse
Accept pipeline input?true (ByValue, ByPropertyName)
Accept wildcard characters?false

Base

-Base <String>
The Base is used as a prefix to the Path for web service URLs and is configured with the web server
that hosts the JS7 Web Service.

This value is fixed and should not be modified for most use cases.

Default: /joc/api

Required?false
Position?6
Default value/joc/api
Accept pipeline input?true (ByValue, ByPropertyName)
Accept wildcard characters?false

Timeout

-Timeout <Int32>
Specifies the timeout to wait for the JOC Cockpit Web Service response.

Required?false
Position?7
Default value30
Accept pipeline input?true (ByValue, ByPropertyName)
Accept wildcard characters?false

SSLProtocol

-SSLProtocol <String>
This parameter can be used to specify the TLS protocol version that should be used. The protocol version is agreed
on between the JOC Cockpit web server and the PowerShell client. Both server and client have to identify a common
protocol version.

* -SSLProtocol 'Tls'
** use any TLS protocol version available
* -SSLProtocol 'Tls12'
** use TLS protocol version 1.2 only
* -SSLProtocol 'Tls11,Tls12'
** use TLS protocol version 1.1 or 1.2 only

Required?false
Position?8
Default value
Accept pipeline input?true (ByValue, ByPropertyName)
Accept wildcard characters?false

Certificate

-Certificate <X509Certificate2>

This parameter can be used for client authentication if JOC Cockpit is configured for mutual authentication with HTTPS (SSL).
If JOC Cockpit is configured to accept one-factor authentication then the certificate specified with this parameter replaces
the password for login. If JOC Cockpit requires two-factor authentication then a certificate is required in addition to specifying a password for login.

Consider that this parameter expects a certificate with the data type [System.Security.Cryptography.X509Certificates.X509Certificate2].
This parameter can be used for Windows only. For other operating systems use the -KeyStorePath parameter.

Use of this parameter requires that the certificate object includes the private key and the certificate chain, i.e. the certificate
and any intermediate/root certificates required for validation of the certificate.

This parameter cannot be used with the -CertificateThumbprint parameter or -KeyStorePath parameter.

Required?false
Position?9
Default value
Accept pipeline input?true (ByValue, ByPropertyName)
Accept wildcard characters?false

CertificateThumbprint

-CertificateThumbprint <String>

This parameter can be used for client authentication if JOC Cockpit is configured for mutual authentication with HTTPS (SSL).
If JOC Cockpit is configured to accept one-factor authentication then the certificate identified with this parameter replaces
the password for login. If JOC Cockpit requires two-factor authentication then a certificate is required
in addition to specifying a password for login.

This parameter can be used for Windows only. For other operating sysems use the -KeyStorePath parameter.

Use of this parameter requires a certificate store to be in place that holds the private key and certificate chain, i.e. the same certificate
and any intermediate/root certificates required for validation of the certificate. Consider this parameter a reference
to a certificate entry in your Windows certificate store that includes the private key and certificate chain.

This parameter cannot be used with the -Certificate parameter or -KeyStorePath parameter.

Required?false
Position?10
Default value
Accept pipeline input?true (ByValue, ByPropertyName)
Accept wildcard characters?false

KeyStorePath

-KeyStorePath <String>

This parameter can be used for client authentication if JOC Cockpit is configured for mutual authentication with HTTPS (SSL).
If JOC Cockpit is configured to accept one-factor authentication then the certificate from the keystore specified with this parameter replaces
the password for login. If JOC Cockpit requires two-factor authentication then a certificate is required
in addition to specifying a password for login.

This parameter expects the path to a keystore file, preferably a PKCS12 keystore, that holds the private key and certificate chain, i.e. the certificate
and any intermediate/root certificates required for validation of the certificate. Certificates of type X509 are supported.

The cmdlet adds the private key, certificate and any intermediate/root certificates from the keystore to the certificate store
used by the current account. This parameter can be used for Windows and Unix operating systems.

This parameter cannot be used with the -Certificate parameter or -CertificateThumbprint parameter.

Required?false
Position?11
Default value
Accept pipeline input?true (ByValue, ByPropertyName)
Accept wildcard characters?false

RootCertificatePath

-RootCertificatePath <String>
Specifies the location of a file that holds the root certificate that was when signing the JOC Cockpit
SSL certificate.

* For Windows environments the root certificate by default is looked up in the Windows Certificate Store, however,
this parameter can be used to apply a root certificate from a location in the file system.
* For Linux environments a path is specified to the root certificate file.

Required?false
Position?12
Default value
Accept pipeline input?true (ByValue, ByPropertyName)
Accept wildcard characters?false

SkipCertificateCheck

-SkipCertificateCheck <SwitchParameter>
Specifies that the JOC Cockpit SSL certificate will not be checked, i.e. the identify of the JOC Cockpit instance is not verified.

Use of this parameter is strongly discouraged with secure environments as it trusts a JOC Cockpit SSL certificate without verification.

Required?false
Position?named
Default valueFalse
Accept pipeline input?true (ByValue, ByPropertyName)
Accept wildcard characters?false

ControllerDetails

-ControllerDetails <SwitchParameter>
Returns details about each Controller such as host, port, active role etc.
The details are provided with the "ControllerInstances" data structure in the response.

Required?false
Position?named
Default valueFalse
Accept pipeline input?true (ByValue, ByPropertyName)
Accept wildcard characters?false

about_JS7

EXAMPLES

-------------------------- EXAMPLE 1 --------------------------

PS > Connect-JS7 http://localhost4446 -AskForCredentials

Connects to the JS7 Web Service at the indicated address and asks the user interactively to enter credentials.

-------------------------- EXAMPLE 2 --------------------------

PS > $credential = ( New-Object -typename System.Management.Automation.PSCredential -ArgumentList 'root', ( 'root' | ConvertTo-SecureString -AsPlainText -Force) ) Connect-JS7 http://localhost:4446 $credential scheduler

A variable $credential is created that holds the credentials for the default root account of JOC Cockpit. When calling the cmdlet the URL is specified, the JS7ID that was used during installationn and the credential object.

-------------------------- EXAMPLE 3 --------------------------

PS > cmdkey /generic:JS7 Web Service /user:root /pass:root $credentials = Get-JS7SystemCredentials -TargetName "JS7 Web Service" Connect-JS7 -Url http://localhost:4446 -Credentials $credentials

Prior to use with PowerShell with some external command ("cmdkey") a credential set is generated for the current user. The credentials are retrieved by use of the Get-JS7SystemCredentials cmdlet and are forwarded to the Connect-JS7 cmdlet.

  • No labels
Write a comment…