...

• The JS7 - Identity Services offer integration with Keycloak® Authentication Server.
• The Keycloak Keycloak® Identity Service integration is available from JOC Cockpit:
  • This requires Keycloak® to be installed and operated. Keycloak® is not a built-in Identity Service Provider and does not ship with JS7.
  • JS7 implements a REST client for use with Keycloak® 16.0 and newer.

...

• Enabled: On
• Direct Access Grants Enabled: On
• Client Protocol: openid-connect
• Access  Type: confidental
• Credentials/Client Authenticator: Client ID and Secret. 
• Roles: New roles can be added to the Client.

...

• Realms/Tokens
  • Access Token Lifespan: After When exceeding the lifespan an access token will expire. The access token is automatically renewed by JOC Cockpit 20s before expiration. If Client Session Idle is shorter than Access Token Lifespan Lifespan then theaccess token will be renewed 20s before Client Session Idle expires.
  • Client Session Idle: After the idle timeout the session will expire. The access token and implicit implicitly the session is are automatically renewed by JOC Cockpit 20s before idle timeout.
  • Client Session Max: After this period a session can no longer be renewed. It is recommended to set this value to a larger value then the session timeout configured in JOC Cockpit.
  • SSO Session Idle: Used when Client Session Idle is not set.
  • SSO Session Max: Used when Client Session Max is not set.

• Keycloak access tokens are created with the following restrictions:
  • Time to Live (TTL):
    • The access token will expire after the given period (Access Token Lifespan).
    • The session will expire after the given period (Client Session Idle).
    • The Identity Service renews the access token 20s before expiration of the session or of the access token, this step is performed until Session Max is reached. This requires that the access token's TTL exceeds 60s and that the Keycloak permission for renewal of an access token by its owner is in place.
  • Maximum Time to Live:
    • The access token's overall lifetime is limited (Session Max), renewals cannot take place after the specified period.
• If an access token cannot be renewed by the Identity Service then the user session is terminated and the user is forced to login and to specify credentials.
  • This happens in the event that the maximum TTL is exceeded or that the token is revoked.
  • Keycloak administrators should check for reasonable values of the session TTL (Session Idle) and the Access Token Lifespan, maybe not less than 300s, and the maximum TTL (Session Max) , maybe typically at least 15 minutes, as otherwise users will have to repeatedly login quite frequently.
• The JOC Cockpit handles the idle timeout of user sessions independently from Keycloak, see JS7 - Identity Services.
  • If the idle timeout is exceeded then the user session is terminated.
  • The Identity Service will revoke the access token with the Keycloak Server on termination of the user session.

Identity Service Configuration

The The Image Added icon in the JOC Cockpit Manage Identity Services page from the user menu of an administrative account is provided for the configuration of Identity Servicesmain 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 Keycloak product has to be installed and has to be accessible for JOC Cockpit and
• the following settings have to be specified: 
  
  

Image Modified

Explanation:

• Keycloak URL: the base URL for which the Keycloak REST API is available. 
• Keycloak Administration Account: A Keycloak account with an administrative role that is assigned the realm-management.view-clients and realm-management.view-users roles.
  • The administration account is used to retrieve the roles for a Keycloak account and for renewing access tokens.
• Keycloak Administration Password: The password for the Keycloak Administration Account.
• Keycloak Truststore Path:  Should the Keycloak Server be configured for HTTPS connections then the indicated truststore has to include an X.509 certificate specified for the Extended Key Usage of Server Authentication.
  • The truststore can include a selfPrivate CA-signed certificate Certificate or a Public CA-signed certificateCertificate. Typically the Root CA certificate Certificate is used as otherwise the complete certificate chain involved in signing the Server Authentication Certificate has to be available with the truststore.
  • If the Keycloak Server is operated for HTTPS connections and this setting is not specified then the JOC Cockpit will use the truststore that is configured with the JETTY_BASE/resources/joc/joc.properties configuration file. This includes use of settings for the truststore password and truststore type.
  • The path to the truststore is 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 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 cannot be specified and a path cannot be specified that lies before the JETTY_BASE directory in the file system hierarchy.
• Keycloak Truststore Password: If the Keycloak Server is configured for HTTPS connections and the indicated truststore is protected by a password then the password has to be specified.
• Keycloak Truststore Type: If the Keycloak Server is configured for HTTPS connections then the type of the truststore has to be specified being either PKCS12 or JKS (deprecated).
• Keycloak Clients are entities that request Keycloak to authenticate a user account. For example, an application such as JOC Cockpit acts as a Client to the Keycloak Server. Clients use Keycloak to authenticate and to provide a single sign-on solution.
  
  • Keycloak Client ID and Keycloak Client Secret are used for 
    • requesting an access token
      • for user authentication,
      • for administrative access,
    • validating an existing access token,
    • renewing an existing access token.
  • Keycloak Client Secret: The Client owns a secret which needs to be known by both the Keycloak Server and the JOC Cockpit.
• Keycloak Realm: A realm manages a set of users, credentials, roles, and groups. A user belongs to a realm and performs a login to a realm. Realms are isolated from each other, they manage and authenticate exclusively user accounts that they control.

...