Introduction

A number of JITL job templates make use of the JS7 - REST Web Service API to retrieve information from the JOC Cockpit:

• JS7 - JITL CheckHistoryJob
• JS7 - JITL CheckLogJob
• JS7 - JITL MaintenanceWindowJob
• JS7 - JITL MonitoringJob
• JS7 - JITL OrderStateTransitionJob
• JS7 - JITL SetJobResourceJob
• JS7 - JITL JS7RESTClientJob

The following prerequisites apply to operation of the JITL jobs:

• Network access from the Agent that executes the job to the JOC Cockpit instance,
• Availability of Controller and of JOC Cockpit,
• Authentication and authorization with JOC Cockpit.

Job Templates use a common mechanism for authentication with the JS7 - REST Web Service API:

• a user account/password and/or
• a certificate, for details see JS7 - Authentication.

Users can apply authentication settings from

• the Agent's ./config/private/private.conf configuration file.
• JS7 - Job Resources assigned the workflow or the job.
  
  FEATURE AVAILABILITY STARTING FROM RELEASE 2.8.0

Typically Job Resources are more flexible as they exist once per scheduling environment and can optionally be used for all Agents. Use of private.conf files holding configuration items has to be prepared on a per Agent basis; at the same time this guarantees use of authentication settings independently from the JS7 inventory.

Authentication Settings

The following settings are applicable:

Authentication by Agent Configuration

For authentication purposes the Job Templates can make use of the Agent's ./config/private/private.conf file to find settings as specified with chapter Authentication Settings.

Consider that the JS7 - Configuration Format is HOCON which means that setitngs

• can be written in a single line such as

  Single line configuration format

  js7.api-server.url = ["https://joc-2-0-primary:4443"]

• can be written across a number of lines such as

  Multi line configuration format

  js7 {
      api-server {
          url = ["https://joc-2-0-primary:4443"]
      }
  }

Find the following configuration example:

js7 {
    auth { ... }
    configuration { ... }
    job { ... }
    web { ... }

    api-server {
        # API Server URL
        url = [
            "https://joc-2-0-primary:4443",
            "https://joc-2-0-secondary:4443",
         ]

        # Option 1: use of a Credential Store
        cs-file=${js7.config-directory}"/private/secret.kdbx"
        cs-key=${js7.config-directory}"/private/secret.key"
        cs-password="secret"

        # Option 1: use of references to credentials 
        username="cs://myAccounts/joc@username"
        password="cs://myAccounts/joc@password"


        # Option 2: use of account and password
        # username="root"
        # password="root"


        # option 3: use of encrypted account and password
        # username="enc:BAGaj1JGQQX2flfi5W4TUxIUDzYXJmI7T1WIO8QZAGoQF3rmsyaLnmehFnCMLTzG3VJdi4zUvw9M++2Du9YuxCax+NUCTmabAB1nlvEGc9wgOXsHer9LxgmucU4Ue1xzz6kI7sc= lrVE+e9qaAFyVraamlivmA== zLefNPT1WhHFzIGM/V+KAw=="
        # password="enc:BAGaj1JGQQX2flfi5W4TUxIUDzYXJmI7T1WIO8QZAGoQF3rmsyaLnmehFnCMLTzG3VJdi4zUvw9M++2Du9YuxCax+NUCTmabAB1nlvEGc9wgOXsHer9LxgmucU4Ue1xzz6kI7sc= lrVE+e9qaAFyVraamlivmA== zLefNPT1WhHFzIGM/V+KAw=="
        # privatekey.path=config/private/private-x509-keys/pdEncryptDecrypt-001.key
     }
}

Explanation:

• The api-server configuration section specifies authentication details for JITL Job Templates and can be positioned anywhere within the js7 configuration block.
• Configuration items available from this configuration section are explained in the following chapters:

Certificate Based Authentication

JS7 - Certificate based Authentication is configured with the ./config/private/private.conf file or from a Job Resource.

• The url configuration item is required that specifies the URL of the JS7 REST Web Service API. Typically this corresponds to the JOC Cockpit URL.
  • Users can set up a number of JOC Cockpit instances that are clustered for automated fail-over.
  • Users can set up a load balancer that routes requests to a number of available JOC Cockpit instances.
  • For use with JITL job templates both active and standby JOC Cockpit instances can be used.
• No further configuration items are used.
• The Client Authentication Certificate has to be available from the keystore file indicated by the js7.web.https.keystore or js7.web.https.client-keystore settings.
  • This requires that JOC Cockpit is configured to use a truststore that holds the Root CA Certificate and Intermediate CA Certificate that was used to sign the Agent's Client Authentication Certificate.
  • For details see JS7 - JOC Cockpit HTTPS Connections.

User Account / Password Authentication

User account/password authentication is configured with the ./config/private/private.conf file or from a Job Resource.

• The url configuration item is required as explained above.
• The username and password can be specified from the following options:
  • Option 1: Use of a JS7 - Credential Store
    • with the following settings:
      • cs-file: Specifies the path to a KeePass database file (required).
      • cs-key: Specifies the path to a KeePass key file (optional).
      • cs-password: Specifies the password for the KeePass database file (optional).
      • username: Specifies the path to the entry in the KeePass database that holds the account name (required).
      • password: Specifies the path to the entry in the KeePass database that holds the password (required).
    • the use of a KeePass key file (cs-key) to protect the KeePass database is preferable. Basically it is pointless to protect a Credential Store by use of a password  (cs-password) which has a visibility similar to putting the key under the mat. Use of a key file allows OS ownership and file permissions to be applied to protect the key file from being visible to 3rd parties.
  • Option 2: Use of user account and password
    • with the following settings:
      • username: Specifies the account name (required).
      • password: Specifies the plain text password (required).
    • this means that both settings will be visible in the configuration file.
  • Option 3: Use of encrypted user account and password
    • with the following settings:
      • username: Specifies the encrypted account name (required).
      • password: Specifies the encrypted password (required).
      • privatekey.path: Specifies the location of the private key to decrypt the password. An absolute location can be specified and a location relative to <AGENT-DATA>. directory can be specified. Frequently private keys are stored in the <AGENT-DATA>/config/private directory or a sub-directory. The private key must not be encrypted.
    • Encryption can be performed from the JOC Cockpit GUI and from command line tools, see JS7 - How to encrypt and decrypt.

Authentication by Job Resource Settings

Users can create JS7 - Job Resources that hold the variables specified in chapter Authentication Settings.

• Download Job Resource example (upload .json): JITL-AuthenticationSettings.jobresource.json
• The example holds all available settings. Users should remove any settings not used.

The Job Resource is assigned the related workflow or JITL Job like this:

For the relationship of settings for different authentication methods see chapter Authentication by Agent Configuration.