About OpenID Connect (OIDC) with Persona
Persona now supports acting as an OpenID Connect (OIDC) Identity Provider (IdP) authenticator.
This allows Identity and Access Management (IAM) solutions, such as Okta, to call Persona for identity verification as part of authentication flows (e.g. application sign-on policies).
For example, your Okta administrator could require identity verification before an employee can access sensitive applications (such as those containing production or financial data).
This differs from Persona’s existing Okta integration as an IDV identity provider, which is exclusively triggered through Okta’s account management policy (OAMP).
You’ll need to configure the Authentications product feature to obtain the client ID and client secret used below.
Okta Configuration Guide
Follow the steps below to configure Persona OIDC as an Identity Provider in Okta.
1. Configure the Persona authentication template
In the Persona Dashboard, open your authentication template and add Okta’s callback URL to its allowed redirect URIs:
- Allowed redirect URIs:
https://<subdomain>.okta.com/oauth2/v1/authorize/callback. Replace<subdomain>with your Okta org’s subdomain (for example,companyincompany.okta.com). If your Okta org also uses a custom domain, add the same path on that domain too, for examplehttps://login.example.com/oauth2/v1/authorize/callback. Once you create the identity provider in the next step, Okta displays the exact value as the Redirect URI on the identity provider’s page.
2. Add Persona OIDC as an Identity Provider
In the Okta Admin Dashboard, navigate to:
- Security > Identity Providers > + Add Identity Provider
- Select OpenID Connect, scroll down, and click Next. Fill in the following details and save.
General Settings
- Name:
Persona IDP(use a distinct name from “Persona IDV”) - IdP Usage: Factor only
- Scopes: No changes
Client Details
- Client ID: obtain from Persona Dashboard in Authentications
- Authentication Type: Client secret
- Client Secret: obtain from Persona Dashboard in Authentications
- Authorize Requests: No changes
- PKCE: No changes
Endpoints
Use the values below or copy from:
https://authenticate.withpersona.com/authenticate/oidc/.well-known/openid-configuration
To test using your sandbox environment, use the following instead: Openid Configuration
Authentication Settings
- No setting changes
JIT Settings
- No setting changes
3. Add the IdP as an Authenticator
Navigate to:
- Security > Authenticators > Add Authenticator > IdP Authenticator
- Select the newly created Persona OIDC.
4. Update Authentication Policies
Navigate to:
- Security > Authentication Policies
- Create a new policy or edit an existing one.
To preserve administrator access in case Persona OIDC is unavailable, ensure at least one admin or group is excluded from this policy.
For testing, the Okta Dashboard policy can be useful.
Steps:
- Edit the Catch-all Rule or create a new rule
- Under Authentication Methods, select: Allow specific authentication methods > Persona IdP
5. Configure Persona Marketplace Integration for Employee Data
Context
Persona requires API access to your Okta tenant to retrieve employee profiles.
Each employee’s Persona account carries two identifiers: its Reference ID is the employee’s Okta user ID, and its email address is the employee’s Okta login email. These are the same accounts the Okta IDV integration uses, so an employee who uses both integrations has one Persona account.
Okta sends the employee’s login email to Persona as the login_hint. Persona defers account creation for this flow: the authentication starts without an account, your Inquiry looks up the employee in Okta by that email, then finds or creates the account by the Okta user ID and records both identifiers on it. A Workflow then attaches the account to the authentication.
Set up your authentication template and account type
- In your authentication template, turn on Skip account creation and map the
login_hintto the email address account identifier. - On the account type, enable the Identifiers configuration for the email address field so each email address belongs to only one account.
Set up profile attribute mapping
In order to ensure the employee being verified matches the Okta account being authenticated into, Persona needs to compare the values extracted from the employee’s government ID with the values stored in their Okta user profile.
The only information Okta passes in the authentication flow is the employee’s login email. Use the Persona Okta Marketplace integration to look up the employee’s profile using this email such that attribute comparison can be performed. The same lookup returns the employee’s Okta user ID, which Persona uses to find or create the account and records as its Reference ID.
Please ensure that the names that are stored in Okta are employee legal names, rather than preferred names or nicknames. If your Okta user profile’s firstName and lastName attributes do not store legal names, we recommend adding custom string attributes such as legalFirstName and legalLastName.
- Follow the Okta Marketplace integration guide to create an Okta API credential with permission to retrieve users. Add it under Integrations > Marketplace > Okta in the Persona Dashboard and use Test to check the connection.
- In a Persona Workflow, add an Okta Retrieve a user integration action. Use the username from the OIDC authentication to look up the employee’s Okta profile. If you are using custom attributes such as
legalFirstNameorlegalLastName, include them by specifyingprofile:(legalFirstName,legalLastName)in Fields to include. Leave the field blank to retrieve all profile attributes. - Map the retrieved legal first and last names to the Persona fields your verification flow uses to compare against the government ID. Check a test employee’s Okta profile and the retrieved Workflow output to confirm the mapped values are legal names, not nicknames.
Plans Explained
Okta Integration by plan
| Startup Program | Essential Plan | Growth Plan | Enterprise Plan | |
|---|---|---|---|---|
| Okta Integration | Not Available | Not Available | Limited | Available |