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:

1. Navigate to the itrs-analytics realm in Keycloak by clicking itrs-analytics in the top-left drop down menu.
2. 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.

Protected system users Copied

Warning

When integrating Keycloak with LDAP, Active Directory, or another identity provider, keep the realm-admin user 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

Deleting realm-admin breaks license validation and can render the platform unusable. If you change the realm-admin password in Keycloak, you must also update the iam-realm-admin-credentials secret. 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:

1. Change the password in Keycloak using the admin console or API.

2. Update the iam-realm-admin-credentials secret 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 the iam-realm-admin-credentials secret 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:

Expand table

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:

1. Navigate to the itrs-analytics realm in Keycloak by clicking itrs-analytics in the top-left drop down menu.
2. Create the user role by clicking Realm roles > Create role. Add the role name and description.
3. Click Realm settings, and then go to the User registration tab.
4. Click Add role, then assign the user role.
   

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

1. Navigate to the itrs-analytics realm in Keycloak by clicking itrs-analytics in the top-left drop down menu.
2. Click User federation, and then select your configured external source.
3. Go to the Mappers tab, and then click Add mapper.
4. Provide the name of the mapper.
5. 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.
6. Click Save to create the mapper.

Role mappings for IDP federation Copied

1. Navigate to the itrs-analytics realm in Keycloak by clicking itrs-analytics in the top-left drop down menu.
2. Click Identity providers, and then select your configured external source.
3. Go to the Mappers tab, and then click Add mapper.
4. 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/user should be assigned the user role.
   • Users with the external role system-admin should be assigned the admin role.
5. Click Save to create the mapper.