Enterprise identity verification vendor

Persona

This document explains how to configure

Persona

, an identity verification (IDV) vendor, as an identity provider (IdP) for your app. You can configure

Persona

as an IdP in your org by creating an account with

Persona

, adding it as an IdP in Okta, and then testing the configuration.

Note:

Persona

works as an IDV vendor, but is listed as an IdP in the Admin Console. This guide refers to

Persona

as an IDV vendor.

Okta manages the connection to the IDV vendor for your app, sitting between your app and the vendor that verifies your users. When a user signs in, you can verify their identity by having them submit a proof of identity to the IDV vendor.

---

Learning outcomes

Configure an IDV vendor so that your user’s identities are verified when they enroll a new authenticator.

Note: This guide describes the process for setting up an IDV flow in a sandbox environment of a

Persona

app. In a sandbox environment, there is no actual identity verification that verifies your user’s identities. You can use the same configuration process in a production environment in your

Persona

app.

See Sandbox vs. Production Environments (opens new window).

What you need

• Okta Developer Edition organization (opens new window)
• The Okta account management policy feature enabled for your org
• The Identity verification with third-party identity verification vendors feature enabled for your org
• An account with

  Persona (opens new window)

  with access to a sandbox environment
• A test user account (opens new window) that you can use to enroll an authenticator
• A test group (opens new window) in your org that the test user is added to
• A test image to use as a proof of identity

---

What is an IDV vendor

IDV vendors work like IdPs, with some key differences. Vendors verify your user’s identities by requiring them to submit a proof of identity. The proof of identity matches a user’s digital identity against a trusted data source. For example, a user’s first name and family name can be matched against a picture of their driver’s license or passport. The vendor verifies the user submission against a data source and that evaluation is sent back to Okta.

IdPs authenticate users by verifying their digital credentials. The IdPs also maintain the digital credentials.

Because of its stricter verification, you might only use an IDV vendor for sensitive operations. For example, use an IDV flow when a user enrolls a new authenticator or resets their password.

Create an app at the IDV vendor

At

Persona

(opens new window), create the client app to use for verifying your users.

Configure an IDV template

1. Create a

   Persona

   app.

2. In your

   Persona

   app, go to Inquiries > Templates.

3. Click Create template.

4. In the list of inquiry templates, select the Government ID and Selfie inquiry template. To test this template, you must have a camera that you can use to take a selfie.

   Note: If you want to use an inquiry template that doesn’t require a camera, use the Government ID (Front side only) inquiry template.

5. Click Configure.

6. Scroll down to Image capture methods > Capture Methods. Turn on File upload. Ensure that it’s turned on for at least one of the following:

   • Desktop web
   • Mobile web
   • Mobile native

   This allows you to upload the provided image when you test the integration.

7. Click Save. After you’ve saved, click Publish.

8. Go to Inquiries > Templates, find your Government ID and Selfie inquiry template.

9. Copy the Inquiry ID and paste it into a text editor so that you can use it in the next section.

Configure the API key and redirect URI of the

Persona

app

Note: In your

Persona

app, ensure that you're in a sandbox environment before you create an API key.

1. In your

   Persona

   app, go to API > API Keys.

2. Click Create API key. Enter a descriptive name for the API key.

3. Copy the API key and paste it into a text editor so that you can use it in the next section.

4. Go to Inquiries > Domain Manager.

5. In Allowed Domains, add a redirect URI. The redirect URI is your org’s URL. {yourOktadomain}.okta.com

   • The redirect URI is the location where

     Persona

     sends the verification response (the inquiry ID of the completed inquiry). The URI sent in the verification request from the client needs to match the redirect URI set at the IDV. Ensure that the URI is located in a secure domain that you own.
   • For example, if your Okta subdomain is called company, then the URL would be: company.okta.com. If you’ve configured a custom domain in your Okta org, use that value to construct your redirect URI, such as login.company.com.
   • Include all base domains (Okta domain and custom domain) that your users interact with in the allowed redirect URI list.

6. Click Add after you finish.

Other IDV vendor configuration

There are more settings for the

Persona

app that you can configure. The steps in this guide address the quickest route to set up

