The legacy Persona identity verification (IDV) provider for Okta’s Account Management Policy uses a Persona API key. The new Persona IDV integration uses OpenID Connect (OIDC), Pushed Authorization Requests (PAR), and Verified Claims. Okta’s legacy API-key-based Persona IDV integration reaches end of life on September 15, 2027. Migrate before then, but keep the existing provider and policy rules in place until the new integration passes your tests.
This guide is for organizations already using the legacy Okta IDV provider. If you are setting up IDV for the first time, use Configure Persona for the Okta Account Management Policy instead. If your provider is already Custom ID verification with OIDC and PAR, the API-key migration does not apply. This is not the Okta SSO setup for signing in to the Persona Dashboard or Persona as an authentication method in Okta application sign-on policies.
Before you start
- Use an Okta Identity Engine tenant with Account Management Policies and the required MFA or Adaptive MFA capability. Arrange Okta administrator access to manage identity providers, profile mappings, and policy rules, and Persona Dashboard access to view, copy, edit, and publish Inquiry Templates and their associated Workflows. Coordinate with your Okta and Persona administrators if these permissions belong to different people.
- In Okta Admin, find the existing Persona provider under Security > Identity Providers. If you have more than one, check which is selected in each Security > Authentication Policies > Account Management Policy rule. On that provider’s configuration page, note the existing Inquiry Template ID (
itmpl_…). Identify the matching template in the Persona Dashboard and record any custom checks, branding, and connected Workflows you need to preserve. - Confirm that the Okta profile attributes you plan to verify contain employees’ legal first and last names, not preferred names. If necessary, map legal-name attributes in Okta. Inventory your Okta tenant’s default domain and any custom domains, plus a test user or group whose OAMP rule you can change without affecting everyone else.
Migrate with the wizard
Open the Okta legacy IDV migration wizard in the Persona Dashboard. If the wizard is unavailable in your organization, ask your Persona account team for migration assistance before changing policies. Complete the steps for each Okta tenant you are migrating. Keep your original provider, template, and production policy rules active while you prepare the replacement.
- Select the existing Inquiry Template. Match the wizard’s template to the
itmpl_ID on the legacy Okta provider. The wizard copies that template rather than changing the flow employees currently use. - Inspect the copied template. The wizard prepares the copy for the new IDV protocol, including comparing government ID data against Okta-supplied Account attributes rather than overwriting them with data from the Inquiry. Review its verification checks, legal-name comparison, customizations, and any changes it could not complete. If the copy fails, use the wizard’s retry or manual-copy path instead of changing the live template. Connected Workflows can be set to trigger for both the original and the copy; review their downstream actions for duplicate or unintended effects.
- Review and publish the copy. Publish the new template when its checks and connected Workflows are ready. Publication does not switch Okta’s existing policy rules; the original template continues to serve the legacy provider until cutover.
- Find your current Persona IdP in Okta. Under Security > Identity Providers, open the provider used by the existing Account Management Policy rule and keep its configuration available for comparison. Do not edit or remove it yet.
- Add your Okta domain or domains in the wizard. Include your tenant’s default Okta-hosted domain even if employees use a custom domain. Add other domains that will send requests and confirm their callback URLs are allowed. Repeat the remaining Okta configuration for each tenant you connect.
- Create the replacement provider. In a production Okta tenant, add the Persona IDV Identity Provider from the Okta Integration Network and enter the client details the wizard supplies. For testing against a Persona Sandbox environment, choose Okta’s Custom IDV tile instead: the Persona IDV tile connects only to Persona Production. Copy the Sandbox-specific OIDC endpoints and other settings from the wizard rather than using Production values. Keep client secrets in the Okta configuration, not in a shared document.
- Copy the profile attribute mapping. In the new provider, use Edit profile and mappings to map
givenNameandfamilyNameto the employees’ legal names. Both are required. Mapbirthdateonly if your existing integration sends it and the new Inquiry verifies it. Only send attributes that Persona actually verifies: do not map unverified email, phone number, or other values as Verified Claims. Check that the claims configured in Persona match the attributes mapped in Okta; the Persona IDV setup guide explains this requirement. - Add a test-only policy rule. Under Security > Authentication Policies, add a rule to the relevant Account Management Policy scoped to your test user or group. Allow the action after successful identity verification and select the new Persona provider as its Identity Verification Service. Check the rule’s order and conditions so the test user actually matches it. Leave the rules serving everyone else on the legacy provider.
- Test before cutover. As a test user, initiate an action protected by that OAMP rule, such as a password reset (you can confirm the IDV step before completing a reset). Confirm the user reaches the new Persona Inquiry, completes it, returns to Okta, and can continue only when verification succeeds. Test a mismatched or unsuccessful result as appropriate for your policy. Investigate any failures before changing production rules.
- Cut over every applicable rule. Once testing succeeds, replace the legacy provider with the new one in all Okta Account Management Policy rules that reference it. Check each rule and representative users or groups, monitor the Okta System Log and Persona Authentications, and confirm that new IDV requests use the replacement provider.
Troubleshooting and cleanup
- Persona does not open: Check that the test rule matches the user and selects the new provider. Confirm the Okta domains, callback configuration, client details, and PAR settings shown by the wizard. In the Okta Reports > System Log, inspect denied events. A PAR error can indicate that Okta’s mapped attributes differ from Persona’s Verified Claims configuration.
- The Inquiry fails or Okta rejects a completed Inquiry: Inspect the Authentication and associated Inquiry in the Persona Dashboard and the failure in Okta’s System Log. Confirm legal-name matches, required
givenNameandfamilyNamemappings, and that no Inquiry action overwrites Okta-provided Account values. Okta requires returned claims to match what it supplied; do not mark an unverified value as verified. See the Persona IDV troubleshooting guidance. - After a verified cutover: Keep the old provider and its API key until you have confirmed every relevant rule, tenant, and user group is using the replacement and no other integration depends on that key. Then remove the unused legacy Okta provider and revoke its Persona API key if it was dedicated to this integration. If a test fails before cutover, leave the production rules on the legacy provider and correct the new configuration. If a problem appears after cutover, restore the affected rule to the still-active legacy provider while you investigate. Do not retire your working fallback until the replacement is stable.
Plans Explained
Okta Integration by plan
| Startup Program | Essential Plan | Growth Plan | Enterprise Plan | |
|---|---|---|---|---|
| Okta Integration | Not Available | Not Available | Limited | Available |