Skip to main content
When you connected Okta, 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
This page explains the design behind the connection to Okta. For the setup steps, see Connect to Okta.

OAuth 2.0 Client Credentials

Provisionr connects to the Okta API with OAuth 2.0 and an API Services app, which is the approach that Okta strongly recommends.
To access Okta users, groups, and apps through the API, we authenticate with Okta’s implementation of OAuth 2.0 for an API Services app, 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 guide.
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. 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 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.
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 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 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.
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 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, 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, and each one matches the 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.

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 explains how people are represented in your directory, and Okta Users 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 describes what each access level allows. Okta Groups explains how group membership is read down and written back.
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 explains how apps and their assignments are read, and how each app’s Provisionr group works.
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 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 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 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.

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. Each list matches the list in 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)

Groups Only (No App Cleanup)

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

Groups + App Assignments

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

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

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
  • 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 →