- 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.
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.
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.readallows 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.
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.
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 asokta.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.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
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. Theprv.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
TheProvisionr 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 asAll 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 Syncrole and notSuper Administrator - The permissions of the
Provisionr Syncrole, 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 →