Persona

as an IDV vendor with Okta.

See the

Persona

documentation (opens new window) for more information about other configuration settings.

Create the IDV vendor in Okta

Use the IdP API (opens new window) to add Persona as an IDV vendor in Okta. Create your own POST request body or copy the example request and input your values.

Note: To add Persona using the Admin Console, see Add an Identity Verification vendor as Identity Provider (opens new window).

1. Set the following request body parameters:

   • Enter a value for name.

   • Set ID_PROOFING as the protocol type.

   • Use the API key from the previous section as the apiKey value.

   • Use the Inquiry Template ID from the previous section as the inquiryTemplateId value, which begins with itmpl_.

2. Send the POST /api/v1/idps request.

3. After you create the IDV vendor, copy the value of id from the response body and paste it into a text editor. Use it in the next section.

Example request

{
    "type": "IDV_PERSONA",
    "name": "Persona IDV",
    "protocol": {
        "type": "ID_PROOFING",
        "credentials": {
            "bearer": {
                "apiKey": "{PersonaAPIkey}"
            }
        }
    },
    "policy": {
        "provisioning": {
            "action": "DISABLED",
            "profileMaster": false,
            "groups": null
        },
        "subject": {
            "userNameTemplate": {
                "template": "source.userName"
            },
            "filter": null,
            "matchType": "USERNAME",
            "matchAttribute": null
        },
        "maxClockSkew": 0
    },
    "properties": {
        "inquiryTemplateId": "{PersonaInquiryTemplateId}"
    }
}

Example response

{
    "id": {"IDVId"},
    "name": "Persona IDV",
    "status": "ACTIVE",
    "created": "2024-11-15T15:22:17.000Z",
    "lastUpdated": "2024-11-15T15:22:17.000Z",
    "protocol": {
        "type": "ID_PROOFING",
        "endpoints": {
            "authorization": {
                "url": "https://withpersona.com/verify",
                "binding": "HTTP-REDIRECT"
            }
        },
        "credentials": {
            "bearer": {
                "apiKey": 
                    "{PersonaAPIkey}"
            }
        }
    },
    "policy": {
        "provisioning": {
            "action": "DISABLED",
            "profileMaster": false,
            "groups": null
        },
        "subject": {
            "userNameTemplate": {
                "template": "source.userName"
            },
            "filter": null,
            "matchType": "USERNAME",
            "matchAttribute": null
        },
        "maxClockSkew": 0
    },
    "properties": {
        "inquiryTemplateId": "{PersonaInquiryTemplateId}"
    },
    "type": "IDV_PERSONA",
    "_links": {
        "users": {
            "href": "https://{yourOktadomain}/api/v1/idps/0oal68on4q8cch2y55d7/users",
            "hints": {
                "allow": [
                    "GET"
                ]
            }
        },
        "deactivate": {
            "href": "https://{yourOktadomain}/api/v1/idps/0oal68on4q8cch2y55d7/lifecycle/deactivate",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        }
    }
}

Create an Okta account management policy rule

Use the Policies API (opens new window) to create a rule that requires users to be verified by the IDV vendor when they enroll a new authenticator. Create your own POST request body or copy the example request and input your values.

Ensure that you’ve created a user account and group for that user. For example, add the user to a group called “Persona IDV test group”.

Note: To add a rule using the Admin Console, see Edit the Okta account management policy (opens new window).

1. Retrieve the Okta account management policy ID. Use the Okta account management policy id as the policyId value in your POST request to create the IDV rule.

2. Set the following request body parameters for the new IDV rule that you want to create:

   • Provide a name value.
   • Use the Okta account management policy id as the policyId value.
   • Set the group ID. Use the List all groups call (opens new window) to find the id for the test group.
   • Set the verificationMethod type to ID_PROOFING.
   • Set the verificationMethod > id to the Okta Persona IdP that you created in the previous section.
   • Set appSignOn access value to ALLOW.
   • Use the following Okta Expression Language object:

       "elCondition": {
           "condition": "accessRequest.operation == 'enroll'"
       }
   

   This expression requires users to verify their identity with the IDV vendor when they enroll a new authenticator.

