...

• The JS7 - Identity Services offer local 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.
  • Any OIDC compliant Identity Provider Providers can be used for authentication., for example Microsoft Azure®.
  • JS7 implements a client for use with OIDC Identity ProvidersThis 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.

• Display feature availability
  StartingFromRelease 2.5.0

  • Jira
    server SOS JIRA columnIds issuekey,summary,issuetype,created,updated,duedate,assignee,reporter,priority,status,resolution columns key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution serverId 6dc67751-9d67-34cd-985b-194a8cdc9602 key JOC-1525

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

...

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

Explanation:

• Service Type: OIDC-JOC
  • 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 Application.
    • This is provided by the Accounts View where the a the roles are assigned to the known accounts .
  • 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.
• 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 accounts view is not provided when using OIDC 
    • The assignment of roles to accounts is provided by the group roles mapping editor in the "Manage Settings View" of the OIDC Identity Service.
  • The JOC Cockpit does not store user accounts and role assignments. This is done by the the OIDC Identity Provider
  • The JOC Cockpit does not know passwords of user accounts or the access tokens of successful authentication.

Group roles mapping

Roles are assigned to accounts via the editor for assigning group roles in the "Manage settings" view of the OIDC identity service.

A list of claims containing the groups configured in the OIDC provider can be defined. The available claims can be checked by checking the JW token during registration.

During assignment, the groups from the OIDC provider are assigned to the roles defined in the identity service. Any number of roles can be assigned to each group. 

Image Added

Identity Service Configuration

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

Image Modified

Add Identity Service

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

Image Modified

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

Image Modified

Explanation:

...

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:

Image Modified

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 a number of settings have to be specified:

Example for Keycloak

Image Modified

Example for Azure

Image Added

Explanations:

OIDC Login

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

Image Modified

Explanation:

...

OIDC Flows

Register Client

It is required to register 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 that which is configured in the JOC Cockpit Identity Service.
• client-secret: The Client Secret that which is configured in the JOC Cockpit Identity Service.
• redirect-urls: The list of allowed URLs for redirection after authentication by the Client. Consider Note that for clustered JOC Cockpit instances 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.

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

...

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.

In case that If the Client has previously did authenticate authenticated 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.

After successful authentication the 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. 

...

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

...

Access Tokens and ID Tokens include the 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.

...

• 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 is will be continued until the JOC Cockpit session is 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 is will be terminated.

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

...