User federation
Note
Please use the ITRS Analytics IAM app to manage user access, roles, and permissions across the ITRS Analytics platform. It provides centralized authentication and integration with identity providers.
You can import users from an external system into Keycloak, and then map user roles to ensure that the users that are imported into ITRS Analytics have the appropriate user and admin roles.
Note
Not all role mapper types are available in the version of Keycloak used in ITRS Analytics Platform 1.4.x and below.
Types of user federations supported by Keycloak Copied
There are two types of federations in Keycloak: LDAP federation and IDP federation.
LDAP federation typically refers to an external Active Directory connected via LDAP, where Keycloak can authenticate users against.
IDP federation delegates using other IDPs as a source of authentication, such as Google, Amazon, or GitHub. Keycloak itself can be set up as an IDP, and you can use it to authenticate your users as well.
Configure LDAP or IDP federation Copied
If you decide to use LDAP or IDP federation, you need to configure the realm. Once configured, you should then manage user permissions and access (see Federated user roles).
To configure user federation setup in Keycloak:
- Navigate to the
itrs-analyticsrealm in Keycloak by clicking itrs-analytics in the top-left drop down menu. - Do the following:
-
LDAP: click User federation on the left-side menu. Click Add new provider, and then select a supported service. Provide your settings.
For more information, see LDAP and Active Directory in Keycloak documentation.
-
IDP: click Identity providers on the left-side menu. Click Add provider, and then select a supported service. Provide your settings.
For more information, see OpenID Connect v1.0 Identity Providers in Keycloak documentation. Please note that SAML is not currently supported for LDAP or IDP.
Trust a private certificate authority for LDAPS Copied
Keycloak trusts public certificate authorities only. If your LDAP or Active Directory server uses LDAPS and presents a certificate signed by your organization’s certificate authority (CA), Keycloak cannot verify that server. Test connection fails with SSLHandshakeFailed, and the Keycloak log shows PKIX path building failed.
Use this procedure on ITRS Analytics Platform 2.18.13 and later. The Secret name corporate-ca and the file name corporate-ca.pem below are examples. Use your own names.
To make Keycloak trust your CA:
-
Create a Secret in the ITRS Analytics namespace before you apply the configuration or start the upgrade. Store only the CA certificate at the key
tls.crt. Use a PEM file, which is a text file that begins with-----BEGIN CERTIFICATE-----. Do not include the directory server certificate or its private key.kubectl create secret generic corporate-ca \ --from-file=tls.crt=corporate-ca.pem \ -n <namespace> -
Set
iam.keycloak.proxyCaSecretto the name of that Secret.-
For KOTS and embedded cluster installations, add the following to Advanced Settings > Helm Chart Values Override. The top-level
iaxkey is the chart name. The nestediaxkey is the chart values alias required since ITRS Analytics 2.18.4. For the override format, see Helm Chart Values Override format changed.iax: iax: iam: keycloak: proxyCaSecret: corporate-ca -
For Helm installations, add the following to your ITRS Analytics values file:
iam: keycloak: proxyCaSecret: corporate-ca
-
-
Save and apply the configuration. For a Helm installation, upgrade the release with the updated values file. Keycloak reads the CA certificate the next time it starts.
-
In Keycloak, open your LDAP provider under User federation. Click Test connection and Test authentication. Both succeed when Keycloak trusts the CA.
Note
Before Platform 2.18.13,proxyCaSecrettakes effect only wheniam.keycloak.proxyHostis also set. Beginning with Platform 2.18.13, a direct LDAPS connection needs onlyproxyCaSecret. If you setproxyHostfor an HTTP forward proxy, you must still setproxyCaSecret.
Warning
The Secret named byproxyCaSecretmust exist before you apply the configuration or start the upgrade. If you previously added the CA to thekeycloakConfigMap manually, the platform upgrade replaces that edit. Create the Secret before the upgrade and setproxyCaSecretin that same upgrade, so LDAPS sign-in continues to work.
Protected system users Copied
Warning
When integrating Keycloak with LDAP, Active Directory, or another identity provider, keep therealm-adminuser as a separate local system account. Do not delete it, federate it, or otherwise bring it under external identity lifecycle management.
realm-admin user Copied
The realm-admin user is a protected system account that serves critical internal platform functions.
Do not delete the realm-admin user from Keycloak, and keep it separate from regular administrative accounts. This protected system account is required for license validation and for authentication during upgrade and reconfiguration operations. If you change its password, you must also update the associated Kubernetes secret.
Warning
Deletingrealm-adminbreaks license validation and can render the platform unusable. If you change therealm-adminpassword in Keycloak, you must also update theiam-realm-admin-credentialssecret. Otherwise, upgrade and reconfiguration operations will fail.
Password management Copied
Rotating the realm-admin password Copied
If you need to change the realm-admin password:
-
Change the password in Keycloak using the admin console or API.
-
Update the
iam-realm-admin-credentialssecret to match:kubectl create secret generic iam-realm-admin-credentials \ --from-literal=username=realm-admin \ --from-literal=password=NEW_PASSWORD \ --dry-run=client -o yaml | kubectl apply -n <namespace> -f -
Warning
The password stored in Keycloak and theiam-realm-admin-credentialssecret must always match. Any mismatch causes upgrade and reconfiguration operations to fail.
Administrative user guidelines Copied
When integrating with Active Directory, LDAP, or another identity provider:
| User | Can delete? | Can change password? | Purpose |
|---|---|---|---|
admin |
Yes | Yes | Master realm administrator |
itrs |
Yes | Yes | Optional administrative user |
realm-admin |
No | Yes | System account |
Password changes for realm-admin require updating the iam-realm-admin-credentials secret.
Ensure that your federation rules do not affect or delete the realm-admin user.
Federated user roles Copied
Since the web console requires certain roles to allow users to access ITRS Analytics, you need to manage federated user roles.
Assign a default user role Copied
Roles can be assigned during registration by defining default roles in Keycloak. Once you have defined the default roles, all new users will be automatically assigned one or more roles when they first authenticate to Keycloak.
Adding the user role by default ensures that all users from the external system will be able to log in to the web console. To do this:
- Navigate to the
itrs-analyticsrealm in Keycloak by clicking itrs-analytics in the top-left drop down menu. - Create the
userrole by clicking Realm roles > Create role. Add the role name and description. - Click Realm settings, and then go to the User registration tab.
- Click Add role, then assign the
userrole.
Although easy to configure, this approach may not be flexible enough for some organizations. It lets every user from the external system automatically access the system, which may not be appropriate for all users. Additionally, it does not provide a way to determine which external users should be admins.
Define role mappings Copied
Using a mapper is a more dynamic approach to managing external user access than assigning a default user role.
Role mappers are available for both types of federations.
With a role mapper, you can map external user attributes to Keycloak roles and permissions. This gives you more control over who has access to ITRS Analytics and what permissions they have.
Role mappings for LDAP federation Copied
- Navigate to the
itrs-analyticsrealm in Keycloak by clicking itrs-analytics in the top-left drop down menu. - Click User federation, and then select your configured external source.
- Go to the Mappers tab, and then click Add mapper.
- Provide the name of the mapper.
- From the Mapper type dropdown list, select an option such as role-ldap-mapper or group-ldap-mapper to configure a role from LDAP to an assigned role in Keycloak.
- Click Save to create the mapper.
Role mappings for IDP federation Copied
- Navigate to the
itrs-analyticsrealm in Keycloak by clicking itrs-analytics in the top-left drop down menu. - Click Identity providers, and then select your configured external source.
- Go to the Mappers tab, and then click Add mapper.
- Provide the identity provider mapper details. Make sure to associate the External role with the appropriate realm Role.
For example, given the following strategies:
- Users with the external role
company/usershould be assigned theuserrole.
- Users with the external role
system-adminshould be assigned theadminrole.
- Users with the external role
- Click Save to create the mapper.