How to trigger Persona identity verification within Okta using the Persona IDV integration

What is Okta workforce authentication?

Okta is used by companies of all sizes as a workforce authentication solution. The cloud-based Identity and Access Management (IAM) platform is designed to securely manage and streamline access for employees, contractors, and partners to enterprise applications, systems, and resources that need to be kept secure.

How Persona identity verification supports Okta workforce authentication

With the rise of social engineering and deepfake attacks, protecting a distributed and remote workforce is increasingly difficult. Persona adds a crucial layer of security by automatically verifying employees’ identities at sensitive moments throughout the employee lifecycle, such as new employee onboarding, account recovery, and the editing of sensitive information.

For businesses already using Okta, Persona is listed in the Okta Integration Network (OIN) as the Persona IDV integration, so it’s easily integrated, offers an added component of security to access controls, and helps keep employees from being blocked.

How to set up Persona Authentications for Okta workforce authentication

As part of this solution, you will need to configure Persona Authentications with OpenID Connect. Additionally, you will need to configure Verified Claims in order to work with Okta BYO IDV.

Follow the steps above to create an Authentication Template and connect it to your Inquiry Template.
Enable the following in the Authentication Template:
- Add Okta’s redirect URI: https://{yourOktaDomain}/idp/identity-verification/callback
- Enable ‘Require Pushed Authorization Requests (PAR)’
- Enable ‘Require PKCE’
Under the Verified Claims section of your Authentication Template, map each claim Okta should receive back to the corresponding field in your Inquiry Template. This controls how Okta’s provided base truth verified claim values are written to the Persona account, and how Persona writes back verified claim values from IDV to Okta. The exact fields will depend on your Okta configuration.
- At minimum, given_name and family_name should be configured. Only configure fields that you also configured Okta to send.
- Your Inquiry Template should NOT write values back to the Account upon successful verification (e.g. with the Update Account from Inquiry action). The Okta-sent verified claims are the base truth values and are written to the Persona Account. If the Inquiry modifies these field values on the Account, the verified claims check will fail.
- You may also configure a custom boolean field, such as id_verified, to indicate to Okta that the verified claim value Persona is returning was verified in the Inquiry flow. Your Inquiry Template should use the Update Object action to set this field at the point where values are actually verified. Data that is not verified (e.g. a self-reported phone number collected without running Phone Verification) should not set this field. The exact configuration of these boolean field(s) will depend on the data your Inquiry template is collecting and verifying.
Record the client ID and client secret to use in the next step.

Capturing the Okta user identifier and email address

Verified Claims are only checked on the redirect back to Okta, so they aren’t a reliable way to get Okta’s user identifier or email address onto the Persona Account — for example, to look up or create the right Account when your Inquiry Template uses deferred account creation, or to email the employee if verification fails. Persona recommends the following standard configuration instead:

Okta user identifier: Okta passes the employee’s Okta ID as the login_hint query parameter when it launches the Persona flow. Add a field to your Inquiry Template (for example, okta_oid), then add a query parameter-to-Inquiry-field mapping from login_hint to that field under your Inquiry Template’s settings. This populates correctly even when account creation is deferred. Note that nested claim values (e.g. given_name) are not available as top-level query parameters and can’t be mapped this way — only parameters like login_hint can.
Email address: Rather than configuring a claim like email_verified to always return true (which doesn’t represent an actually-verified value and undermines the intent of the Verified Claims spec), use Persona’s Okta Marketplace integration in a Workflow to look up the employee’s email directly from Okta (the Retrieve a user action), then write it to the Account with the Update Object action. This is the recommended pattern going forward — it also gives you the flexibility to use an identifier other than the Okta ID for account lookup, if needed.

How to set up Persona as your Identity Provider in Okta

To learn more about the Okta Account Management Policy, see the Okta documentation here. Please note, identity verification is only available for Okta Identity Engine (not Okta Classic) tenants, and requires MFA/AMFA features.

