Introduction

• The JS7 - Identity Services offer local management of user accounts for authentication and authorization.
• The OIDC Identity Service integration is available from JOC Cockpit:
  • Any OIDC compliant Identity Provider can be used for authentication.
  • This requires an OIDC Identity Provider to be installed and operated. JS7 does not ship with an OIDC Identity Provider.
  • JS7 implements a REST client for use with OIDC Identity Providers.

Terminology

OIDC knows of the following roles involved in authentication:

• The Identity Provider is a system external to JS7 that provides authentication services for user accounts.
• The Client is the JOC Cockpit GUI that performs login/logout with the Identity Provider and that receives tokens from the Identity Provider in case of successful login.
• The Application is the JS7 - REST Web Service API that is handed over tokens by the Client and that verifies tokens with the Identity Provider.

Identity Service Type

The following integration level is available from the OIDC Identity Service Type:

Explanation:

• Service Type: OIDC
  • Management of user accounts with passwords is performed by the OIDC Identity Provider
  • The assignment of roles to user accounts is performed by the JOC Cockpit Client.
  • The JOC Cockpit stores user accounts and role assignments: in the JS7 - Database.
  • The JOC Cockpit does not know passwords of user accounts.

Identity Service Configuration

The  icon in the JOC Cockpit main menu is used to select the Manage Identity Services page:

Add Identity Service

To add an Identity Service use the button Add Identity Service from the page shown above, listing the available Identity Services:

The remaining input fields for the popup window look like this:

Explanation:

• The Identity Service Name is a unique identifier that can be freely chosen.
• The Identity Service Type can be selected as available from the above matrix.
• The Ordering specifies the sequence in which a login is performed with available Identity Services.
• The Disabled attribute specifies if the respective Identity Service should not be considered by JOC Cockpit.
• The Identity Service Authentication Scheme allows to select
  • single-factor authentication: user account and password are specified for login with the Identity Service.
  • two-factor authentication: in addition to user account and password a Client Authentication Certificate is required - see the JS7 - Certificate based Authentication article for more information.

Identity Service Settings

Having added an OIDC Identity Service it is necessary to add settings for the OIDC integration from the Identity Service's Manage Settings action menu item:

For use with the OIDC Identity Service Type:

• the OIDC Identity Provider product has to be installed and has to be accessible for JOC Cockpit and
• the following settings have to be specified:
  
  

Explanations:

Identity Service Processing

Login

If login is performed with an OIDC Identity Service then

• the list of required Identity Services will not be considered by JOC Cockpit.
• the login is tried with the given OIDC Identity Service only. Other Identity Services will not be considered.
• OIDC Identity Services cannot be set to be "required".

Token Verification

The login call returns the following tokens to the Client:

• Access Token: A token returned after successful authentication by the Client.
• ID Token: A JWT Token with Header.Payload.Signature is expected.
• Refresh Token: A token used by the Application to renew the Access Token.

After successful login of the Client the OIDC Token Verification URL is called by the Application with the following settings:

• Client ID
• Client Secret
• Access Token

Processing of the response and verification of the token is performed by the following steps:

• Checking if the response contains the field "active". The value of the field is expected to be "true".
• Checking if the Access Token is not expired.
• Checking if the Client  ID (aud) stored in the ID Token is the same as in the configuration of the Identity Service.
• Checking if the issuer (iss) stored in the ID Token is the same as the OIDC Authentication URL in the configuration of the Identity Service.
• Checking if the account (e-mail) stored in the ID Token is the same as in the field "email" in the answer of the userinfo endpoint.
• Checking if the signature is valid for the given public key. The certs endpoint is the value of jwks_uri  in the response to the /.well-known/openid-configuration call. The response of the certs endpoint includes a number of keys. The public key is calculated from the key entry using the value for n and e of the corresponding array element where the kid value matches the kid in the token header. 

Token Renewal

The token contains the expiration date. The token will be renewed 20s before expiration. 

If the token cannot be renewed then the JOC Cockpit session will be terminated and the user is forced to login.

The token cannot be renewed, if

• the session has been cancelled in the Identity Provider. 
• no valid Session Token is returned from the Identity Provider.

Examples for Use with Identity Providers

Adding a Client to the OIDC Identity Provider

It is required to configure a Client in the OIDC Identity Provider. The Client specifies the given Client ID and Client Secret during login. To achieve this, the token endpoint is called with

• client-id: The Client ID that is configured in the JOC Cockpit Identity Service.
• client-secret: The Client Secret that is configured in the JOC Cockpit Identity Service.
• grant-type: refresh_token
• refresh-token: The refresh token that has been provided in the header of the login call.

The JOC Cockpit session idle timeout is configured in the JOC Cockpit global settings for Identity Services.

If the session in the Identity Provider is no longer valid then the JOC Cockpit session will terminate at the point of time of the next token renewal.

Keycloak Identity Provider

Settings

• Open "Clients" view.
• Create a new Client with the "Create" button.
• The following values are approved:
  • Enabled: on
  • Standard Flow Enable: on
• Valid Redirect URL: JOC Cockpit URL, for example https://joc-primary:4446/joc
• Web Origin: For example https://joc-primary:4446/joc

Credentials

• Client Authenticator: Client ID and Client Secret
• Secret: Generated secret value

After setting up the Client users can be added in Keycloak's "Users" view.

Logging

• Log Files
  • See JS7 - Log Files and Locations
• Standard Log Files
  • Identity Services log output to the JETTY_BASE/logs/joc.log file. This includes reporting success or failure of authentication.
  • Successful and failed authentication attempts including user accounts involved are logged to the JETTY_BASE/logs/audit.log file.
• Debug Log Files
  • For problem analysis during setup of an Identity Service increase the log level as explained with JS7 - Log Levels and Debug Options.
  • The JETTY_BASE/logs/joc-debug.log file includes general debug output of JOC Cockpit.
  • The JETTY_BASE/logs/authentication-debug.log file includes debug output related to authentication and authorization.
  • The JETTY_BASE/logs/jetty.log file includes debug output of attempts to establish SSL connections.