...

• 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

The OIDC protocol 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 a token by the Client and that verifies tokens the token with the Identity Provider.

...

• 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 or access tokens of successful authentication.

Identity Service Configuration

...

OIDC Flows

Register Client

It is required to register a Client with the Identity

...

Provider. The Client specifies the given Client ID and Client Secret during authentication. 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.
• redirect-urls: The list of allowed URLs for redirection after authentication by the Client. Consider that for clustered JOC Cockpit instances the URL of each JOC Cockpit instance has to be specified. For JOC Cockpit the protocol (HTTP, HTTPS), host and port is specified as the URL, for example https://joc-2-0-primary:4446.

The step to register the Client is performed once in the lifetime of an OIDC Identity Service.

Authenticate Client

When authentication is performed with an Identity Provider then

• no additional required Identity Services will

Login

If login is performed with an OIDC Identity Service then

• any additional required Identity Service will not be considered by JOC Cockpit.  The login Authentication is performed with the given OIDC Identity Service only.
• OIDC Identity Services cannot be set to be required.

In case that the Client previously did authenticate with the Identity Provider and that an active session exists then the Client immediately receives tokens from the Identity Provider. Without previous authentication the Client specifies credentials for authentication with the Identity Provider and creates a session in the Identity Provider. This mechanism allows Single Sign-On for Clients.

Token Verification

After successful authentication the Identity Provider returns to the Client:

• Access Token: The Client stores this token in a locker for later token renewal.
• Refresh Token: The Client stores this token in a locker for later token renewal.
• ID Token: This token is used by the Application to verify the Client's authentication. 

Verify Token

During login the following tokens are returned The login call returns the following tokens to the Client:

• Access Token: A token returned after successful authentication by the Identity Service Provider.
• ID Token: A JWT Token with Header.Payload.Signature is expected that is used by the Application to verify the Client's authentication.
• Refresh Token: A token used by the Client to renew the Access Token.

...

• Checking if the response contains the field "active". The value of the field is expected to be "true".
• Checking if the ID 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 thekey entryusing the value for n and e of the corresponding array element where the kid value matches the kid in the token header. 

Renew Token

...

Access Tokens and ID Tokens include The token contains the expiration date. The token tokens will be renewed by the Client 20s before expiration. 

If the token tokens cannot be renewed, for example if the underlying session in the Identity Provider is terminated, then the JOC Cockpit session will be terminated and the user is forced to login. The token cannot be renewed, ifThis occurs in case that

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

Examples for Use with Identity Providers

Register a Client with the OIDC Identity Provider

It is required to register a Client with the OIDC Identity Provider. The Client specifies the given Client ID during login. and Client Secret during login. To achieve this, the token endpoint is called withThe Client will use the following configuration items for token renewal:

• 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 Refresh Token that was previously returned by the Identity Provider after successful authentication..

The JOC Cockpit session idle timeout 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 in time of the next token renewal.

Examples for Use with Identity Providers

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.

...