# Active Directory through Keycloak

> Single sign-on and Windows sign-in with Active Directory accounts, through a Keycloak that runs next to Proxus, also without internet access.

Source: https://proxus.io/docs/administer/active-directory-keycloak

At the end of this guide, people sign in to Proxus with their Active Directory (or other LDAP) user name and
password, and their AD groups decide their Proxus roles. Nothing leaves the plant network: a Keycloak runs next to
Proxus, reads Active Directory over LDAPS, and Proxus signs people in through Keycloak with
[single sign-on](https://proxus.io/docs/administer/single-sign-on).

Keycloak is open-source identity software. Besides Active Directory, it can add Windows sign-in (Kerberos), so people
on domain-joined PCs open Proxus without typing a password, and multi-factor sign-in.

To let people type their Active Directory user name and password on the Proxus sign-in page, without Keycloak, see
[Active Directory and LDAP sign-in](https://proxus.io/docs/administer/active-directory). Use Keycloak when you want single sign-on
across applications or Windows sign-in.

If Keycloak already runs next to Proxus ([Sign in with Keycloak](https://proxus.io/docs/administer/keycloak)), do only the second part
of Step 1 and go on with [Step 2](#step-2-connect-active-directory).

## Before you start

- Proxus installed with the [installer](https://proxus.io/docs/get-started/install).
- A **read-only service account** in Active Directory, for example `svc-proxus-ldap`, with a password that does not
  expire.
- **LDAPS** on your domain controllers (port 636), and your company's root CA certificate as a `.pem` file. Windows
  Server 2025 refuses plain LDAP sign-ins by default; use LDAPS everywhere.
- AD groups for Proxus, for example `proxus-admins`, `proxus-operators` and `proxus-viewers`, with people in them.
- Two addresses people can open: one for Proxus, for example `https://proxus.plant.local`, and one for Keycloak, for
  example `https://sso.plant.local`. In a lab, `http://<host>:8080` and `http://<host>:8180` are enough.

## Step 1: Add Keycloak and trust your company CA

1. Add Keycloak next to Proxus with the installer, as in
   [Sign in with Keycloak, Step 1](https://proxus.io/docs/administer/keycloak#step-1-add-keycloak-with-the-installer). The installer
   creates the realm `proxus` with the application Proxus signs in with and the groups `proxus-admins`,
   `proxus-operators` and `proxus-viewers`, and shows Keycloak's `admin` password.
2. Copy your company's root CA certificate into `proxus-platform/keycloak/truststore/`, for example as
   `company-root-ca.pem`, so Keycloak trusts the domain controllers' LDAPS certificates. Then, in `proxus-platform`:

   ```bash
   docker compose restart keycloak
   ```

## Step 2: Connect Active Directory

1. Open `<KEYCLOAK_URL>/admin`, sign in as `admin` with `KEYCLOAK_ADMIN_PASSWORD`, and switch to the realm
   **proxus** (top left).
2. Open **User federation** and select **Add Ldap providers**.
3. Fill in:

   | Field | Value |
   | --- | --- |
   | Vendor | **Active Directory** |
   | Connection URL | `ldaps://dc1.plant.local:636` (several: separate with a space) |
   | Bind type | **simple** |
   | Bind DN | the service account, e.g. `CN=svc-proxus-ldap,OU=Service Accounts,DC=plant,DC=local` |
   | Bind credentials | its password |
   | Edit mode | **READ_ONLY** |
   | Users DN | where people are, e.g. `OU=Users,DC=plant,DC=local` |
   | Search scope | **Subtree** |

   Select **Test connection** and **Test authentication**; both must succeed. Then **Save**.
4. In the provider, open **Mappers** > **Add mapper**, type **group-ldap-mapper**:

   | Field | Value |
   | --- | --- |
   | LDAP Groups DN | where the Proxus groups are, e.g. `OU=Groups,DC=plant,DC=local` |
   | Group Name LDAP Attribute | `cn` |
   | Group Object Classes | `group` |
   | Membership LDAP Attribute | `member` |
   | Membership Attribute Type | `DN` |
   | Mode | **READ_ONLY** |
   | User Groups Retrieve Strategy | **LOAD_GROUPS_BY_MEMBER_ATTRIBUTE_RECURSIVELY** (follows nested AD groups) |
   | LDAP Filter | `(cn=proxus-*)` (only the Proxus groups) |

   **Save**, then **Sync LDAP groups to Keycloak**.

## Step 3: Check the roles

The groups map to Proxus roles in `docker-compose.keycloak.yml`:

| AD group | Proxus role |
| --- | --- |
| `proxus-admins` | Administrators |
| `proxus-operators` | Operator |
| `proxus-viewers` | Viewer |

Every user also gets **Default** when Proxus creates them. To use other group names or roles, change the
role map in `proxus-platform/docker-compose.override.yml` as in
[Sign in with Keycloak](https://proxus.io/docs/administer/keycloak#step-2-add-people) and run `docker compose up -d` again. How mapped roles are kept in line
at every sign-in is in [Single sign-on](https://proxus.io/docs/administer/single-sign-on#step-3-map-groups-to-roles).

## Step 4: Test it

1. Open Proxus in a private browser window and select **Log In with Company account**.
2. Sign in with an AD account that is in `proxus-admins`.
3. In Proxus, open **Security > Users**: the person is listed with **Administrators**.
4. Take the person out of the group in AD and sign in again: the role is gone.

## Keep a way in

Keep at least one Proxus administrator who signs in with a Proxus password (the **Admin** user, with
[two-step verification](https://proxus.io/docs/administer/two-step-verification)). When a domain controller or Keycloak cannot be
reached, that account still works.

## Windows sign-in and multi-factor sign-in

- **Windows sign-in (Kerberos):** people on domain-joined PCs open Proxus without typing a password. In Keycloak's
  LDAP provider, turn on **Allow Kerberos authentication** and give it the service principal and keytab your AD
  administrator creates for the Keycloak address. Browsers must trust that address for Windows sign-in.
- **Multi-factor sign-in:** in Keycloak, **Authentication** > **Required actions**, turn on **Configure OTP**, or add
  OTP to the browser flow.

## When something does not work

| What you see | Why | What to do |
| --- | --- | --- |
| **Test connection** fails with a certificate error. | Keycloak does not trust the domain controller's certificate. | Put the root CA `.pem` in `proxus-platform/keycloak/truststore/` and run `docker compose restart keycloak`. |
| **Test authentication** fails. | Wrong Bind DN or password, or the account is locked. | Check the service account in AD. Use its full DN. |
| Sign-in works but the person has no Proxus role. | Their groups are not synced or are named differently. | Run **Sync LDAP groups to Keycloak**; check the names against the role map. |
| No **Log In with Company account** button. | The provider settings are incomplete, for example `KEYCLOAK_URL` starts with `http://` without `KEYCLOAK_REQUIRE_HTTPS=false`. | The hub log (category **Authentication**) names the problem at start. |
| The button shows an error instead of Keycloak's sign-in page. | Proxus cannot reach Keycloak's address. | `KEYCLOAK_URL` must be reachable from the Proxus container as well as from browsers. |

## What's next

- [Active Directory and LDAP sign-in](https://proxus.io/docs/administer/active-directory): without Keycloak
- [Single sign-on](https://proxus.io/docs/administer/single-sign-on): all OpenID Connect settings, API and service accounts
- [Users and roles](https://proxus.io/docs/administer/users-and-roles)
- [Two-step verification](https://proxus.io/docs/administer/two-step-verification)