3. Send the POST /api/v1/policies/{policyId}/rules request.

Okta account management policy rule example request

{
    "name": "Require IDV for authenticator enrollment",
    "priority": 1,
    "type": "ACCESS_POLICY",
    "system": false,
    "conditions": {
        "people": {
            "groups": {
                "include":
                    ["{groupId}"]
            }
        },
        "network": {
            "connection": "ANYWHERE"
        },
        "riskScore": {
            "level": "ANY"
        },
        "elCondition": {
            "condition": "accessRequest.operation == 'enroll'"
        },
        "userType": {
            "include": [],
            "exclude": []
        }
    },
    "actions": {
        "appSignOn": {
            "access": "ALLOW",
            "verificationMethod": {
                "id": "{IDVId}",
                "type": "ID_PROOFING"
            }
        }
    }
}

Example response

{
    "id": "ruleId",
    "status": "ACTIVE",
    "name": "Require IDV for authenticator enrollment",
    "priority": 1,
    "created": "2024-11-14T21:16:55.000Z",
    "lastUpdated": "2024-11-14T21:16:55.000Z",
    "system": false,
    "conditions": {
        "people": {
            "users": {
                "exclude": []
            },
            "groups": {
                "include": [
                    {"groupId"}
                ]
            }
        },
        "network": {
            "connection": "ANYWHERE"
        },
        "riskScore": {
            "level": "ANY"
        },
        "elCondition": {
            "condition": "accessRequest.operation == 'enroll'"
        },
        "userType": {
            "include": [],
            "exclude": []
        }
    },
    "actions": {
        "appSignOn": {
            "access": "ALLOW",
            "verificationMethod": {
                "id": {"IDVId"},
                "type": "ID_PROOFING"
            }
        }
    },
    "_links": {
        "self": {
            "href": "https://{yourOktadomain}/api/v1/policies/rstjqw4t47yn9lXUK5d7/rules/rull5mrtqkAVfIyWT5d7",
            "hints": {
                "allow": [
                    "GET",
                    "PUT",
                    "DELETE"
                ]
            }
        },
        "deactivate": {
            "href": "https://{yourOktadomain}/api/v1/policies/rstjqw4t47yn9lXUK5d7/rules/rull5mrtqkAVfIyWT5d7/lifecycle/deactivate",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        }
    },
    "type": "ACCESS_POLICY"
}

Test the integration

You can test your integration by using the rule that you configured in the previous section.

1. Sign in to your org as the user that you created.
2. Click your username.
3. Go to My Settings.
4. Select Security Methods, and then set up a new authenticator.

If the IDV vendor is set up correctly, you’re prompted to verify your identity and redirected through the

Persona

IDV flow. Then, the user you created can successfully enroll an authenticator.

Test image

Use the following image if your verification template requires you to upload a photo. Save the image and then select it when you're prompted to upload a photo.

Alternate use cases

You can use

Persona

to verify your user identities in different scenarios. Use the following Okta Expression Language expressions for different scenarios.

Note: You can use the Okta account management policy rule without any expression. If you don't use any expression in the rule then your user is prompted to verify their identity when the following events occur:

• They enroll or unenroll authenticators

• They edit their personal information in their My Settings

Verify user identity only when they enroll an authenticator

accessRequest.operation == 'enroll'

Verify user identity only when they reset their password

accessRequest.authenticator.key == 'okta_password' && accessRequest.operation == 'recover'

Verify user identity only when they enroll phishing-resistant authenticators

{
  'okta_verify',
  'webauthn',
  'smart_card_idp',
  'yubikey_token'
}.contains(accessRequest.authenticator.key) &&
accessRequest.operation == 'enroll'

Troubleshooting

When you test the integration, if you’re not redirected to the IDV flow, review the following areas:

• Review the user and group that you created. Ensure that you’ve set the correct group ID when you create the Okta account management policy rule.

• Review the Okta account management policy rule. Ensure that you’ve added the correct Okta Expression Language expression and that the verificationMethod type is set to ID_PROOFING.

• Ensure that your user has the authenticators that they're allowed to enroll.

• Ensure that your API key was created in the sandbox environment.