Identity Provider

The quick start bundle includes a starter Keycloak that handles user sign-in. This page covers replacing it with your own OpenID Connect identity provider (IdP).

What the stack expects from your IdP

Requirement	In the starter Keycloak
A confidential client for user sign-in	login-client in the master realm
Access tokens that include the user's roles	Realm roles, at $.realm_access.roles
A JWKS endpoint for token verification	/realms/master/protocol/openid-connect/certs
At least one user with the admin role	example_user, with ONE_STS_ADMIN

For supported signing algorithms and the full token specification, see Token Structures.

1. Prepare your IdP

Create a client for Procivis One, add a roles claim to access tokens, and assign the admin role to at least one user. For step-by-step examples, see:

• Integrate Okta
• Integrate Keycloak

When you configure the client's redirect URI, use:

https://<domain>/oauth2/callback

2. Point the gateway at your IdP

The gateway is configured in two files in conf/oauth2_proxy/.

In alpha-config.yml, update the provider:

providers:
  - provider: oidc
    id: login-client
    clientID: <your-client-id>
    clientSecret: <your-client-secret>
    backendLogoutURL: <your-idp-logout-url>
    oidcConfig:
      issuerURL: <your-issuer-uri>

In oauth2-proxy.cfg, replace keycloak.<domain> in whitelist_domains with your IdP's domain.

3. Point BFF at your IdP

Add these variables to env/.bff.env:

sts.iam.tokenValidation.iss="<your-issuer-uri>"
sts.iam.tokenValidation.jwksUri="<your-jwks-uri>"
sts.iam.tokenValidation.aud="<your-token-audience>"
sts.iam.rolePath="<json-path-to-roles>"
frontend.iamLink="<your-idp-user-url>"

• iss: must match the iss claim in your IdP's access tokens exactly
• jwksUri: must be reachable from the BFF container
• aud: defaults to one-bff-client; set it to the audience your IdP puts in access tokens
• rolePath: JSONPath to the roles array in the access token, for example $.roles
• frontend.iamLink: link from the Desk to a user's record in your IdP; use %s as a placeholder for the user's sub

4. Set the admin role

Any user whose access token contains ONE_STS_ADMIN in the roles claim has full administrative access, including creating organizations and mapping roles.

To use a different role name from your IdP, set:

sts.iam.adminRole="<your-admin-role>"

After signing in as an admin, map your IdP roles to Procivis One roles. See Configure Access Control.

5. Remove the starter Keycloak

In docker-compose.yml:

• Remove the keycloak and keycloak_postgres services
• Remove keycloak from the depends_on lists of oauth2_proxy and bff
• Remove the keycloak_postgres_data volume

The master-realm.json, env/.keycloak.env, and env/.keycloak_postgres.env files are no longer used.

Apply the changes:

docker compose up -d --remove-orphans

Sign in with a user who has the admin role and confirm that Organizations appears in the sidebar.

Service-to-service authentication

In the quick start bundle, BFF calls Core, Bridge, and WRPR with static tokens. Real setups will want STS between services, with each service authenticating to your IdP as a technical user. See Service Authentication Modes and Technical Users and Delegation.

info

For other ways to set these values, see Configuration Mechanics.