# Sign in with Keycloak

> Run Keycloak next to Proxus with the ready profile, keep your people and groups in it, and let them sign in to Proxus with one company account.

Source: https://proxus.io/docs/administer/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](https://proxus.io/docs/get-started/install).
- 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`:

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

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:

```yaml
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](https://proxus.io/docs/administer/single-sign-on#step-3-map-groups-to-roles) for how roles are kept in line.

## Turn on what Keycloak adds

| What | Where in Keycloak (realm **proxus**) |
| --- | --- |
| Multi-factor sign-in (authenticator app) | **Authentication** > **Required actions**: turn on **Configure OTP**, or add OTP to the browser flow |
| Password rules | **Authentication** > **Policies** > **Password policy** |
| Account locking after wrong passwords | **Realm settings** > **Security defenses** > **Brute force detection** |
| Active Directory or LDAP accounts | **User federation**, see [Active Directory through Keycloak](https://proxus.io/docs/administer/active-directory-keycloak) |

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

## When something does not work

| What you see | Why | What to do |
| --- | --- | --- |
| No **Log In with Company account** button. | The provider settings are incomplete. | 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. |
| Keycloak says "Invalid redirect uri". | The Proxus address you gave is not the one people open Proxus with. | Run the installer, remove and add Keycloak with the right address. The realm reads it only at its first start: change **Valid redirect URIs** of the client `proxus-hub` in Keycloak too. |
| Sign-in works but the person has no Proxus role. | The person is in no mapped group. | Add them to a group on the **Groups** tab, or map their group in the override file. |
| Keycloak shows "HTTPS required". | Keycloak runs on plain HTTP and is opened from an address outside the local network. | Put Keycloak behind HTTPS. In a lab only: **Realm settings** > **General** > **Require SSL**: **none**. |

## What's next

- [Choose how people sign in](https://proxus.io/docs/administer/sign-in-methods)
- [Single sign-on](https://proxus.io/docs/administer/single-sign-on): all OpenID Connect settings, API and service accounts
- [Active Directory through Keycloak](https://proxus.io/docs/administer/active-directory-keycloak)