> ## Documentation Index
> Fetch the complete documentation index at: https://docs.provisionr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Okta OAuth2 Architecture

> See how Provisionr authenticates to the Okta API with an OAuth 2.0 service app, private key JWT, DPoP-bound tokens, least-privilege scopes, and a custom admin role.

When you [connected Okta](https://docs.provisionr.io/integrations/okta/connect.md), you created an API Services app in your Okta org, registered a public key on it, granted it Okta API scopes, and assigned it a custom admin role. This page explains what each of those pieces does behind the scenes, so that you and your security team can see how Provisionr reaches the Okta API and where its access ends.

It covers these topics, in this order:

* How Provisionr gets an access token with OAuth 2.0, and how DPoP binds that token to Provisionr
* How scopes and the admin role work together to limit what Provisionr can do
* How your key is stored and rotated
* What each Okta API scope and admin role permission allows
* The settings to review on your Okta app

> [!NOTE]
>
> This page explains the design behind the connection to Okta. For the setup steps, see [Connect to Okta](https://docs.provisionr.io/integrations/okta/connect.md).

***

## OAuth 2.0 Client Credentials

> [!NOTE]
>
> Provisionr connects to the Okta API with OAuth 2.0 and an API Services app, which is the approach that Okta [strongly recommends](https://developer.okta.com/docs/guides/create-an-api-token/main/).

To access Okta users, groups, and apps through the API, we authenticate with Okta's [implementation of OAuth 2.0](https://developer.okta.com/docs/guides/implement-oauth-for-okta-serviceapp/main/) for an [API Services app](https://developer.okta.com/docs/guides/implement-oauth-for-okta/main/), using the client credentials grant.

Your Okta app has a public key registered in Okta, and the matching private key is held in Cloud KMS. Instead of sending a password or a client secret, Provisionr proves its identity by signing a short-lived JSON Web Token (JWT), known as a **client assertion**, with the private key. Every access token is requested in the same four steps.

**1. Client Assertion**

Provisionr builds a JWT that contains the app's Client ID, the key ID (`kid`) of the registered public key, a unique ID, and an expiration of 5 minutes, and Cloud KMS signs the JWT with the private key using RS256.

**2. Token Request**

Provisionr sends the client assertion to your Okta org's `/oauth2/v1/token` endpoint, along with the scopes that the API request needs.

**3. Assertion Verification**

Okta finds the registered public key that matches the `kid`, verifies the signature, and checks that each requested scope is granted to the app. If everything is valid, Okta returns an access token that expires in 60 minutes.

**4. API Request**

Provisionr sends the access token with each API request, and Okta checks that the app's admin role permits the action on the resource.

When your app requires DPoP, the token request and each API request also carry a DPoP proof, which the next section explains. You can learn more about the whole process in Okta's [OAuth 2.0 for Okta API](https://developer.okta.com/docs/guides/implement-oauth-for-okta/main/) guide.

> [!NOTE]
>
> Okta only supports public key authentication (private key JWT) for the Okta management API scopes. Client secrets can't be used to access the Okta API, so Provisionr doesn't use them.

## Demonstrating Proof of Possession

Demonstrating Proof of Possession (DPoP) is defined in [RFC 9449](https://datatracker.ietf.org/doc/html/rfc9449). When you enable **Require Demonstrating Proof of Possession (DPoP) header in token requests** on your Okta app, each access token is bound to a separate key pair that only Provisionr has.

This means that two key pairs are at work, and each has its own job. The signing key is the one whose public key you registered on your Okta app, and it proves to Okta that a token request comes from Provisionr. The DPoP key isn't your signing key, and it isn't registered in Okta. Provisionr generates a new DPoP key pair each time it requests an access token, and every API request carries a single-use proof that is signed with the DPoP key for that specific HTTP method and URL.

As a result, if an access token were ever leaked, it couldn't be replayed without the DPoP key, which only Provisionr has.

## Scopes and Admin Roles

Two settings on your Okta app control what Provisionr can do, and every API request needs both.

* Okta API scopes decide which API endpoints an access token is allowed to call. For example, `okta.users.read` allows Provisionr to list users. You grant scopes on the app's **Okta API Scopes** tab.
* Admin role permissions authorize the action itself, on the resources in the role's resource set. You assign the role on the app's **Admin roles** tab.

If a scope is granted but the admin role doesn't include a matching permission, Okta rejects the request, which makes the custom admin role your least-privilege boundary. For example, the `okta.apps.manage` scope allows calls to app endpoints, but the [Provisionr Sync role](#admin-role-permissions) only allows Provisionr to change which users and groups are assigned to apps, so it can't change your app's sign-on or provisioning configuration.

> [!TIP]
>
> Provisionr's access to Okta is bounded by two controls that are configured in your Okta org rather than in Provisionr, which are the scopes granted to the app and the permissions of its custom admin role. Both can be inspected in the Okta Admin Console, on the app's **Okta API Scopes** and **Admin roles** tabs. An app that holds only the `Provisionr Sync` role, and not `Super Administrator`, shows that the integration operates with least privilege. [Reviewing the Okta App](#reviewing-the-okta-app) lists the settings to check.

## Secrets Storage

A 4096-bit RSA private key is generated inside Cloud KMS when you create your integration, and each Okta integration has a signing key of its own. The private key can't be exported by anyone, including us, so it's never displayed, it's never stored in your workspace's database, and it's never in Provisionr's memory. To sign a token request, Provisionr sends Cloud KMS a hash of the request and receives the signature. Each signature is recorded in your [event log](https://docs.provisionr.io/concepts/workspace/logs.md) as `okta.credential.sign.success`.

Nothing in the web interface, the API, or the CLI can read the private key, so the only way to replace it is to rotate it, which the next section explains.

Okta access tokens expire after 60 minutes. Each access token is encrypted before it's cached, and it's cached for no longer than its lifetime.

## Key Rotation

You can rotate your Provisionr-managed key at any time with this Provisionr CLI command, and we'll ask you to run it if a security incident ever affects your key.

```bash theme={null}
prv okta-integration:rotate-key
```

The command generates a new version of your integration's signing key and displays its public key. An Okta app can have more than one public key, so you add the new public key to your Okta app before Provisionr stops using the old key. Once scopes are granted to an app, Okta only allows a Super Administrator to add or remove its keys.

Then run `prv okta-integration:activate`. Provisionr runs the [connection test](https://docs.provisionr.io/integrations/okta/connect.md#connection-test) with the new key, and if it passes, Provisionr switches to the new key and destroys the old one in Cloud KMS, so the old key can't sign anything again. You can then remove the old public key from your Okta app. If the test fails, the old key keeps working, and nothing changes.

## API Client

We call the Okta API through the open source [Okta API Client](https://github.com/boldlygrow/okta-api-client), which is maintained by our founder. It handles authentication, token caching, DPoP, error handling, and pagination, so each call that Provisionr makes only needs to provide the endpoint, the credentials, and the scope.

## OAuth2 Scopes

Your Okta app needs the following Okta API scopes so that Provisionr can read Okta users and apps and manage groups and group members. Each scope below is marked with a badge for the kind of functionality that it provides:

* Read-Only Functionality
* Read-Write Full Functionality
* Read-Write Restricted Functionality

We follow the principle of least privilege and only request the minimum Okta API scopes that each feature we implement requires. Each API call asks for the narrowest scope that can do the job, so a read asks for the `read` scope first, and if Okta hasn't granted that scope to your app, we ask for the `manage` scope instead. A `manage` scope includes everything that its `read` scope allows, so you don't need to grant both. We remember which scope worked, so that later syncs don't repeat a request that Okta has already refused.

If your team has security concerns, you can start with the read-only scopes. You don't need to grant the read-write scopes until you're ready to sync group members or create new groups from Provisionr.

### Scope Lists

There are three lists of scopes, one for each [access level](https://docs.provisionr.io/integrations/okta/connect.md#access-levels), and each one matches the [admin role permissions](#admin-role-permissions) list with the same name. Grant the **Groups + App Assignments** list if you want to use all of the functionality that Provisionr currently supports for your Okta integration.

```plain Groups + App Assignments theme={null}
okta.users.read
okta.groups.manage
okta.apps.manage
```

```plain Groups Only (No App Cleanup) theme={null}
okta.users.read
okta.groups.manage
okta.apps.read
```

```plain Audit (Read-Only) theme={null}
okta.users.read
okta.groups.read
okta.apps.read
```

### Core Functionality

Every scope list includes this scope.

`okta.users.read`

Provisionr can read your Okta users and their profile attributes to build your organizational directory structure. This scope is required for any functionality in Provisionr to work with Okta.

When a user is created or deactivated in Okta, the next sync picks up the change. [Users & Identities](https://docs.provisionr.io/concepts/control/users.md) explains how people are represented in your directory, and [Okta Users](https://docs.provisionr.io/integrations/okta/users.md) explains how each Okta user is reconciled.

### Okta Groups

These scopes decide whether Provisionr can only read your Okta groups or can also manage them. [Access Levels and Policy Modes](https://docs.provisionr.io/integrations/okta/sync.md#access-levels-and-policy-modes) describes what each access level allows. [Okta Groups](https://docs.provisionr.io/integrations/okta/groups.md) explains how group membership is read down and written back.

```plain Manage Groups and Members theme={null}
okta.groups.manage
```

```plain Read-Only Audit theme={null}
okta.groups.read
```

`okta.groups.read`

Provisionr can read your existing Okta groups and their members, so that you can start building group-based access control policies.

You can also use this scope to audit existing access without giving Provisionr permission to make any changes.

`okta.groups.manage`

Provisionr can create Okta groups and add and remove group members. This allows Provisionr to create a group automatically for each department, team, project, or other attribute in the Provisionr Directory.

Provisionr can also sync users to new and existing groups based on the access control policies that you create in Provisionr.

### Okta Applications

These scopes decide whether Provisionr can only read your Okta apps or can also change their assignments. [Okta Applications](https://docs.provisionr.io/integrations/okta/apps.md) explains how apps and their assignments are read, and how each app's Provisionr group works.

```plain Manage App Assignments theme={null}
okta.apps.manage
```

```plain Read-Only Audit theme={null}
okta.apps.read
```

`okta.apps.read`

Provisionr can read the list of Okta applications that you've configured, along with the groups that are assigned to them and the users who are assigned to them directly, so that you can see which groups grant access to each application.

Provisionr doesn't have any knowledge of your SAML or SCIM configuration.

`okta.apps.manage`

Provisionr can assign each app's [Provisionr group](https://docs.provisionr.io/integrations/okta/apps.md#provisionr-groups) to the app. Once the app's access has moved into its Provisionr group, Provisionr can also remove the direct user assignments that are left over, if you'd like Provisionr to handle that cleanup rather than doing it yourself. Provisionr never changes an app's assignments to any other group.

Although this scope allows calls to all of the app endpoints, the [Provisionr Sync role](#admin-role-permissions) restricts Provisionr to changing which users and groups are assigned to applications. Provisionr can't create, update, or delete applications, or change their sign-on and provisioning settings.

## Capabilities

A capability is one thing that Provisionr can do in Okta, and each access level is a set of capabilities. Each automated workflow needs specific capabilities, and it only runs when they're in your access level and the last [connection test](https://docs.provisionr.io/integrations/okta/connect.md#connection-test) passed them.

The `prv.okta` names are Provisionr's own, and you'll see them in the API and the CLI. You don't enter them in Okta. The scopes that you grant in Okta are the ones in the third column.

| Capability | What Provisionr can do | Okta API scope | Admin role permissions | Access levels |
| - | - | - | - | - |
| `prv.okta.user.read` | Read users and their profiles | `okta.users.read` | **User:** View users and their details, and **User:** View users' profile attributes | All |
| `prv.okta.group.read` | Read groups | `okta.groups.read` or `okta.groups.manage` | **Group:** View groups and their details | All |
| `prv.okta.group.user.read` | Read the members of a group | `okta.groups.read` or `okta.groups.manage` | **Group:** View groups and their details | All |
| `prv.okta.app.read` | Read apps and their assignments | `okta.apps.read` or `okta.apps.manage` | **Application:** View application and their details | All |
| `prv.okta.group.create` | Create groups | `okta.groups.manage` | **Group:** Create groups | Groups Only, and Groups + App Assignments |
| `prv.okta.group.user.add` | Add someone to a group | `okta.groups.manage` | **Group:** Manage group membership, **User:** Edit users' group membership, and **Application:** Edit application's user or group assignments | Groups Only, and Groups + App Assignments |
| `prv.okta.group.user.remove` | Remove someone from a group | `okta.groups.manage` | **Group:** Manage group membership, **User:** Edit users' group membership, and **Application:** Edit application's user or group assignments | Groups Only, and Groups + App Assignments |
| `prv.okta.app.group.add` | Assign a group to an app | `okta.apps.manage` | **Group:** Edit groups' application assignments | Groups + App Assignments |
| `prv.okta.app.user.remove` | Remove a direct user assignment from an app | `okta.apps.manage` | **User:** Edit users' application assignments | Groups + App Assignments |

## Admin Role Permissions

The `Provisionr Sync` custom admin role authorizes the actions that the granted scopes allow. These are the permissions that you select when you [create the role](https://docs.provisionr.io/integrations/okta/connect.md#connecting-okta). Each list matches the list in [Scope Lists](#scope-lists) with the same name, and each one adds permissions to the one before it.

You can start with **Audit (Read-Only)** and edit the role to add permissions when you grant the read-write scopes.

### Audit (Read-Only)

| Permission | Why Provisionr Needs It |
| - | - |
| **Application:** View application and their details | Read the list of applications and their group assignments |
| **Group:** View groups and their details | Read groups and their members |
| **User:** View users' profile attributes | Read user profile attributes for the Provisionr Directory |
| **User:** View users and their details | Read users and their status |

### Groups Only (No App Cleanup)

This list includes the **Audit (Read-Only)** permissions and adds the following permissions.

| Permission | Why Provisionr Needs It |
| - | - |
| **Application:** Edit application's user or group assignments | Okta requires this permission before any group member or app assignment can be changed |
| **Group:** Create groups | Create a group for each department, team, project, or other attribute |
| **Group:** Manage group membership | Add and remove group members |
| **User:** Edit users' group membership | Add and remove users from groups |

### Groups + App Assignments

This list includes the **Groups Only (No App Cleanup)** permissions and adds the following permissions.

| Permission | Why Provisionr Needs It |
| - | - |
| **Group:** Edit groups' application assignments | Assign groups to applications |
| **User:** Edit users' application assignments | Update a user's application access when Provisionr changes their app group membership |

### Resource Set

The role is assigned with the default resource set, such as `All Users`. If you have a large organization, you can create a narrower resource set to limit what Provisionr can see and manage.

### Super Administrator

> [!CAUTION]
>
> Don't assign the `Super Administrator` role to the Provisionr app. If you did, anyone who could use its key would have full control of your Okta org, which would be a major security risk.
>
> Okta's **Public client app admins** org setting can assign the Super Administrator role to API service apps automatically when scopes are granted. After you assign the custom role, check the app's **Admin roles** tab and remove the Super Administrator role if it's listed.

***

## Reviewing the Okta App

When you review the integration, or when an auditor asks how Provisionr's access to Okta is limited, these are the settings to check in the Okta Admin Console.

* The scopes on the app's **Okta API Scopes** tab, which should match one of the [Scope Lists](#scope-lists)
* The app's **Admin roles** tab, which should list only the `Provisionr Sync` role and not `Super Administrator`
* The permissions of the `Provisionr Sync` role, which should match the list for the same access level, and the resource set that the role is assigned with
* The app's **Client authentication** setting, which should be **Public key / Private key**, and the active keys in its **Public keys** table
* The **Require Demonstrating Proof of Possession (DPoP) header in token requests** setting, which should be selected
* Okta's **Public client app admins** org setting, which Okta recommends turning off once you assign admin roles to apps yourself

***

Now that you know how Provisionr reaches the Okta API and where its access ends, the next page walks through what each sync does with that access, from reading your Okta users to writing group membership back.

[Continue reading: How the Okta Sync Works →](https://docs.provisionr.io/integrations/okta/sync.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.