• The JS7 - Identity Services offer management of user accounts for authentication and authorization.
  • The OIDC Identity Service integration is available from JOC Cockpit:
    • As a prerequisite JOC Cockpit has to be set up for JS7 - JOC Cockpit HTTPS Connections.
    • OIDC compliant Identity Providers can be used for authentication, for example Microsoft Azure®.
    • JS7 implements a client for use with OIDC Identity Providers. JS7 does not ship with an OIDC Identity Provider.


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 a token by the Client and which verifies the token with the Identity Provider.

Identity Service Type

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

Identity ServiceIdentity Service Configuration Items
Service TypeBuilt-inUser Accounts/Passwords
stored with
User Accounts/Passwords
managed by
stored with
Roles->User Accounts Mapping
managed with
OIDCyesOIDC Identity ProviderOIDC Identity ProviderJS7 Database JOC Cockpit


  • 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 Application.
    • The JOC Cockpit stores user accounts and role assignments: in the JS7 - Database.
    • The JOC Cockpit does not know passwords of user accounts or the access tokens of successful authentication.

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:


  • 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 accessible for JOC Cockpit and
  • a number of settings have to be specified

Example for Keycloak

Example for Azure


OIDC NameThe name of the OIDC Identity Service.The name of the Identity Service is used by JOC Cockpit to show the caption of the assigned login button.Google, Keycloak
OIDC Authentication URLThe URL used by the Client to login to the OIDC Identity Provider.This URL is called by the Client for login and returns the Access Token from the OIDC Identity Provider. It is similarly used when reading settings of the OIDC Identity Provider with the /.well-known/openid-configuration URL and is used as the issuer during token verification.

Keycloak: https://keycloak:8283/auth/realms/JOC


OIDC Client IDThe Client ID is configured in the OIDC Identity Provider.The Client ID is used for a number of calls to to the OIDC Identity Provider.


OIDC Client Secret

The Client Secret is configured in the OIDC Identity Provider.The Client Secret is used for a number of calls to the OIDC Identity Provider.



OIDC User Name AttributeThe attribute is configured with the OIDC Identity Service.

The attribute is returned by the OIDC Identity Service and identifies the user account. 

  • The following strategy is applied to identify the attribute used to map to the JOC Cockpit account:
    • the URL https://<identity-provider>/.well-known/openid-configuration is called.
    • the response is checked for the object claims_supported
      • if not available or empty then the email attribute will be used
      • if available and if it includes the preferred_username attribute then this attribute will be used.
    • if no attribute has been identified then the email attribute is used.
  • Should this not result in an identifiable user account then users can specify the name attribute such with the OIDC settings. Frequently OIDC Identity Providers support attribute names such as username or email



OIDC ImageAn image can be uploaded that is displayed with the login page.

Optionally an image can be uploaded. .

OIDC Truststore PathThe Path to a truststore.

A truststore can be indicated and has to include an X.509 certificate specified for the Extended Key Usage of Server Authentication for the Identity Provider.

    • For connections to well known OIDC Identity Providers such as Azure® users should specify the path to the Java cacerts truststore file that ships with the Java JDK used with JOC Cockpit.
    • The truststore can include a self-signed certificate or a CA signed certificate. Typically the Root CA certificate is used as otherwise the complete certificate chain involved in signing the Server Authentication Certificate has to be available with the truststore.
    • If this setting is not specified then the JOC Cockpit will use the truststore that is configured with the JETTY_BASE/resources/joc/ configuration file. This includes use of settings for the truststore password and truststore type.
    • The path to the truststore can be specified relative to the JETTY_BASE/resources/joc directory. If the truststore is located in this directory then only the file name is specified, typically with a .p12 or .pfx extension. Other relative locations can be specified using, for example, ../../joc-truststore.p12 if the truststore is located in the JETTY_BASE directory.
    • An absolute path can be specified.
Use of Java truststore: /usr/lib/jvm/java-17-openjdk/lib/security/cacerts
OIDC Truststore PasswordTruststore passwordIf the indicated truststore is protected by a password then the password has to be specified.Use of Java truststore: changeit
OIDC Truststore TypeTruststore type

The type of the truststore is either PKCS12 or JKS (deprecated).

Use of Java truststore: PKCS12

OIDC Login

Once OIDC Identity Services have been configured they are displayed in JOC Cockpit's login screen like this: 


  • OIDC Identity Services are displayed in alphabetical order.
  • If a users clicks the Identity Service in the login screen then the Identity Provider will show a popup window that asks for credentials or the user will be immediately authenticated in case of single sign-on.

OIDC Flows

Register Client

It is necessary for a Client to be registered 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 which is configured in the JOC Cockpit Identity Service.
  • client-secret: The Client Secret which is configured in the JOC Cockpit Identity Service.
  • redirect-urls: The list of allowed URLs for redirection after authentication by the Client. Note that the URL of each JOC Cockpit instance has to be specified for clustered JOC Cockpit instances. For JOC Cockpit, the protocol (HTTP, HTTPS), host and port is specified as the URL, for example https://joc-2-0-primary:4446.

Registration of 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 be considered by JOC Cockpit. Authentication is performed with the given OIDC Identity Service only.
  • OIDC Identity Services cannot be set to be required.

If the Client has previously authenticated with the Identity Provider and 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.

The Identity Provider returns the following to the Client after successful authentication:

  • 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 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.

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

  • Client ID
  • Client Secret
  • ID 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 ID Token has 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. 

Renew Token

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

If the 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. This occurs in case that:

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

The 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 was previously returned by the Identity Provider after successful authentication..

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 in time of the next token renewal.

Single Sign-On

The OIDC Identity Service allows single sign-on for the underlying Identity Provider:

  • Users who previously have been authenticated with the same Identity Provider as used by the OIDC Identity Service can access JOC Cockpit from their browser without specifying credentials.
  • Users who initially authenticate with an Identity Provider by use of JOC Cockpit can open additional tabs in their browser without specifying credentials.
    • If a session is created for a user in the Identity Provider by authentication with JOC Cockpit then this session will last as long as the JOC Cockpit session.
    • If the user's Access Token is revoked in the Identity Provider then the underlying session in the Identity Provider will be continued until the JOC Cockpit session has been terminated either by a logout operation or by reaching the Idle Session Timeout.
    • If the user performs a logout operation from the JOC Cockpit session that was used to authenticate with the Identity Provider then the underlying session in the Identity Provider will be terminated.


  • Log Files
  • 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 in the JS7 - Log Levels and Debug Options article.
    • 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.

  • No labels