Follow the steps here and search the Okta Integration Network catalog for Persona IDV to add Persona as an Identity Provider. If you have multiple Persona Templates you want to use, make sure to name the Identity Provider appropriately so you can distinguish between them (we recommend the same name as the Persona Inquiry Template).
Fill in your Authentication Template’s Client ID and Client Secret.
Update the User attributes mapping to include the attributes you want to verify with Persona. These will be sent to Persona as Verified Claims. This must EXACTLY match the previously configured Authentication Template Verified Claims.

Configuring the policy

Under Security > Authentication Policies, click on your Okta Account Management Policy. Click on Add Rule and configure to your specifications (we recommend restricting this rule to a test group first). Under Identity Verification Service, select the appropriate Persona Identity Provider.

Updating your Password Policy

Edit your Password Policy rules to use the OAMP to determine the authenticators a user is prompted for.

Testing the policy

One of the easiest ways to test the integration is to go to the End User settings in Okta and attempt to change a security method. This triggers the Account Management policy and will bring the user through the Persona flow.

How the integration between Persona and Okta works

Upon the Authentication Policy rule trigger, the integration will create an OIDC authentication for the employee with:
1. The client ID and secret provided in the BYO IDV configuration.
2. The employee’s Okta ID as the Persona account’s reference-id (which will serve as the account identifier for Persona).
3. The employee’s first and last name from the Okta Universal Directory, as Inquiry fields.
4. A redirect URL (to get back to Okta). If you are using domain allowlisting, you will need to add your Okta tenant’s domain (e.g. persona.okta.com), or inquiry creations will be rejected.
The employee will be instructed to go through the Persona inquiry — a button in the Okta flow will bring them to a hosted Persona Inquiry page.
Once the employee has completed the inquiry, they will be redirected back to an Okta webpage.
If the authentication passes (all verifications have passed), the employee will be allowed to continue. Otherwise (at least one verification has failed), the user will be prevented from continuing.

Note that employees will have a limited period of time to complete identity verification. If they take more than ten minutes to verify, they may encounter an error and could potentially need to re-start the verification flow.

Understanding and making changes to your Inquiry template

Your template comes pre-configured via our standard recommendations for the Know Your Employee verification experience, but is customizable in the following ways:

Updating inquiry configurations and verification checks to require more or less friction for your employee (for example: requiring that the barcode of any drivers’ licenses be captured and scanned, or only allowing IDs from certain countries). Please refer to the Google spreadsheet given to your team for an in-depth explanation of Persona’s verification checks and other available configurations.
Configuring the colors of your template to match your company’s brand.
Adding any custom text to help your employees through the process.

Troubleshooting

Persona is not opening when triggering OAMP

If the Persona flow does not open at all, an error is likely happening when Okta is attempting to create the Persona Authentication.

In the Okta Admin dashboard, navigate to Reports > System Log and filter for outcome.result eq "DENY". These logs may include error messages or other context to help identify the issue. For example, ReasonForFailure may say PAR response doesn't have an HTTP 201 status code, instead received a status code of 400. This implies a misconfiguration; for example, this error can happen if the Verified Claims configured in the Persona Authentication Template do not match the user attribute mapping configured in the Okta Identity Provider.

The Persona Inquiry flow is unexpectedly failing

Find the Authentication in the Persona Dashboard here. If it is failed, investigate the associated Inquiry to determine why. The failure may be a configuration error or user error.

The Persona Inquiry flow is passing, but OAMP fails

If the Persona flow opens and passes, but an error is encountered when redirecting to Okta, it is likely that the OIDC ID token does not match what Okta expects. Ensure that you are not writing new values from the Inquiry to the Account’s Verified Claims fields; any mismatch between the Verified Claim values Okta sends and the Verified Claim values on the Persona Account will result in an ID token error.

In the Okta Admin dashboard, navigate to Reports > System Log and filter for outcome.result eq "FAILURE". These logs may include error messages or other context to help identify the issue.