LDAP user administration
HCL OneTest™ Server uses Keycloak V12.0.4 (https://www.keycloak.org/) to manage and authenticate users.
Existing user databases hold user credentials. Keycloak federates these existing external user databases through the concept of storage providers. By default, Keycloak supports an LDAP and Active Directory storage provider. By adding a storage provider, you can map LDAP user attributes into Keycloak. You can also configure more mappings.
- Set up your LDAP/AD provider as a read-only repository so that HCL OneTest™ Server cannot change it.
- Add and remove users in LDAP/AD and not the Keycloak local user database.
- Import and synchronize your LDAP/AD users to your Keycloak local database.
- Map a login style name, for example,
user1@server.com
, by using theUserPrincipalName
attribute in LDAP/AD to ausername
in Keycloak. If you want the full name of the user as your login style, use thecn
attribute in LDAP/AD.Note: The LDAP/AD user name attribute must match the LDAP/AD provider user name attribute (Username LDAP attribute) in Keycloak for the LDAP/AD provider to connect with Keycloak.
The following sections use these best practices to guide you to set up Keycloak to connect to your LDAP/AD HTTP server.
LDAP provider selection in Keycloak
You can use the Keycloak Admin Console to add an LDAP/AD provider.
https://<fully-qualified-dns-nam>/auth/admin
. The
default user name for the Keycloak administrator is keycloak
.
The password is randomly generated when you installed the HCL OneTest™ Server software. You can
see the password by using the following kubectl command:
kubectl get secret -n test-system {my-ots}
-keycloak-postgresql -o jsonpath="{.data.password}" | base64 --decode; echo
{my-ots}
with
the release name of your choice.After you log in, you can go to the User Federation page to add your provider.
You want to select the provider named ldap from the list. From the Add user federation provider page, you can use a form to complete your LDAP/AD connection parameters.
Required settings for a successful connection to your LDAP/AD provider
The form includes many fields and several fields include default values. Tables describe the important fields that you must complete to ensure a successful HTTP connection to your LDAP/AD provider.
Field | Description |
---|---|
Console Display Name | You want to make your console name recognizable, for example, Test Server LDAP/AD Provider. This name is shown in the Keycloak Admin Console. |
Priority | The priority must be set to 0 so that when a user logs in to HCL OneTest™ Server, Keycloak looks up the user first in the list of users managed in the LDAP/AD user database. If the user is not found in your LDAP/AD user database, Keycloak then looks up the user in the local Keycloak user database. |
Import Users | You want to leave import users ON so that
users in your LDAP/AD user database are synchronized (imported)
automatically into the Keycloak local user database. The import uses the
settings that you are defining now. After the initial import, when you add a user to your LDAP/AD user database and that user logs in to HCL OneTest™ Server, the LDAP/AD provider imports the LDAP/AD user into the Keycloak user database and authenticates the user against the LDAP/AD password. Similarly, after the initial import, when you remove a user from your LDAP/AD user database that user cannot log in to HCL OneTest™ Server.Note: For consistent user management, continue to manage users in
your LDAP/AD user database.
|
Edit Mode | Make sure that edit mode is set to
READ_ONLY. This setting means that your
LDAP/AD user database is read-only. No user data defined through the
mapping of attributes in Keycloak such as the
This read-only setting also means that a new user cannot sign up from HCL OneTest™ Server as no user data can be written to your LDAP/AD user database. |
Vendor | You want to select Active Directory from the list of vendors. Many fields complete with default values based on this selection. |
Field | Description |
---|---|
Username LDAP attribute | You can use the default value cn for the
username , which is a first name, last name, or you
can use userPrincipalName , which is username@domain.
You might want a login that matches your company style. For example, you might prefer joetester@mycompany.com instead of Joe Tester. If you do make this change the
|
User Object Classes | Because LDAP user records are found based on a user object class,
you must set the User Object Classes to User .
|
Connection URL | So that Keycloak can connect to your LDAP/AD user database, you
must enter your LDAP/AD URL, for example,
ldap://<hostname>.<domain>
Make sure that you test the connection and confirm that the connection is successful. |
Users DN | You must provide the directory where the LDAP users are listed, for example,
cn=Users,dc=OneTest,dc=COM . |
Custom User LDAP Filter | You can filter your LDAP/AD users to import a subset of all your
LDAP users. For example, you can set up a RTAS user group for your
LDAP/AD user database such that only those users are imported to
Keycloak.
|
Bind DN Bind Credential |
You must also provide the LDAP/AD user database administrator user
ID for BIND DN and password for the
BIND Credential. These credentials are used
by Keycloak to access the LDAP/AD user database. Make sure that you test the authentication and confirm that the authentication is successful. |
You can save the settings, which create your LDAP/AD provider.
Mappers
Keycloak uses mappers to map the user attributes defined in the Keycloak user model such as username and email to the corresponding user attributes in the LDAP/AD user database. By default, when you saved your settings and created your LDAP/AD provider, the following mappers were created.
The username attribute that you specified in the Username LDAP attribute must match the username t attribute defined in the Keycloak mapper for the LDAP/AD user database to connect with Keycloak.
Because you changed the Username LDAP attribute from the
default value cn
to userPrincipalName
,
Keycloak made the same change in the mapper called
username to match.
User synchronization
You must import all users from your LDAP/AD user database by using the option to Synchronize all users. Users are imported based on your saved settings when you set up your LDAP/AD provider.
A successful import is followed by a success message with the number of users imported.
You can view all the LDAP/AD database users that were imported and authenticated from the Users page in the Keycloak Admin Console.
Users are listed with ID, Username, Email, Last Name, and First Name. The ID is generated by Keycloak. The value of the other attributes is fetched from the LDAP/AD user database by using mappers.
- The User logon name field under the Account tab of that LDAP/AD user is blank.
- The value of the Custom User LDAP Filter field to import only a subset of all LDAP users does not match with the LDAP set of users.
You can check the log file of the Keycloak pod to understand the reason for the failed import.
- Run the following command to view the list of all
pods:
kubectl get pods -n test-system
- Identify the Keycloak pod
ssocloak-0
. - Run the following command to view the log of the Keycloak
pod:
kubectl logs {my-ots}-ssocloak-0 -n test-system
Note: Where, {my-ots} is the name of the release that is provided during the installation of the server software.The log file of the Keycloak pod is displayed.
12:49:00,535 ERROR [org.keycloak.storage.ldap.LDAPStorageProviderFactory] (default task-40)
Failed during import user from LDAP: org.keycloak.models.ModelException: User returned from LDAP has null username!
Check configuration of your LDAP mappings.
Mapped username LDAP attribute: userPrincipalName, user DN: CN=DefaultAccount,CN=Users,DC=ONETEST,DC=COM,
attributes from LDAP: {whenChanged=[20190527143130.0Z], whenCreated=[20190527143130.0Z], cn=[DefaultAccount],
userAccountControl=[66082], pwdLastSet=[0]}