This document explains how to configure a custom IDV vendor as an identity provider (IdP) for your org. You can configure a custom IDV vendor as an IdP in your org by creating an account with the vendor, adding it as an IdP in Okta, and then testing the configuration. If you don't have a custom IDV vendor that you want to use, you can create your own IDV service and use this guide to add it as an IdP.
Note: IDV vendors are listed as IdPs in the Admin Console. This guide refers to the custom IDV vendor as an IDV vendor.
Learning outcomes Configure a custom IDV vendor so that your user’s identities are verified when they enroll a new authenticator.
What you need 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 When you create a custom IDV vendor integration in your org, the vendor must first provide the following information:
Requirement Description Instance name The vendor must have a client app that can communicate with Okta. The Instance name is the unique name of that app. End user license agreement (EULA) The vendor must provide a URL that links to an EULA that your users must accept before using the IDV vendor. Vendor name The vendor must provide a name that identifies the IDV vendor. This name is displayed to users during IDV flows, in the Sign-In Widget. Privacy policy The vendor must provide a URL that links to a privacy policy that explains the vendor's privacy practices. Client ID The vendor must provide a client identifier for the app that you create at the vendor. Client secret The vendor must provide a client secret for the app that you create at the vendor. Issuer URL The vendor must provide a URL that identifies the IDV vendor. This is the base URL for the IDV vendor’s authorization server. PAR request URL The vendor must provide a URL that Okta uses to send pushed authorization requests (PAR) to the IDV vendor. Authorize URL The vendor must provide a URL that Okta uses to redirect users to the IDV vendor for identity verification. Token URL The vendor must provide a URL that Okta uses to exchange the authorization code for an access token and an ID token. JWKS URL The vendor must provide a URL that Okta uses to retrieve JSON Web Key Set (JWKS) from the IDV vendor.
For more information about these requirements, see Integrate Okta with identity verification vendors .
After your IDV vendor provides this information, you can create the IdP integration in your org.
Note: Your IDV vendor might have other configuration settings. Refer to your IDV vendor's documentation for more information about other configuration settings.
Create the IDV vendor in Okta Use the IdP API(opens new window) to add your custom IDV vendor in Okta. Create your own POST request body or copy the example request and input your values.
Note: To add a custom IDV vendor using the Admin Console, see Add an Identity Verification vendor as Identity Provider(opens new window) .
Set the following request body parameters:
Enter a value for name. Set type to IDV_STANDARD. Set ID_PROOFING as the protocol type. Use the Client ID and Client Secret values from the previous section as the client_id and client_secret values. Use the URLs that your IDV vendor provided in the following parameters:
issuer.url: The Issuer URL that your IDV vendor provided.endpoints.par.url: The PAR request URL that your IDV vendor provided.endpoints.authorization.url: The Authorize URL that your IDV vendor provided.endpoints.token.url: The Token URL that your IDV vendor provided.endpoints.jwks.url: The JWKS URL that your IDV vendor provided. Set the properties.idvMetadata object values:
vendorDisplayName: The Vendor name that your IDV vendor provided.termsOfUse: The End user license agreement (EULA) URL that your IDV vendor provided.privacyPolicy: The Privacy policy URL that your IDV vendor provided. Set the scopes array to include the profile, identity_assurance, and openid scopes.
profile: This scope allows the IDV vendor to request access to basic user profile information from Okta.identity_assurance: This scope requests access to the verified_claims object so that the IDV vendor can send and receive information about the level of assurance of the IDV flow.openid: This scope is required to make the request an OpenID Connect (OIDC) request. Send the POST /api/v1/idps request.
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 Example response Map profile attributes from Okta to your IDV vendor After you've created the IDV vendor in Okta, you can map other profile attributes from your user directory to attributes in your IDV vendor. Okta sends the givenName and familyName attributes by default. You can map other attributes as needed. See Map profile attributes from Okta to an identity verification vendor(opens new window) .
Create an Okta account management policy rule Use the Policies API(opens new window) to create a rule that requires your custom IDV vendor to verify users 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 group for users who you want to verify with your custom IDV vendor. For example, create a group called "Custom IDV test group".
Note: To add a rule using the Admin Console, see Edit the Okta account management policy(opens new window) .
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.
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 as the ID of the custom IDV vendor IdP that you created in the previous section . Set appSignOn access value to ALLOW. Use the following Okta Expression Language object: This expression requires users to verify their identity with the IDV vendor when they enroll a new authenticator.
Send the POST /api/v1/policies/{policyId}/rules request.
Okta account management policy rule example request Example response Test the integration After you've configured your custom IDV vendor and created the Okta account management policy rule, you can test the integration.
Testing the integration can depend on your IDV vendor. Depending on your vendor, you might be able to use a sandbox environment to complete the verification. Refer to your IDV vendor's documentation for more information about testing the integration.
However, there's a simple way to test if the Okta account management policy and IDV vendor are set up correctly in your org. Try to enroll an authenticator using your test user. If your IDV vendor and policy are set up correctly, that user is prompted to verify their identity with the IDV vendor before they can complete the enrollment.
Note: Your user may not be able to complete the IDV flow if their information doesn't match the verifiable information required by your IDV vendor. Review the System Log(opens new window) if you encounter errors when testing the IDV flow. See Identity verification events for information about IDV events in the System Log.
Alternate use cases You can use your IDV vendor 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 at least one of the following events occurs:
They enroll or unenroll authenticators.
They edit their personal information in their Settings .
They reset their password in Settings or in the Sign-in widget.
They unlock their account.
Verify user identity only when they enroll an authenticator Verify user identity only when they reset their password Verify user identity only when they enroll phishing-resistant authenticators 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.
