Integrate Okta with Procivis One

Overview

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

Example scenario

In this example, our organization already has:

• Okta groups for different teams/roles
• An existing authorization server
• Users assigned to groups

We will add Procivis One as a new application and configure one existing group to have initial admin access.

Prerequisites

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

Okta configuration

Step 1. Create an App Integration

Create a new application in Okta for Procivis One.

1. In the Okta Admin Console, navigate to Applications > Applications > Create App Integration

2. Configure the following:

• Sign-in method: OIDC - OpenID Connect
• Application type: Web Application

3. Click Create

Step 2: Configure redirect URIs

Configure where Okta sends authentication responses.

1. Navigate to your Procivis One application in Okta

2. Configure Sign-in redirect URIs based on your gateway:

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

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

Step 3: Configure authorization server

Set up the authorization server that will issue tokens for Procivis One.

1. Navigate to Security > API > Authorization Servers

2. Select your authorization server (or click Add Authorization Server to create a new one)

3. Note the Issuer URI and Audience values

Configuration requirements:

• If reusing an existing server: Set your BFF's sts.iam.tokenValidation.aud variable to match the authorization server's audience
• If creating a new server:: Set the audience to match your BFF's sts.iam.tokenValidation.aud variable (or configure both to match)

Access policy setup:

1. Navigate to your authorization server's Access Policies tab

2. Add your Procivis One app to an existing policy, or create a new policy

3. In the policy's rules, ensure the Procivis One app is listed under Assigned to clients

Step 4: Configure admin access for bootstrapping

Grant initial admin access to bootstrap Procivis One.

If you already include roles/groups in your tokens:

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

2. Add the value ONE_STS_ADMIN to their existing roles/groups claim

3. Assign that user or group to the Procivis One application:

   • Navigate to Applications > Applications > [Your Procivis One App] > Assignments tab
   • Click Assign and select the user or group

4. If your 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. In your authorization server, navigate to the Claims tab

2. Add a custom claim:

• Name: roles (or match your sts.iam.rolePath configuration)
• Include in: Access Token
• Value type: Groups
• Filter: Configure based on your naming convention

3. Create an Okta group named ONE_STS_ADMIN (or another name matching your filter)

4. Assign at least one user to this group

5. Assign that user to the Procivis One application

Optional: Display user names in Desk

If your tokens include family_name and given_name claims, user names will appear in the Desk UI. Most Okta configurations include these by default as part of the OpenID Connect profile scope.

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

Required configuration values

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

Value	Location in Okta	Notes
Client ID	Applications > [Your App] > General > Client Credentials
Client Secret	Applications > [Your App] > General > Client Credentials
Issuer URI	Security > API > [Auth Server] > Issuer URI	Required for OAuth2-Proxy
OIDC Discovery URL	Security > API > [Auth Server] > Metadata URI	Required for APISIX; auto-discovers issuer

Example values:

• Issuer URI: https://dev-12345.okta.com/oauth2/default
• OIDC Discovery: https://dev-12345.okta.com/oauth2/default/.well-known/openid-configuration

Next Steps

• Configure your Procivis One deployment with these Okta values. The specific configuration depends on your deployment architecture and gateway choice.
• For guidance on mapping your Okta roles to Procivis One permissions, see Mapping an IAM Role to System Permissions.