Page History
...
- The JS7 - Identity Services offer integration with HashiCorp® Vault authentication serverKeycloak® Authentication Server.
- The Vault Keycloak® Identity Service integration is available from JOC Cockpit:
- This requires HashiCorpKeycloak® Vault to be downloaded, installed and operated by the user. Vault Keycloak® is not a built-in Identity Service Provider and does not ship with JS7.
- JS7 implements a REST client for use with HashiCorp® Vault 1.7Keycloak® 16.0 and newer.
Identity Service Types
The following integration levels are available from Identity Service Types that can be used with VaultKeycloak:
Identity Service | Identity Service Configuration Items | JOC Cockpit Configuration | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Service Type | Built-in | User Accounts/Passwords stored with | User Accounts/Passwords managed by | Roles/Permissions stored with | Roles->User Accounts Mapping managed with | Roles Mapping | |||||||
VAULT KEYCLOAK | no | Vault Keycloak ServerVault | Keycloak Server | JS7 Database | Vault Keycloak Server | Mapping of Vault Policies Keycloak Roles to JOC Cockpit Roles | |||||||
VAULTKEYCLOAK-JOC | no | Vault Keycloak ServerVault | Keycloak Server | JS7 Database | JOC Cockpit | Mapping of user accounts and roles with JOC Cockpit | VAULT-JOC-ACTIVE | noVault Server | Vault Server / JOC Cockpit | JS7 Database | JOC Cockpit | Mapping of user accounts and roles with JOC Cockpit |
Explanation:
- Service Type:
VAULT
KEYCLOAK
- Management of user accounts and passwords is performed by the Vault Keycloak Server.
- In addition, an automated mapping of policies roles - assigned a user account in Vault Keycloak - to roles in JOC Cockpit roles takes place.
- The JOC Cockpit does not know any user accounts, passwords and role assignments as this information is managed with Vault onlyKeycloak exclusively.
- Service Type:
VAULTKEYCLOAK-JOC
- Management of user accounts and passwords is performed by the Vault Keycloak Server.
- The assignment of roles to user accounts is performed with The the JOC Cockpit and is stored with the JS7 database.
- The JOC Cockpit knows user accounts and role assignments. The JOC Cockpit does not know passwords as this information is managed with Vault only
- Service Type:
VAULT-JOC-ACTIVE
- Management of user accounts and passwords is performed by the JOC Cockpit. The JOC Cockpit forwards user accounts and passwords to the Vault Server. The JOC Cockpit stores users accounts (not: passwords) in the JS7 database.
- The assignment of roles to user accounts is performed with The JOC Cockpit and is stored with the JS7 database.
- The JOC Cockpit knows user accounts and role assignments. The JOC Cockpit temporarily knows passwords until this information is forwarded to Vault.
...
- Keycloak exclusively.
Keycloak Authentication Methods
JS7 supports the following authentication methods with VaultKeycloak:
- Username Account & Password
- LDAP
- It is not required to use Vault Keycloak to connect to an LDAP Directory Service as there is a built-in in JS7 - LDAP Identity Service for this purpose.
- This authentication method can be used with the
VAULT
KEYCLOAK
Identity Service Type only.
JS7 does not support cloud based authentication methods with Vault as such methods are typically used for engineering and administrative roles with cloud services that are not related to an application such as JS7.
Vault Server Configuration
...
If the VAULT-JOC-ACTIVE
Identity Service Type is used then an Application Role has to be created and an access token has to be generated with Vault that is added to the JOC Cockpit configuration of the Vault Identity Service.
...
Keycloak.
Keycloak Server Configuration
The following objects have to be in place with Keycloak to enable authentication from JOC Cockpit:
- Realm Configuration
- Client Configuration
- User Accounts
- Roles
- Roles are used with the Identity Service Type
KEYCLOAK
. Roles in Keycloak are not applicable when using the Identity Service TypeKEYCLOAK-JOC.
- Roles are used with the Identity Service Type
Realm
It is recommended to create a new Realm and not to use the Master Realm.
If no Keycloak Realm is present then it can be added in Keycloak. The default settings are sufficient. The Realm has to be enabled.
Client
If no Keycloak Client is present then it can be added in Keycloak.
- 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.
Roles
An administrative role has to be added to the Realm. The administrative role is assigned the following Client Roles:
- realm-management.view-clients
- realm-management.view-users
If the KEYCLOAK
Identity Service Type is used then the names of roles in Keycloak have to match the roles in JOC Cockpit.
If the KEYCLOAK-JOC
Identity Service Type is used then roles in Keycloak are not considered. Instead roles are assigned to accounts in JOC Cockpit..
User Accounts
Administrative account
- The Keycloak administrative user account has to use password credentials.
- The Keycloak administrative user account is assigned the "admin" role.
JOC Accounts
For each account that should be able to login into JOC Cockpit, a user account has to be added.
- Enabled: On
- Required User Actions: none
- Email Verified: Off
- Credentials: Password
- Credentials Temporary: Off
Anchor | ||||
---|---|---|---|---|
|
Username & Password
...
Account & Password
- If the
VAULT
KEYCLOAK
Identity Service Type is used then:- user accounts are managed exclusively by VaultKeycloak,
- policies roles have to be set up in Vault Keycloak with names that exactly match the names of roles in the JOC Cockpit.
- a user account will be assigned the JOC Cockpit roles matching policy Keycloak role names when performing a login to the JOC Cockpit.
- it is not required to add specific permissions to policies roles with VaultKeycloak.
- If the
VAULTKEYCLOAK-JOC
Identity Service Type is used then:- user accounts are managed by VaultKeycloak.
- user accounts are added to the JOC Cockpit to allow assignment of roles:
- user accounts in Vault Keycloak and in the JOC Cockpit have to match as otherwise the user account is not assigned a role.
- no passwords are managed by the JOC Cockpit.
VAULT-JOC-ACTIVE
Identity Service Type is used then:- user accounts are managed by the JOC Cockpit and are stored with Vault.
- user accounts are assigned roles with the JOC Cockpit
- Keycloak exclusively.
LDAP
- It is not necessary required to use Vault Keycloak to connect to an LDAP Directory Service as there is the built-in in JS7 - LDAP Identity Service for this purpose.
- The authentication method has to be added to VaultKeycloak.
- The path of the Authentication Method has to be added to the Identity Service configuration in JOC Cockpit.
- Authentication with the LDAP authentication service in Keycloak is possible using the
user federation provider
LDAP in Keycloak.
- The
KEYCLOAK
TheVAULT
Identity Service Type has to be used, meaning that:- user accounts are managed with VaultKeycloak.
- user accounts are added to the JOC Cockpit to allow assignment of roles:
- user accounts in Vault Keycloak and in the JOC Cockpit have to match as otherwise the user account is not assigned a role.
- no passwords are managed by the JOC CockpitKeycloak exclusively.
Access Tokens
When a user logs in to the JOC Cockpit then user credentials are forwarded to the Vault Keycloak Server that authenticates the user and returns an access token.
- Realms/Tokens
- Access Token Lifespan: 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 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 implicitly the session 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 Vault access tokens are created with the following restrictions:
- time Time to live Live (TTL):
- the The access token will expire after the given period ,(Access Token Lifespan).
- The session will expire after the given period (Client Session Idle)
- The the Identity Service renews the access token 60s 20s before expiration of the session or of the access token, this step is performed for an arbitrary number of renewalsuntil Session Max is reached. This requires that the access token's TTL exceeds 60s and that the Vault Keycloak permission
self
for renewing a for renewal of an access token by the token its owner to be is in place.
- maximum time Maximum Time to liveLive:
- the The access token's overall lifetime is limited (Session Max), renewals cannot take place after the specified period.
- time Time to live Live (TTL):
- 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 of that the maximum TTL being is exceeded or that the token has been is revoked.
- Vault 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 , maybe (Session Max) typically at least 15 minutes, as otherwise users would will have to repeatedly login quite frequently.
- The JOC Cockpit handles the idle timeout of user sessions independently of Vaultfrom Keycloak, see JS7 - Identity Services.
- If the idle timeout is exceeded then the user session is terminated.
- The Identity Service tries to will revoke the access token . This requires the Vault permission
self
to revoke a token by the token owner.
- The Identity Service does not make use of Vault child tokens.
Identity Service Configuration
- with the Keycloak Server on termination of the user session.
Identity Service Configuration
The icon in the JOC Cockpit main menu is used to select the Manage Identity Services pageThe JOC Cockpit Manage Identity Services page from the user menu of an administrative account is provided for the configuration of Identity Services:
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 can be selected as available from the above matrixlist. - The
Ordering
specifies the sequence in which a login is performed with available Identity Services. - The
Required
attribute specifies if login with the respective Identity Service is required to be successful, for example if a number of Identity Services are triggered on login of a user account. - The
Identity Service Authentication Scheme
allows to selectsingle-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 a Vault Keycloak Identity Service it is necessary required to add settings for the Vault Keycloak integration from the Identity Service's Manage Settings action menu item:
For use of the HashiCorp® Vault Identity with the Keycloak Identity Service:
- the Vault Keycloak product has to be installed and has to be accessible for JOC Cockpit and
- the following settings have to be specified:
Explanation:
Vault Keycloak URL
: the base URL for which the Vault Keycloak REST API is available.Vault Authentication Method Path
: the path specifies the Vault Authentication Method to be used, see the Authentication Methods section above.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 theKeycloak Administration Account.
Keycloak Vault Truststore Path
: Should the Vault 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 Vault 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 theJETTY_BASE
directory. An absolute path cannot be specified and a path cannot be specified that lies before theJETTY_BASE
directory in the file system hierarchy.
Vault Keycloak Truststore Password
: If the Vault the Keycloak Server is configured for HTTPS connections and the indicated truststore is protected by a password then the password has to be specified.Vault Keycloak Truststore Type
: If the Vault the Keycloak Server is configured for HTTPS connections then the type of the truststore has to be specified being eitherPKCS12
orJKS
(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
andKeycloak 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.
- requesting an 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.Vault Application Token
: The application token setting is available only if theVAULT-JOC-ACTIVE
Identity Service Type is used.- The JOC Cockpit requires this token in order to manage users with Vault. This token has to be created with Vault, see the Application Role section above. This token allows JOC Cockpit to access the Vault REST API to manage user accounts. This token is not used for login of users.
Logging
- 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 the user accounts involved are logged to the
JETTY_BASE/logs/audit.log
file.
- Identity Services log output to the
- 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.
...