Internal documentation only

This page has been marked as draft.

ITRS Analytics (Obcerv)- How to connect Obcerv/Keycloak to Active Directory (AD)

This article may be outdated. There is an ongoing ticket https://itrs.zendesk.com/agent/tickets/373169 and the contents will need to be reviewed.

To be able to connect KeyCloak to Active Directory, you need to access the Keycloak interface.

It is accessible via https://www.obcerv.local/auth (adjusted to your actual DNS name).

• This will take you to the Welcome page. Click “Administration Console” on this page.

• This will take you to the login screen. Enter your admin user name and password you used to set up Keycloak. On a fresh install, this might be the user name “admin” and the password “admin”. You SHOULD change them if this is the case in the ‘Users’ menu in the left-hand side (ask your sysadmin for the credentials used to setup Keycloak if they are different from default ones).
• After successfully logging in, click the “User Federation” menu on the left-hand side to arrive at the following page. Keycloak, User Federation menu (Make sure you use Obcerv realm)

• This page only appears if you are adding a provider for the first time.
• Otherwise, you will see a list of configured providers already in the system. In this case you can add a new provider by selecting one from a list of providers shown at the top-right of the table.
• Select the “ldap” entry from the options displayed.
• The page will automatically open a form to fill in your LDAP connection parameters. The form will initially be empty as shown below:

Settings for Active Directory/AD Copied

• Enter an appropriate name in the “Console Display Name” field.

• Proceed to the “Vendor” drop down list. Select the LDAP vendor that you want to configure. This will usually fill in reasonable defaults for many of the fields. The “Help” icon in Keycloak next to each field provides a good description of what is required as well as example values for AD or LDAP.

• Click “Test Connection” and “Test Authentication”. Both these tests should be successful.

• Click “Save” at the bottom of the page.

• After successfully saving your LDAP settings from the previous section, new buttons will appear next to the “Save” and “Cancel” buttons as shown below.

• Click “Synchronize all users”.

• Shortly afterwards an info box will appear at the top with a success message, and the number of users imported as well as other information. If this step fails for you and you cannot find any reason in your input fields, then you might need to review the Keycloak logs in Debug mode.

• At this point you can successfully view your imported users by clicking the “Users” menu on the left-hand side and then clicking “View all users” on the page that appears.

• If you want to set up SSO for the UI, verify the following for the users:

  • The “Username” column contains the Windows login name
  • The columns “Email”, “First Name” and “Last Name” contain the correct values for all users

Attribute mappers Copied

By default, Keycloak does not copy all attributes it sees in Active Directory. Use the Mappers tab in the user federation admin section to view mappings.

Default attribute mappings:

• email mail
• cn username

To use a value other than CN for logging in, modify the username LDAP Mapper. Set User Model Attribute to the name of the Active Directory field that contains the user name you want to use.

You can set it to whatever attribute is used for user logins in your environment. Examples:

• username

• email

  Caution - later changes

  When you save the settings of the user federation for the first time, Keycloak adds the mappings for the previously entered LDAP settings in the Mappers tab. These have to be updated manually, when you change the settings. This is not done automatically.

Note on “PKIX Path Building Failed” Copied

Active Directory servers may be secured using an organization-managed root certificate rather than a global certificate authority. The error is caused by Keycloak not recognizing the certificate.

To install the certificate into Keycloak, do the following:

keytool -import -noprompt -trustcacerts -alias FQDN-OF-LDAP-SERVER -file "\Path\to\www.example.com.crt" -keystore cacerts

Hint - LDAPS

If you use LDAPS, you have to import the following certificates into your Java Key Store:

• a certificate from the configured LDAP server:

keytool -import -noprompt -trustcacerts -alias <choose-an-alias> -file <root-certificate-file> -keystore <JRE_HOME>\lib\security\cacerts files -storepass changeit

• the root certificate:

keytool -import -noprompt -trustcerts -alias <choose-an-alias> -file <root-certificate-file> -keystore <JAVA_HOME>/lib/security/cacerts -storepass changeit