Keycloak setup

Configure Keycloak or a generic OIDC provider.

This is the operator guide for wiring the BARRY UI against Keycloak — the default identity provider — or any other standards-compliant OpenID Connect provider (Authentik, Janssen, Auth0). For the concepts behind login and roles, read Authentication & Roles first.

The runtime uses the Backend-for-Frontend pattern: the SPA never sees tokens; the server runs the authorization-code + PKCE flow and issues a session cookie. Users and roles live entirely in Keycloak.

Hosting modes

Two modes are supported, both selected by configuration:

• Self-hosted (default) — a Keycloak service runs alongside the runtime (a container app in the cloud, a compose service locally).
• External — you already run Keycloak or another OIDC provider, and point the runtime's authority URL at it.

The golden rule — one authority URL. The issuer Keycloak stamps into its tokens must equal the authority the server validates against, which must equal the URL the browser is redirected to. Almost every "it bounces back to login" problem traces to these three drifting apart.

Setup steps

All steps below happen inside a dedicated realm (named barry in the examples), not the master realm.

1. Create the realm

In the Keycloak admin console, create a realm named barry. Its name must match the …/realms/barry segment of the authority URL the runtime uses.

2. Create the BFF client

This is the confidential client the server authenticates as.

• Client type: OpenID Connect.
• Client ID: barry-io-ir (must match the runtime's Oidc:ClientId).
• Client authentication: On — this makes it a confidential client.
• Authentication flow: Standard flow only.
• Valid redirect URIs: one …/signin-oidc entry per origin the UI is served from (e.g. https://<ui-host>/signin-oidc, and the local-dev origins).
• Valid post-logout redirect URIs: the matching …/signout-callback-oidc entries.
• Web origins: + to mirror the redirect-URI origins.

Then open the client's Credentials tab and copy the client secret — this becomes the runtime's Oidc:ClientSecret. Treat it like a password.

3. Define the realm roles

Create three realm roles. The names are case-sensitive and must be exactly:

• Admin — full control.
• Operator — operate clients and trigger transports; no settings.
• Viewer — read-only.

You do not need to compose the roles; the runtime treats them hierarchically.

4. Emit the roles into the ID token

The server reads roles off the ID token, but Keycloak by default emits realm roles only into the access token. Without this step every user lands on the Access-denied page.

In Client scopes → roles → Mappers → realm roles, turn Add to ID token on. Confirm the token claim name is realm_access.roles (the default the runtime expects).

5. Assign roles to users

For each user, open Role mapping → Assign role, filter by realm roles, and assign Admin, Operator, or Viewer. The role is read on the user's next sign-in. (You can also federate users from your corporate directory via Keycloak's Identity providers — that is outside this guide.)

Configuring the runtime

The minimum configuration the server needs:

BARRY_AUTH_PROVIDER=Keycloak
BARRY_OIDC_AUTHORITY=<keycloak-base>/realms/barry
BARRY_OIDC_CLIENT_ID=barry-io-ir
BARRY_OIDC_CLIENT_SECRET=<from step 2>

Other useful settings:

• Oidc:RoleClaim — defaults to realm_access.roles.
• Oidc:NameClaim — defaults to preferred_username.
• Oidc:AdminConsoleUrl — the deep link shown on Settings → Users.

Other OIDC providers

The provider is provider-agnostic; only configuration changes for Authentik, Janssen, or Auth0:

• Set the authority URL to the provider's issuer (it must serve /.well-known/openid-configuration).
• Set the role claim to the dotted path of the role array in the token (Authentik often uses a flat groups claim, for example).
• The role values must still be exactly Admin / Operator / Viewer.

Machine authentication to cloud systems

Beyond UI login, a Keycloak service-account client can authenticate the runtime to destinations, so a Keycloak identity reaches cloud storage with no cloud secret stored.

Create a second client (e.g. barry-machine) with Client authentication on and Service accounts roles enabled, and copy its secret. Then:

• S3 / MinIO (web identity) — the runtime mints a service-account token and trades it at AWS STS for temporary credentials. You set up, one time, an IAM OIDC identity provider for the Keycloak realm issuer and an IAM role that trusts it; on the destination you provide the role ARN, the token endpoint, and the service-account client id/secret.
• ADLS / Fabric / OneLake (Workload Identity Federation) — the runtime exchanges the service-account token for an Entra token. This requires a one-time setup in the Entra portal: add a federated credential to an Entra app registration whose issuer is the Keycloak realm issuer, whose subject is the service account's sub, and whose audience is api://AzureADTokenExchange; grant that app the right Azure role on the storage account or workspace; and add an audience mapper in Keycloak. On the BARRY destination, pick Workload Identity Federation and fill in the Entra tenant/client id and the Keycloak token endpoint and client id/secret.

The runtime cannot create the federated credential itself — it is a one-time portal step done by an administrator.

Troubleshooting

• The UI bounces between login and the dashboard — the issuer does not match the authority URL the browser reached Keycloak at (the golden rule).
• Every page says Access denied, even for an Admin — the realm-roles mapper's Add to ID token is off (step 4), or the role claim path is wrong.
• /api/me returns 403 with empty roles — the user has no Admin/Operator/Viewer realm role (step 5), or the roles mapper is not emitting to the ID token.
• redirect_uri … invalid — the exact UI origin (scheme + host + port) is missing from the client's valid redirect URIs.