Introduction

• The JS7 - PowerShell Module allows operations to be performed with the JS7 - REST Web Service API. The module simplifies access to REST resources for scripting purposes.
• The connection to JOC Cockpit is established by using the Connect-JS7 cmdlet.
• JOC Cockpit offers a number of authentication methods that are supported by the Connect-JS7 cmdlet.

Identity Services

FEATURE AVAILABILITY STARTING FROM RELEASE 2.3.0

JOC Cockpit implements the concept of JS7 - Identity Services which allows use of a number of Authentication Servers. These manage user accounts either locally or by federation with LDAP, Cloud Services etc.

• When a user account is used to login to the JOC Cockpit, credentials such as user account, password or token will be specified which are then forwarded to the relevant Identity Service.
• More than one Identity Service can be active at a given time. This allows authentication of a user account to take place with one of a number of Identity Services or to force authentication with more than one Identity Service.

Authentication Methods

Basically authentication makes use of credentials such as user account/password or token. 

Alternatively or in addition to use of credentials, authentication can be performed with certificates.

This article is focused on use of authentication methods, find further information how to connect to JOC Cockpit from the Connect-JS7 cmdlet

User Account/Password Authentication for HTTP Connections

Note that any credentials used when performing a login to the JOC Cockpit will be exposed to the network if an unsecured HTTP connection is used.

$credential = ( New-Object -typename System.Management.Automation.PSCredential -ArgumentList 'root', ( 'root' | ConvertTo-SecureString -AsPlainText -Force) )

Connect-JS7 -Url http://localhost:4446 -Id controller -Credential $credential

• To specify the user account/password a $credential object is created.
  • The above example exposes the root account and the root password directly to readers of the script.
  • Frequently users populate the credential object from a PowerShell® profile that is automatically executed when running PowerShell® scripts.
  • There are more ways of populating credential objects, e.g. by reading a serialized object from a file.
• Please keep in mind that PowerShell® credential objects are not secure. In fact they are based on a "secure string" datatype that does not expose a password immediately. However, secure strings are intended to prevent exposition of credentials during logging, they do not prevent a password from being decrypted like this:
  • $ptr = [System.Runtime.InteropServices.Marshal]::SecureStringToCoTaskMemUnicode($credential.password)
$password = [System.Runtime.InteropServices.Marshal]::PtrToStringUni($ptr)
  • The above two lines are sufficient to decrypt a secure string $credential.password to a plain text $password variable. 

Connect-JS7 -Url http://root:root@127.0.0.1:4446 -Id controller

• Another bad way for dealing with credentials is to directly prefix the server path in the URL with the user account and password as in root:root@.

User Account/Password Authentication for HTTPS Connections

Communication to the JOC Cockpit is encrypted when HTTPS connections are used. This authentication method requires that the JOC Cockpit is set up to use SSL for HTTPS connections.

$credential = ( New-Object -typename System.Management.Automation.PSCredential -ArgumentList 'root', ( 'root' | ConvertTo-SecureString -AsPlainText -Force) )

Connect-JS7 -Url https://joc-2-0-primary:4443 -Id controller -Credential $credential
# or
Connect-JS7 -Url https://joc-2-0-primary:4443 -Id controller -Credential $credential -RootCertificatePath c:/my/root-ca.crt
# or
$trustStoreCredentials = ( New-Object -typename System.Management.Automation.PSCredential -ArgumentList 'truststore', ( 'jobscheduler' | ConvertTo-SecureString -AsPlainText -Force) )
Connect-JS7 -Url https://joc-2-0-primary:4443 -Id controller -Credential $credential -RootCertificatePath c:/my/truststore.p12 -RootCertificateCredentials $truststoreCredentials

• Authentication with credentials holding the user account/password is the same as for HTTP connections.
• For use with HTTPS connections please note that:
  • the URL has to specify a hostname, not an IP address and not localhost.
  • The JOC Cockpit server certificate has to be created for the given hostname. This typically includes the use of the fully qualified hostname (FQDN) in the URL.
