---
title: "User federation"
description: ""
url: "https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.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 `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](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.

## Trust a private certificate authority for LDAPS

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:

1. 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.

   ```bash
   kubectl create secret generic corporate-ca \
     --from-file=tls.crt=corporate-ca.pem \
     -n <namespace>
   ```

2. Set `iam.keycloak.proxyCaSecret` to the name of that Secret.

   - For KOTS and embedded cluster installations, add the following to **Advanced Settings > Helm Chart Values Override**. The top-level `iax` key is the chart name. The nested `iax` key is the chart values alias required since ITRS Analytics 2.18.4. For the override format, see [Helm Chart Values Override format changed](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/upgrade/itrs-analytics-upgrade-notes/index.html#helm-chart-values-override-format-changed).

     ```yaml
     iax:
       iax:
         iam:
           keycloak:
             proxyCaSecret: corporate-ca
     ```

   - For Helm installations, add the following to your ITRS Analytics values file:

     ```yaml
     iam:
       keycloak:
         proxyCaSecret: corporate-ca
     ```

3. 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.
4. 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, `proxyCaSecret` takes effect only when `iam.keycloak.proxyHost` is also set. Beginning with Platform 2.18.13, a direct LDAPS connection needs only `proxyCaSecret`. If you set `proxyHost` for an HTTP forward proxy, you must still set `proxyCaSecret`.




**Warning**


The Secret named by `proxyCaSecret` must exist before you apply the configuration or start the upgrade. If you previously added the CA to the `keycloak` ConfigMap manually, the platform upgrade replaces that edit. Create the Secret before the upgrade and set `proxyCaSecret` in that same upgrade, so LDAPS sign-in continues to work.



## 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 `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.  
    ![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 `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**.
    ![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 `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.
    ![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.

