> ## Documentation Index
> Fetch the complete documentation index at: https://syteca.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Keycloak SSO Integration

> Set up SAML 2.0 Single Sign-On between Keycloak (with an LDAP-backed realm) and the Syteca Management Tool.

This page configures SAML 2.0 authentication between Keycloak and the Syteca Management Tool, including synchronizing users from Active Directory via an LDAP provider in Keycloak. See [SSO integration overview](/docs/administration/integrations/sso) for what SSO integration does and the Management Tool settings shared across every provider.

## 1. Create a realm in Keycloak

<Steps>
  <Step title="Log in to the Keycloak administrative console">
    Open the Keycloak admin console.
  </Step>

  <Step title="Create a realm">
    In the upper left corner, click **Manage realms**, then **Create realm**. Enter a name for the realm and click **Create**.
  </Step>
</Steps>

## 2. Configure the LDAP provider

To synchronize users from Active Directory into this realm:

<Steps>
  <Step title="Add an LDAP provider">
    Go to **User Federation**, then click **Add LDAP providers**.
  </Step>

  <Step title="Set connection and authentication settings">
    | Parameter          | Value                                                                            |
    | ------------------ | -------------------------------------------------------------------------------- |
    | Vendor             | Active Directory                                                                 |
    | Connection URL     | `LDAP://<ldap-hostname-or-ip>`                                                   |
    | Connection pooling | Off                                                                              |
    | Bind Type          | simple                                                                           |
    | Bind DN            | The service user's DN, for example `CN=Administrator,CN=Users,DC=example,DC=com` |
    | Bind Credential    | The service user's password                                                      |
    | Use Truststore SPI | Always                                                                           |
  </Step>

  <Step title="Set LDAP searching and updating settings">
    | Parameter               | Value                                                                  |
    | ----------------------- | ---------------------------------------------------------------------- |
    | Edit mode               | READ\_ONLY                                                             |
    | Users DN                | The DN containing your users, for example `CN=Users,DC=example,DC=com` |
    | Username LDAP attribute | `cn`                                                                   |
    | RDN LDAP attribute      | `cn`                                                                   |
    | UUID LDAP attribute     | `objectGUID`                                                           |
    | User object classes     | `user`                                                                 |
    | Search scope            | Subtree                                                                |
    | Pagination              | Off                                                                    |
  </Step>

  <Step title="Set synchronization settings">
    | Parameter                   | Value |
    | --------------------------- | ----- |
    | Import Users                | On    |
    | Sync Registrations          | On    |
    | Periodic Full Sync          | Off   |
    | Periodic Changed Users Sync | Off   |
  </Step>

  <Step title="Save">
    Save the LDAP provider settings.
  </Step>
</Steps>

## 3. Add a mapper for the distinguished name

To pass each user's full distinguished name (DN) from LDAP into Keycloak — required later for the SAML assertion mapper:

<Steps>
  <Step title="Open the LDAP provider's mappers">
    Go to **User Federation > \[your LDAP provider] > Mappers > Add mapper**.
  </Step>

  <Step title="Create the mapper">
    | Parameter                   | Value                        |
    | --------------------------- | ---------------------------- |
    | Name                        | `ldap-dn-mapper`             |
    | Mapper Type                 | `user-attribute-ldap-mapper` |
    | User Model Attribute        | `dn`                         |
    | LDAP Attribute              | `distinguishedName`          |
    | Read Only                   | On                           |
    | Always Read Value From LDAP | On                           |
    | Is Mandatory In LDAP        | Off                          |
  </Step>

  <Step title="Save">
    Save the mapper.
  </Step>
</Steps>

<Tip>
  Confirm DN synchronization is working before continuing: open **Users**, select any user imported from LDAP, and check that the **Details** tab shows a `dn` attribute with user and domain information (for example `CN=User Name,OU=Users,DC=domain,DC=com`).
</Tip>

## 4. Set up the SAML identity provider

<Steps>
  <Step title="Add a SAML identity provider">
    Go to **Identity Providers**, and select **SAML v2.0**.
  </Step>

  <Step title="Disable the entity descriptor option">
    Deselect **Use entity descriptor** — this is required to make the fields below available.
  </Step>

  <Step title="Fill in the identity provider fields">
    | Parameter                   | Value                                                                                    |
    | --------------------------- | ---------------------------------------------------------------------------------------- |
    | Service provider entity ID  | `https://<ip-or-hostname>/Syteca`                                                        |
    | Identity provider entity ID | `https://<ip-or-hostname>:<port>/realms/<realmName>` — the URL of the realm you created  |
    | Single Sign-On service URL  | `https://<ip-or-hostname>/Syteca/Account/ConsumeSSO/` — the Syteca Management Tool's URL |
    | Single logout service URL   | `https://<ip-or-hostname>/Syteca/Account/SsoLoggedOut/`                                  |
    | NameID policy format        | Unspecified                                                                              |
    | Principal type              | Subject NameID                                                                           |
  </Step>

  <Step title="Add the identity provider">
    Click **Add**.
  </Step>
</Steps>

## 5. Export the realm's IdP metadata

<Steps>
  <Step title="Open Realm Settings">
    Go to **Realm Settings**, then the **General** tab.
  </Step>

  <Step title="Download the metadata">
    Click **SAML 2.0 Identity Provider Metadata** and save the file (for example, `IdP_metadata.xml`).

    <Note>
      This file is used on the Service Provider side, in the Syteca Management Tool's SSO settings.
    </Note>
  </Step>
