- Summary
- FAQ
- When configuring Keycloak, should we delete local authentication mode users?
- How should the account used to access the LDAP system from Keycloak be configured?
- What happens when users required to use CAST Imaging Console are added to the LDAP group dedicated to CAST, does the admin need to perform a synchronization in Keycloak?
- What happens if a user password changed in LDAP?
- What happens if a user is deleted from LDAP?
- Step 1 - Configure LDAP settings
- Step 2 - Test connection and authentication
- Step 3 - Configure LDAP group settings
- Step 4 - Test user login
Summary
Information about how to configure Keycloak to interact with your LDAP directory.
Enabling and configuring a new authentication mode will NOT disable any existing authentication modes configured in Keycloak. Therefore, CAST highly recommends that you disable all existing authentication methods before adding a new one: in most cases this will involve disabling or deleting the "local" users provided with CAST Console or any that you have created yourself:
FAQ
When configuring Keycloak, should we delete local authentication mode users?
CAST recommends that when switching to a new authentication mode that all existing modes are disabled, and in the case of local authentication, you should disable or delete the existing users (see note at the top of this page).
How should the account used to access the LDAP system from Keycloak be configured?
CAST recommends creating a dedicated LDAP "service" account to be used exclusively for configuring access between Keycloak and LDAP. This service account should be a member of an LDAP group dedicated to CAST (i.e. only users required to access CAST Imaging Console should be added to this group).
What happens when users required to use CAST Imaging Console are added to the LDAP group dedicated to CAST, does the admin need to perform a synchronization in Keycloak?
CAST recommends that users are imported into Keycloak (into its own database), otherwise some functionality is lost (typically API Key access to CAST Console because the API key needs to be stored with the user in the Keycloak database). When users are configured to be imported into the Keycloak database, this action is only performed the very first time a user logs into CAST Imaging Console. As such, CAST also recommends that a periodic synchronization is configured in Keycloak. This can be done by enabling the Peridoc Full Sync option (this performs a full synchronization every 24 hours).
What happens if a user password changed in LDAP?
All authentication is performed against the LDAP database (not the Keycloak database), therefore if the user changes his/her password in LDAP, then the change is immediate when attempting to access CAST Console via Keycloak (they will need to use the new password).
What happens if a user is deleted from LDAP?
If the user is deleted from LDAP then that user will no longer be able to login to CAST Console via Keycloak (because all authentication is performed against the LDAP database (not the Keycloak database)) - this occurs immediately. The user's details will remain in the Keycloak database until the next synchronization, after which, it will be removed automatically.
Step 1 - Configure LDAP settings
Click the User Federation option on the left then choose the LDAP provider in the dropdown :
Click to enlarge
Fill in the fields as follows (see also https://www.keycloak.org/docs/latest/server_admin/#_ldap):
| Field | Description |
|---|---|
| Enabled | Set this to ON to enable the LDAP integration. |
| Console Display Name | By default this is set to "ldap", but you are free to choose a different name - it is simply a display name. |
| Priority | Leave this set to 0 - this sets the priority for user lookup when multiple authentication methods are handled by Keycloak. |
| Import Users | This option allows you to import your LDAP users into the Keycloak database stored on your CAST Storage Service/PostgreSQL instance. CAST recommends that this option is set to ON otherwise the following functionality will be lost:
When set to ON, the first time a user logs in, the LDAP provider imports the LDAP user details into the Keycloak database and validates the LDAP password. This first time a user logs in is the only time that Keycloak will import the user. Therefore, if you click the Users menu option and then click the View all users button, you will only see the LDAP users that have authenticated at least once via Keycloak:
Keycloak imports users this way, so that a single user login operation does not trigger an import of the entire LDAP user database and cause performance issues. Note that by default the user's details will only be imported once when they first login, therefore if users are updated in the LDAP database, these details are not automatically synchronized to the Keycloak database unless you either:
|
| Edit Mode | This option determines how Keycloak will handle the remote LDAP database:
|
| Sync Registrations | This option determines whether Keycloak will synchronize users created directly in Keycloak back to the remote LDAP database. CAST recommends that this should be set to OFF since the LDAP database should be the only reference. |
| Vendor | Choose the type of remote LDAP database you are using - this setting will automatically populate the following fields using the most common vendor specific settings (but these can be customized if required):
|
| Username LDAP attribute | Populated automatically based on the type of LDAP database you have selected in the Vendor field, but can be customized if required. This is the name of the LDAP database attribute, which (when users are imported) will be mapped as the username in the Keycloak database. If users are not imported into Keycloak, this is what users will use to log in to the CAST product:
|
| RDN LDAP attribute | Populated automatically based on the type of LDAP database you have selected in the Vendor field, but can be customized if required. This is the name of the LDAP database attribute, which is used as the RDN (top attribute) of a typical user Distinguished Name. Usually this is the same as Username LDAP attribute, however it is not a required attribute in the LDAP database. For example for Active Directory, sometimes 'cn' is used as the RDN attribute when the username attribute might be 'sAMAccountName'. |
| UUID LDAP attribute | Populated automatically based on the type of LDAP database you have selected in the Vendor field, but can be customized if required. This is the name of the LDAP database attribute, which is used as a unique object identifier (UUID) for objects in the LDAP database. For many LDAP server vendors, it is 'entryUUID'; however some are different. For example for Active Directory it should be 'objectGUID'. If your LDAP server does not support the notion of UUID, you can use any other attribute that is supposed to be unique among LDAP users in tree. For example 'uid' or 'entryDN'. |
| User Object Classes | Populated automatically based on the type of LDAP database you have selected in the Vendor field, but can be customized if required. These are all the values of the LDAP database 'objectClass' attribute for users in the LDAP database, separated with a comma. For example:
|
| Connection URL | Enter the URL for your remote LDAP server. For example use a FQDN (fully qualified domain name), host name, IP address etc.:
|
| Users DN | This the DN (Distinguished Name) of the Organisational Unit (OU) in your LDAP database in which your users are stored. For example: Click to enlarge
|
| Custom User LDAP Filter | Additional LDAP Filter for filtering searched users. Leave this empty if you don't need an additional filter. If you do need to filter, make sure that the value starts with '(' and ends with ')' |
| Search Scope | Set the level that Keycloak should search the entry set in the Users DN field. Usually you should set this to One Level unless your users are located in multiple sub OUs in which case choose Subtree. |
| Bind Type | Type of authentication used in the LDAP bind operation. Typically you should leave this set to simple. |
| Bind DN | Enter the DN (Distinguished Name) of the LDAP service account that will be used for the LDAP bind operation. |
| Bind Credentials | Enter the password for the LDAP service account that will be used for the LDAP bind operation. |
When complete, click the Save button:
Step 2 - Test connection and authentication
Use the following buttons to check that the connection to the LDAP server functions and that the service account can login - if not you may need to revise the values you have supplied:
Step 3 - Configure LDAP group settings
If you need to grant CAST Console/embedded Dashboard permissions to LDAP groups (this is highly recommended) rather than or as well as individual LDAP users, you will need to configure a mapper specifically to synchronize your LDAP groups and make them available in Keycloak. To do so click the Mappers tab in your LDAP User Federation setting:
Then click the Create button:
In the Mapper Type field, choose the group-ldap-mapper option:
And fill in as below:
| Field | Description |
|---|---|
| Name | This is simply a display name - enter as required. |
| Mapper Type | Must be set to group-ldap-mapper. |
| LDAP Groups DN | This the DN (Distinguished Name) of the Organisational Unit (OU) in your LDAP database in which your groups are stored. For example: Click to enlarge
|
| Group Name LDAP Attribute | Populated automatically, but can be customized if required. This is the name of the LDAP database attribute, which is used in group objects for the name and RDN of the group. In the vast majority of cases, this will be "cn" (Common Name) - typically group objects may have a Distinguished Name such as "
|
| Group Object Classes | Populated automatically, but can be customized if required. These are all the values of the LDAP database 'objectClass' attribute for your groups in the LDAP database, separated with a comma. Groups will be identified by Keycloak if at least one of the values in this field is defined in the LDAP database 'objectClass' attribute for a given group. In the following example groups will be imported into the Keycloak database if at least one of the values in this field is defined in the LDAP database 'objectClass' attribute for a given group:
|
| Preserve Group Inheritance | This option determines whether your LDAP group inheritance organisation is mirrored in Keycloak. In other words, if you have nested groups, you should ensure this option is set to ON. If set to OFF, all groups will be mirrored in Keycloak in "flat mode", i.e. all at one level, ignoring the nested organisation. |
| Ignore Missing Groups | This option should always be set to ON. |
| Membership LDAP Attribute | Populated automatically, but can be customized if required. This is the name of the LDAP database attribute, which is used for group membership mappings. Usually this will be "member". However if the Membership Attribute Type option (see below) is set to "UID" then Membership LDAP Attribute could be "memberUid". |
| Membership Attribute Type | Select either UID or DN:
|
| Membership User LDAP Attribute | Populated automatically, but can be customized if required. This option is ignored if the Membership Attribute Type option (see above) is set to DN. This is the name of the LDAP database attribute for the user, which is used for membership mappings. Usually it will be "uid" . For example if Membership User LDAP Attribute is set to is "uid" and the LDAP group has "memberUid: john", then it is expected that that particular LDAP user will have the attribute "uid: john". |
| LDAP Filter | Additional LDAP Filter for filtering searched groups. Leave this empty if you don't need an additional filter. If you do need to filter, make sure that the value starts with '(' and ends with ')' |
| Mode | This option determines how Keycloak will handle groups:
|
| User Groups Retrieve Strategy | This option determines how Keycloak should retrieve groups from the LDAP database:
Note that if a user already exists in the Keycloak database (i.e the user has already logged in before the groups mapper was setup), then the group membership details will not be updated for the given user. In this case, the user needs to be deleted from the Keycloak database (using the "Users" option in the left panel) - the group membership details will be retrieved when the user next logs in. |
| Member-Of LDAP Attribute | Populated automatically, but can be customized if required. This option is ignored if the User Groups Retrieve Strategy option (see above) is set to anything other than GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE. It specifies the name of the LDAP database attribute on the LDAP user, which contains the groups, which the user is member of. Usually it will be 'memberOf' and that's also the default value. |
| Drop non-existing groups during sync | If this option is set to ON then during retrieval of groups from the LDAP database, only those Keycloak groups (i.e. groups created directly in Keycloak) which also exist in LDAP will be retained. All others will be deleted. CAST recommends setting this option to ON if you only care about groups set in your LDAP database. |
| Groups Path | This is the path where the LDAP groups will be created in the Keycloak database and is set by default to "/" (i.e. the root). Root means that the groups will be created under this default entry:
|
When created, click Sync LDAP Groups to Keycloak and the groups will be imported into the Keycloak database:
Click to enlarge
You can check whether the groups have been successfully retrieved using the following interface:
Step 4 - Test user login
Finally you should test that an LDAP user can successfully log into CAST products and if you have set Import Users to ON, that their details are correctly stored in the Keycloak database:
That's it, the configuration is complete for LDAP and you can now log in as explained in Initial login to AIP Console - v. 2.x.
By default users/groups from LDAP will not have any roles assigned to them, so at least one LDAP user (or group) will need to be granted the admin and dashboards_admin roles (this will grant the global Console admin role and the global dashboards role (access all applications)) via the Keycloak role mappings section in the first instance:
Click to enlarge
Any additional users/groups that need to log in to Console or access CAST Dashboards will also need to be granted appropriate access roles:
- either the admin or application_owner role to access Console (admin grants full rights to everything, application_owner grants only rights to access applications and not the Admin Center).
- any one of the Dashboard roles as discussed here:
- dashboards_admin
- dashboards_exclusion_manager
- dashboards_quality_automation_manager
- dashboards_quality_manager
- Note that users assigned the application_owner role will not be able to view existing applications created by other users. To allow them to do so, you will need to assign them the resource level resource owner role in Console itself, see Administration Center - Security - User Roles.
