Skip to main content
If Okta is your Identity Provider (IdP), connecting it is the first thing you’ll do in a new Provisionr workspace, because the first integration that you create becomes your primary integration. You’ll set up Provisionr’s access in your Okta org with a public key and a least-privilege admin role, and then activate the integration so that the first sync can begin. This page covers the setup in this order:
  • How your primary integration is chosen
  • How Provisionr authenticates with Okta, and the access levels that you can choose from
  • The steps in Okta and in Provisionr to connect

Primary Integration

Your primary integration is the source of the unified Directory User profile. It provides each person’s name and email address, their manager relationships and employee ID, and the lifecycle timestamps for when they’re provisioned and deprovisioned as an employee or contractor. Every integration that you add after it enriches Directory Attributes and gives us the user metadata from that vendor, which we use to assign group and resource membership. The first integration that you create becomes your primary integration, and you can’t change it later. We recommend making your IdP your primary integration, because your IdP is the source of truth for Directory Users. If you already have a Google Workspace integration, then Google Workspace is your primary integration.
If Google Workspace is your IdP instead of Okta, stop here and create the Google Workspace integration before you create your Okta integration.
If Okta is your IdP, you’re in the right place. Create your Okta integration before any other integration so that Okta becomes your primary integration. From then on, each person’s Directory User follows their Okta status between staged, active, and suspended, and a person who is deprovisioned in Okta is deprovisioned in Provisionr as well. Okta Users explains how each Okta status is mapped.

Security Architecture

We authenticate with the Okta API using OAuth 2.0, through an API Services app integration in your Okta organization. Okta doesn’t allow client secrets to be used with the Okta management API, so Provisionr signs each token request with a private key instead, and Okta verifies the signature with the public key that you register on the app. Okta then returns a short-lived access token that is bound to Provisionr with Demonstrating Proof of Possession (DPoP). In other words, there are no passwords or static secrets that could be replayed if they were leaked. You decide what Provisionr can access with the Okta API scopes that you grant to the app and the custom admin role that you assign to it.
Okta OAuth2 Architecture explains each token request, what each Okta API scope and admin role permission allows, and how DPoP protects access tokens.

Access Levels

Provisionr can work with Okta at one of three access levels, and you choose one when you create the integration. Each level has a list of admin role permissions and a list of Okta API scopes with the same name. In the steps below, you’ll select the permissions from the list for your level, and you’ll also grant the scopes from the list with the same name. If you’re just getting started, you can begin with Audit (Read-Only). When you’re ready for Provisionr to make changes, you edit the role to add permissions, grant the read-write scopes, and change your access level. Admin Role Permissions explains why Provisionr needs each permission, and Access Levels and Policy Modes shows which sync stages run at each access level.

Connection Test

When you activate your integration, Provisionr tests your Okta app against the access level that you chose. Each access level is a set of capabilities, and a capability is one thing that Provisionr can do in Okta, such as reading users or adding someone to a group. The integration stays staged until every capability in your level passes, so a missing scope or admin role permission shows up right away instead of during a sync. Capabilities lists each one.

The Test Group

The two levels that write to Okta use a group named provisionr.connection-test. We use a group of our own because adding someone to a real group could give them its apps. The group stays empty between tests, and it should never have apps assigned. If it does, the test stops without adding anyone. Provisionr looks for the group by name and creates it if it’s missing. If your admin role can’t create groups, activation stops and asks you to create the group yourself. A group that you create counts for the test, so Provisionr then only confirms that Okta grants the scope for creating groups. Create a group in Okta named exactly provisionr.connection-test, leave it with no apps, and run prv okta-integration:activate again. Each write test adds two entries to your Okta System Log, one when the user is added and one when they’re removed. A passing test proves that Provisionr can change the members of this group. If you use a narrower resource set, make sure that it also includes the groups that your policies manage.

Testing Again

You can test your integration at any time with this Provisionr CLI command.
The command shows the result of each capability, and a failure doesn’t deactivate anything. Provisionr only uses a capability that’s in your access level and that the last test passed, so if the write test fails, you can’t change a policy to additive or authoritative until it passes. To change your access level, first update the admin role and the scopes in Okta, and then run this command. Provisionr tests your Okta app against the new level, and only saves it if the test passes.

Connecting Okta

Provisionr connects to Okta with a Provisionr-managed key. We generate the key pair for you inside Cloud KMS, and the private key can’t be exported by anyone, including us, so you only need to paste the public key into Okta. You keep full control of what Provisionr can access through the scopes and admin role that you assign to the app, and you can revoke access at any time from the Okta Admin Console.
1

Creating the Okta Integration

Start by creating a new Okta integration in your workspace with the Provisionr CLI.
The CLI prompts you for your Okta org URL, such as https://redshirt.okta.com, the environment type, and your access level. Okta Preview orgs (*.oktapreview.com) and custom domains are supported as well.Your integration is created in a staged state. Your workspace generates a key pair automatically and displays the public key as a JSON Web Key (JWK). The key ID (kid) starts with provisionr-, so that you can recognize it in Okta.
Provisionr Public Key JWK
Keep your terminal open. After you create the app in the Okta Admin Console in the steps that follow, you’ll come back to the CLI prompt to enter the app’s Client ID. If you close your terminal, run prv okta-integration:credentials to see the public key again and enter the Client ID.
2

Okta Super Administrator Role

The steps in Okta need an account with the Super Administrator role, because Okta only allows a Super Administrator to grant API scopes to an app and to create custom admin roles.If you don’t have that permission, ask your Okta administrator to perform these steps, and share the public key from the previous step with them.
Never assign the Super Administrator role to the Provisionr app itself. You’ll assign it a least-privilege custom admin role in an upcoming step.
3

