Sign in with Keycloak

At the end of this guide, Keycloak runs next to Proxus, you manage people and their groups in it, and people sign in to Proxus with their Keycloak account. The groups decide their Proxus roles. You need no Active Directory and no internet access.

Keycloak is open-source identity software. Use it when you want one account for Proxus and your other applications (single sign-on), multi-factor sign-in and password rules in one place, or a place to connect Active Directory later.

Before you start

• Proxus installed with the installer.
• 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.
• Both addresses must also be reachable from the Proxus container.

Step 1: Add Keycloak with the installer

1. In the folder that contains proxus-platform, run the installer again (the same command as for the installation) and choose Add Keycloak (single sign-on). On a new installation, answer y to Install Keycloak next to Proxus? instead.
2. Answer its questions:
   • Address people open Proxus with, for example https://proxus.plant.local.
   • Address people open Keycloak with, for example https://sso.plant.local.
   • Text of the sign-in button, for example Company account.
3. The installer creates Keycloak's administrator password and the secret Proxus and Keycloak share, starts Keycloak next to Proxus and connects Proxus to it. At the end it shows the address of Keycloak's administration and the admin password. Both are also in proxus-platform/.env.

At the first start, Keycloak creates its own database on the Proxus PostgreSQL server and a realm called proxus with:

• the application proxus-hub that Proxus signs in with,
• the groups proxus-admins, proxus-operators and proxus-viewers,
• the groups information Proxus reads to give roles.

Later starts and updates keep what you changed in Keycloak; the realm is not created again. Keycloak's data is in the Proxus database, so the installer's backups include it. To remove Keycloak, run the installer and choose Remove Keycloak; its data stays, so adding it again brings it back.

Step 2: Add people

1. Open <KEYCLOAK_URL>/admin and sign in as admin with KEYCLOAK_ADMIN_PASSWORD. Switch to the realm proxus (top left).
2. Open Users and select Add user. Enter the Username, the email and the name, then Create.
3. On the Credentials tab, select Set password. Leave Temporary on: the person chooses their own password at the first sign-in.
4. On the Groups tab, select Join Group and pick proxus-operators, for example.

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

Every user also gets Default when Proxus creates them. To map other groups, add them in proxus-platform/docker-compose.override.yml (updates replace docker-compose.keycloak.yml, never the override), then run docker compose up -d in that folder:

services:
  proxus-ui:
    environment:
      Authentication__Oidc__Providers__0__RoleMap__line-1-operators__0: Operator

Step 3: Test it

1. Open Proxus in a private browser window. Under Log In there is now Log In with Company account.
2. Select it. Keycloak's sign-in page opens; sign in with the person's user name and password.
3. Proxus opens. As an administrator, open Security > Users: the person is listed with Operator and Default, and Sign-in says Single sign-on (company).

Take the person out of the group in Keycloak and sign in again: the role is gone. See Single sign-on for how roles are kept in line.

Turn on what Keycloak adds

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 Keycloak cannot be reached, that account still works.

When something does not work

What's next

• Choose how people sign in
• Single sign-on: all OpenID Connect settings, API and service accounts
• Active Directory through Keycloak