Active Directory through 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.

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. 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), do only the second part of Step 1 and go on with Step 2.

Before you start

• Proxus installed with the installer.
• 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. 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:

   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:

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 and run docker compose up -d again. How mapped roles are kept in line at every sign-in is in Single sign-on.

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). 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's next

• Active Directory and LDAP sign-in: without Keycloak
• Single sign-on: all OpenID Connect settings, API and service accounts
• Users and roles
• Two-step verification