Creating the Custom Admin Role

Okta API scopes control which API endpoints Provisionr can call, and an admin role controls which actions Provisionr can take on those endpoints, so your app needs both. Scopes and Admin Roles explains how the two work together.In the Okta Admin Console, go to Security > Administrators, open the Roles tab, and click Create new role. Fill in the role with these values:
  • Role name: Provisionr Sync
  • Role description: This is a custom role that allows Provisionr to view apps, users, and manage groups and group members.
Okta Create new role form with the name Provisionr Sync
Select the permissions in the list for your access level, and click Save role. Each list has the same name as the list of Okta API scopes that you’ll grant in an upcoming step.If you’re just getting started, you can start with Audit (Read-Only) and edit the role to add permissions when you’re ready for Provisionr to make changes.
The screenshots show the Groups + App Assignments permissions, and you can click a screenshot to enlarge it.
Okta Application permissions with View application and Edit application's user or group assignments selected

Application permissions

Okta Group permissions with four individual permissions selected

Selecting Manage groups also works, but we select each permission for least-privilege clarity.

Okta User permissions with four permissions selected

User permissions

Okta requires Edit application’s user or group assignments before Provisionr can change group members or app assignments, even when the group and user permissions are selected.
4

Creating the API Services App

In the Okta Admin Console, go to Applications and Resources > Applications and click Create App Integration.Select the Classic experience tab. These steps use the Classic experience because the new Okta Integration Wizard is still changing frequently.
Okta Create App Integration dialog with the Classic experience tab highlighted
Select API Services as the sign-in method, and click Next.
Okta Classic experience sign-in method options with API Services selected
Fill in the app with these values:
  • App integration name: Provisionr Sync
  • Client definition: Use Okta-generated client ID
Click Save.
New API Services App Integration form with the name Provisionr Sync
5

Adding the Public Key

On the General tab of your new app, find the Public keys section and click Edit.
Okta app Client Credentials and Public keys sections with the Public keys Edit link highlighted
Leave Configuration set to Save keys in Okta, and click Add key.
Okta Public keys section in edit mode with the Add key button highlighted
Paste the entire public key JWK that the Provisionr CLI displayed in the first step, and click Done. Don’t click Generate new key, because Provisionr can only sign with the key pair that it generated. You can ignore the Key Size option, which only applies to keys that Okta generates.
Okta Add a public key dialog with the Provisionr public key JWK pasted
The key is listed as Inactive until you change the client authentication method in the next step. Click Save.
Okta Public keys table with the inactive Provisionr key and the Save button highlighted
6

Enabling Public Key Authentication

In the Client Credentials section, click Edit.
Okta Client Credentials section with the Edit link highlighted
Select Public key / Private key for Client authentication, and click Save.
Okta Client authentication set to Public key / Private key
A client secret can’t be used instead. Okta only supports public key authentication for the Okta API scopes that Provisionr uses, so client secrets can’t be used to access the Okta management API.
Okta warns that the existing client secrets will be deleted. Provisionr doesn’t use client secrets, so click Save.Your public key is now Active.
Okta Public keys table with the Provisionr key in the Active status
7

Requiring DPoP

On the General tab, make sure that Require Demonstrating Proof of Possession (DPoP) header in token requests is selected. If it isn’t, click Edit in that section, select it, and click Save.With DPoP, Provisionr binds every access token to a key that only Provisionr has, so a leaked access token can’t be replayed by anyone else. Demonstrating Proof of Possession explains how it works.
8

Saving the Client ID

Copy the Client ID from the Client Credentials section and paste it at the Provisionr CLI prompt.Provisionr saves the Client ID with your staged integration. The Client ID is a public identifier, not a secret.
9

Granting Okta API Scopes

Provisionr needs Okta API scopes to read Okta users and apps and to manage groups and group members. OAuth2 Scopes describes what each scope allows.Open the Okta API Scopes tab of your app, and click Grant next to each scope in the list that matches the admin role permissions that you selected.
Okta API Scopes tab with a Grant button next to each scope

Okta API Scopes tab

10

Assigning the Admin Role

Go to Applications > Applications, open the Provisionr Sync app, open the Admin roles tab, and click Edit assignments.
Okta app Admin roles tab with no admin roles assigned and the Edit assignments button
Select the Provisionr Sync role and the default resource set, such as All Users, and click Save Changes. Okta may ask you to authenticate again.You can ignore the warning that the resource set includes resources that aren’t affected by the permissions in the role.
Okta role assignment form with the Provisionr Sync role and a resource set selected
After you save, check that the Admin roles tab lists only the Provisionr Sync role. If it also lists Super Administrator, remove it.Okta’s Public client app admins org setting can assign the Super Administrator role to API service apps automatically when scopes are granted. Okta recommends turning off this setting once you assign admin roles to apps yourself.
11

Activating the Integration

Now that you’ve registered the public key, granted the Okta API scopes, and assigned the admin role, activate your Okta integration with the Provisionr CLI.
The command runs the connection test for your access level. If it passes, the integration is activated, and the initial sync of your Okta users, groups, and apps into Provisionr begins. If it doesn’t, the command shows the reason, and you can run it again after you fix the app in Okta.How the Okta Sync Works walks through what each sync does, and Okta OAuth2 Architecture explains how Provisionr authenticates with Okta along the way.

Once your integration is active, the first sync reads your Okta users, groups, and apps into Provisionr. The next page looks more closely at how Provisionr authenticates with Okta, and at what each scope and admin role permission allows. Continue reading: Okta OAuth2 Architecture →