Integrate Keycloak with Procivis One

Overview

This guide assumes you have an existing Keycloak setup with OpenID Connect. You will configure Keycloak to work with Procivis One, then use the Procivis One Desk to map your existing Keycloak realm roles to Procivis One roles.

Example scenario

In this example, our organization already has:

• A Keycloak realm with existing realm roles
• Users assigned to realm roles (directly or via groups)
• An existing realm for authentication

We will add Procivis One as a new client and configure one existing realm role to have initial admin access.

Prerequisites

• Keycloak administrator account
• Access to your Procivis One deployment configuration

note

Exact labels vary between Keycloak versions. If you don't see a term as written, check your version's documentation — the underlying concept will be the same.

Keycloak configuration

Step 1: Create a client

Create a new client in Keycloak for Procivis One.

1. In the Keycloak Admin Console, navigate to your realm, then go to Clients > Create client

2. Configure the following:

   • Client type: OpenID Connect
   • Client ID: Choose a name, for example procivis-one

3. Click Next

4. On the Capability config step, enable Client authentication (this creates a confidential client with a client secret)

5. Click Next, then Save

Step 2: Configure redirect URIs

Configure where Keycloak sends authentication responses.

1. Navigate to your new client's Settings tab

2. Under Access settings, configure Valid redirect URIs based on your gateway:

   • For example: https://your-domain.com/.apisix/redirect
   • Exact paths depend on your gateway configuration

3. (Optional) Configure Valid post logout redirect URIs for post-logout redirects

4. Click Save

Step 3: Retrieve client credentials

After saving, retrieve the credentials needed for your Procivis One deployment configuration.

1. Navigate to the Credentials tab of your client

2. Note the Client Secret

3. The Client ID is the value you set in Step 1

Step 4: Locate the issuer URI

Retrieve the issuer URI for your realm.

1. Navigate to Realm settings > General tab

2. Note the Realm name

The issuer URI follows the pattern: https://your-keycloak-domain/realms/{realm-name}

The OIDC discovery URL follows the pattern: https://your-keycloak-domain/realms/{realm-name}/.well-known/openid-configuration

Configuration requirement: Set your BFF's sts.iam.tokenValidation.aud variable to match your client ID (Keycloak uses the client ID as the token audience by default).

Step 5: Configure admin access for bootstrapping

Grant initial admin access to bootstrap Procivis One.

In Keycloak, realm roles can be assigned to users directly or via groups — either approach results in the role appearing in the user's token.

If you already include realm roles in your tokens:

1. Identify which user or group should have initial admin access

2. Create a realm role named ONE_STS_ADMIN and assign it to that user or group:

   • Navigate to Clients > [Your Client] > Roles, or manage assignments via Users > [User] > Role mapping

3. If your roles claim is not named roles, update sts.iam.rolePath in your BFF configuration to match your claim name

If you need to create a roles claim:

1. Create a realm role named ONE_STS_ADMIN

2. Assign at least one user to this role (directly or via a group)

3. Add a protocol mapper to include realm roles in access tokens:

   • Navigate to Clients > [Your Client] > Client scopes > [Client]-dedicated > Add mapper > Configure a new mapper
   • Select User Realm Role
   • Set the Token Claim Name to roles (or match your sts.iam.rolePath configuration)
   • Enable Add to access token

4. Click Save

Optional: Display user names in Desk

If your tokens include family_name and given_name claims, user names will appear in the Desk UI. Keycloak includes these by default when the profile scope is assigned to your client.

After bootstrapping: The STS admin can use the Desk to map your organization's existing Keycloak realm roles to Procivis One roles and permissions, eliminating the need to manage role assignments in both systems.

Required configuration values

After completing the Keycloak configuration, you will need these values to configure your Procivis One deployment:

Value	Location in Keycloak	Notes
Client ID	Clients > [Your Client] > Settings > Client ID
Client Secret	Clients > [Your Client] > Credentials > Client Secret
Issuer URI	Realm settings > General (see pattern above)	Required for OAuth2-Proxy
OIDC Discovery URL	Derived from Issuer URI (see pattern above)	Required for APISIX; auto-discovers issuer

Example values:

• Issuer URI: https://keycloak.your-domain.com/realms/your-realm
• OIDC Discovery: https://keycloak.your-domain.com/realms/your-realm/.well-known/openid-configuration

Next steps

• Configure your Procivis One deployment with these Keycloak values. The specific configuration depends on your deployment architecture and gateway choice. For a full list of BFF configuration variables, see BFF Configuration Reference.
• For guidance on mapping your Keycloak realm roles to Procivis One permissions, see Mapping an IAM Role to System Permissions.