Introduction

• The JS7 - PowerShell Module allows to perform operations 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 use of 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.4.0

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

• When a user account is used to login to JOC Cockpit then this includes to specify credentials such as user account, password or token that are forwarded to the respective Identity Service.
• More than one Identity Service can be active at a given time allowing to authenticate a user account with one out 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

Consider that any credentials used when performing a login to 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 account root and the password root 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 how to populate 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 plaintext $password variable.:  

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

• Another bad way how to deal 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

When HTTPS connections are used then the communication to JOC Cockpit is encrypted. This authentication method requires that 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 consider 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, typically this includes to use 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 from one of the following locations:
  • from the Windows Certificate Store that might similarly be used by a number of browser products when establishing HTTPS connections, therefore no parameter has 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

• With the -KeystorePath parameter the path to a keystore is provided that holds both a 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, the second argument 'jobscheduler' specifies the password for the keystore.
• For Windows environments as an alternative the -CertificateThumbprint parameter can be used that specifies the thumbprint of a private key/certificate entry in the Windows Certificate Store that has been created for Client Authentication.
• One more option is to create an individual $certificate object that 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 to use either credentials or certificate based authentication.
• Multi-factor authentication includes to use both credentials and certificate based authentication.

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

$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