</Steps>

## 6. Create a client (service provider) in Keycloak

<Steps>
  <Step title="Create a client">
    Go to **Clients**, then click **Create client**.
  </Step>

  <Step title="Set general settings">
    | Parameter   | Value                                                                |
    | ----------- | -------------------------------------------------------------------- |
    | Client type | SAML                                                                 |
    | Client ID   | `https://<ip-or-hostname>/Syteca` — the Syteca Management Tool's URL |

    Leave the remaining parameters at their defaults, and click **Next**.
  </Step>

  <Step title="Set login settings">
    | Parameter           | Value                               |
    | ------------------- | ----------------------------------- |
    | Valid redirect URIs | `https://<ip-or-hostname>/Syteca/*` |

    Click **Save**.
  </Step>

  <Step title="Verify SAML capabilities">
    Open the client's settings and confirm, under **SAML capabilities**:

    | Parameter              | Value |
    | ---------------------- | ----- |
    | Force POST binding     | On    |
    | Include AuthnStatement | On    |
  </Step>

  <Step title="Configure SAML endpoints">
    On the client's **Advanced** tab:

    | Parameter                                   | Value                                                  |
    | ------------------------------------------- | ------------------------------------------------------ |
    | Assertion Consumer Service POST Binding URL | `https://<ip-or-hostname>/Syteca/Account/ConsumeSSO`   |
    | Logout Service POST Binding URL             | `https://<ip-or-hostname>/Syteca/Account/SingleLogout` |

    Save the changes.
  </Step>
</Steps>

## 7. Create a SAML attribute mapper for the DN

To pass the user's DN (from LDAP) into the SAML assertion:

<Steps>
  <Step title="Open the client's scopes">
    Go to **Clients > \[your SAML client] > Client scopes**.
  </Step>

  <Step title="Add a mapper">
    If no mappers exist yet, click **Configure a new mapper**. Otherwise, click **Add mapper > By configuration**. Either way, select **User Attribute**.
  </Step>

  <Step title="Configure the mapper">
    | Parameter                 | Value                                                      |
    | ------------------------- | ---------------------------------------------------------- |
    | Mapper Type               | User Attribute                                             |
    | Name                      | `dn-claim-mapper`                                          |
    | User Attribute            | `dn`                                                       |
    | SAML Attribute Name       | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/dn` |
    | SAML Attribute NameFormat | URI Reference                                              |

    <Warning>
      The **User Attribute** value must exactly match the attribute name created in the LDAP mapper in step 3 (`dn`).
    </Warning>
  </Step>

  <Step title="Save">
    Save the mapper.
  </Step>
</Steps>

## 8. Configure SSO integration in the Management Tool

<Steps>
  <Step title="Open SSO Integration settings">
    In the Management Tool, click **Configuration**, then select the **SSO Integration** tab.
  </Step>

  <Step title="Enter the issuer and upload the metadata">
    | Parameter                        | Value                                                                                     |
    | -------------------------------- | ----------------------------------------------------------------------------------------- |
    | Issuer name                      | Your Management Tool URL, for example `https://<ip-or-hostname>/Syteca`                   |
    | Identity provider metadata (XML) | Upload the `IdP_metadata.xml` file exported in step 5                                     |
    | Custom certificate               | Only needed if you want to use a certificate generated by Keycloak instead of the default |

    <Note>
      SSO authentication is not currently supported in [Multi-Tenant mode](/docs/administration/multi-tenant/overview).
    </Note>
  </Step>

  <Step title="Save and restart the Application Server">
    Click **Save**, then restart the **EkranServer** service in Windows Services.
  </Step>
</Steps>

## Using a self-signed certificate from the Management Tool

If you plan to use a self-signed certificate generated by the Management Tool (rather than one generated by Keycloak), complete these additional steps.

<Steps>
  <Step title="Export the Management Tool's certificate">
    In the Management Tool's SSO settings, with the required fields already filled in, click **Download signing certificate** and save the file (for example, `SsoCert.cer`).
  </Step>

  <Step title="Convert the certificate to PEM format, if needed">
    If the certificate downloaded in DER format, convert it:

    ```bash theme={"system"}
    openssl x509 -inform DER -in SsoCert.cer -out SsoCert.pem
    ```
  </Step>

  <Step title="Import the certificate into Keycloak">
    Go to **Clients > \[your SAML client] > Keys**, click **Import key**, and upload the `SsoCert.pem` file.
  </Step>

  <Step title="Save">
    Click **Save** to apply the changes.
  </Step>
</Steps>

## Related

<CardGroup cols={2}>
  <Card title="SSO integration overview" icon="key" href="/docs/administration/integrations/sso">
    All supported SSO providers and shared Management Tool settings.
  </Card>

  <Card title="LDAP targets" icon="folder-tree" href="/docs/administration/integrations/ldap-targets">
    A separate LDAP integration for user provisioning and login, independent of SSO.
  </Card>

  <Card title="Azure SSO" icon="microsoft" href="/docs/administration/integrations/sso-azure">
    Configure SSO through Azure instead.
  </Card>

  <Card title="User management" icon="users" href="/docs/administration/users/users">
    Managing Management Tool user accounts and permissions.
  </Card>
</CardGroup>