---
title: "User federation"
description: ""
url: "https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.16.0/install/advanced-keycloak/user-federation/index.html"
---

**Note**


Please use the [ITRS Analytics IAM app](https://docs.itrsgroup.com/docs/itrs-analytics/app/iam/current/user-guide/iam-configuration/index.html) 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

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

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](#federated-user-roles)).

To configure user federation setup in Keycloak: 

1. Navigate to the `Obcerv` realm in Keycloak by clicking **Obcerv** 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](https://wjw465150.gitbooks.io/keycloak-documentation/content/server_admin/topics/user-federation/ldap.html) 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](https://wjw465150.gitbooks.io/keycloak-documentation/content/server_admin/topics/identity-broker/oidc.html) in Keycloak documentation. Please note that SAML is not currently supported for LDAP or IDP.

## Protected system users


**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

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

#### Rotating the realm-admin password

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:

   ```bash
   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

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

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

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 `Obcerv` realm in Keycloak by clicking **Obcerv** 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.  
    ![Assign roles in Keycloak](https://docscdn.itrsgroup.com/obcerv-platform/images/thirdparty/keycloak-assign-roles.gif)

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

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

1. Navigate to the `Obcerv` realm in Keycloak by clicking **Obcerv** 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**.
    ![User role](https://docscdn.itrsgroup.com/obcerv-platform/images/thirdparty/keycloak-ldap-mappers.png)
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

1. Navigate to the `Obcerv` realm in Keycloak by clicking **Obcerv** 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.
    ![User role](https://docscdn.itrsgroup.com/obcerv-platform/images/thirdparty/keycloak-role-mapper-user.png)
    - Users with the external role `system-admin` should be assigned the `admin` role.
    ![Admin role](https://docscdn.itrsgroup.com/obcerv-platform/images/thirdparty/keycloak-role-mapper-admin.png)
5. Click **Save** to create the mapper.