• The PowerShell® client has to establish the HTTPS connection and therefore the JOC Cockpit server certificate has to be available to the PowerShell® client at one of the following locations:
  • from the Windows Certificate Store that might also be used by a number of browser products when establishing HTTPS connections. This means that parameter does not have to be specified to use this option,
  • from a certificate file that is specified with the -RootCertificatePath parameter.
    • this file holds the certificate in a PEM format (.pem, .crt) or
    • alternatively a truststore file can be specified in PKCS12 format (.p12).
      • If a truststore is used then the -RootCertificateCredentials parameter can be specified that holds a credential object with the password for access to the truststore.
      • When creating the truststore credential object then the first argument 'truststore' is arbitrary. Only the the second argument 'jobscheduler' is relevant as it specifies the password.

Certificate Based Authentication with HTTPS Connections

This authentication method requires that JOC Cockpit is set up:

• to use SSL for HTTPS connections and
• to challenge Client Authentication certificates to be in place either optionally or mandatory.

Connect-JS7 -Url https://joc-2-0-primary:4443 -Id controller -KeystorePath "c:/my/keystore.p12"
# or
$keyStoreCredentials = ( New-Object -typename System.Management.Automation.PSCredential -ArgumentList 'keystore', ( 'jobscheduler' | ConvertTo-SecureString -AsPlainText -Force) )
Connect-JS7 -Url https://joc-2-0-primary:4443 -Id controller -KeystorePath "c:/my/keystore.p12" -KeyStoreCredentials $keyStoreCredentials
# or
Connect-JS7 -Url https://joc-2-0-primary:4443 -Id controller -CertificateThumbprint "4ce8129a8f668f62cee491ec625b161988dcdba6"
# or
$certificate = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Certificate2
...
Connect-JS7 -Url https://joc-2-0-primary:4443 -Id controller -Certificate $certificate

• The -KeystorePath parameter specifies the path to a keystore which holds both the private key and certificate that are used for Client Authentication.
  • Keep in mind that for Windows environments frequently the .pfx extension is used instead of .p12, however, the certificate store format is the same.
  • Credentials for access to the keystore can be provided with the -KeyStoreCredentials parameter. When setting up the credential object then the first argument 'keystore' is arbitrary. Only the second argument 'jobscheduler' specifies the password for the keystore.
• As an alternative for Windows environments the -CertificateThumbprint parameter can be used. This specifies the thumbprint of a private key/certificate entry in the Windows Certificate Store which has been created for Client Authentication.
• One more option is to create an individual $certificate object which is used with the -Certificate parameter. Use of this option requires detailed knowledge how to create and to populate certificate objects.

Single-factor and Multi-factor Authentication

This boils down to the following definition:

• Single-factor authentication includes using either credentials or certificate based authentication.
• Multi-factor authentication includes using both credentials and certificate based authentication.

Multi-factor authentication means that from the above examples both credentials and certificates can be specified as follows:

$credential = ( New-Object -typename System.Management.Automation.PSCredential -ArgumentList 'root', ( 'root' | ConvertTo-SecureString -AsPlainText -Force) )

Connect-JS7 -Url https://joc-2-0-primary:4443 -Id controller -Credential $credential -KeystorePath "c:/my/keystore.p12"
# or
$keyStoreCredentials = ( New-Object -typename System.Management.Automation.PSCredential -ArgumentList 'keystore', ( 'jobscheduler' | ConvertTo-SecureString -AsPlainText -Force) )
Connect-JS7 -Url https://joc-2-0-primary:4443 -Id controller -Credential $credential -KeystorePath "c:/my/keystore.p12" -KeyStoreCredentials $keyStoreCredentials
# or
Connect-JS7 -Url https://joc-2-0-primary:4443 -Id controller -Credential $credential -CertificateThumbprint "4ce8129a8f668f62cee491ec625b161988dcdba6"
# or
$trustStoreCredentials = ( New-Object -typename System.Management.Automation.PSCredential -ArgumentList 'truststore', ( 'jobscheduler' | ConvertTo-SecureString -AsPlainText -Force) )
Connect-JS7 -Url https://joc-2-0-primary:4443 -Id controller -Credential $credential -KeystorePath "c:/my/keystore.p12" -KeyStoreCredentials $keyStoreCredentials -RootCertificatePath c:/my/truststore.p12 -RootCertificateCredentials $truststoreCredentials