How to configure Persona Authentications with OpenID Connect

Persona Authentications is a product that enables you to trigger identity verification flows when users authenticate to your systems via OpenID Connect (OIDC). This guide will walk you through configuring Authentications to work with your identity provider (IdP).

Prerequisites

Before you begin, ensure you have:

• Admin access to your Persona Dashboard
• Access to your identity provider for configuration

Overview

When you set up Authentications with OIDC, Persona acts as an identity provider that verifies a user’s identity before they’re allowed to sign in to an application.

At a high level, the authentication flow works as follows:

1. A user attempts to log in to your application
2. Your identity provider redirects them to Persona for identity verification
3. The user completes a verification inquiry (e.g. a selfie or government ID verification)
4. Upon successful verification, Persona returns authentication tokens to your IdP
5. The user gains access to your application

Step 1: Prepare your inquiry template

Your inquiry template defines what verification steps users will complete during authentication.

1. Go to Inquiry Templates in your Persona Dashboard
2. Either select an existing template or create a new one
3. Configure your template with the appropriate verification steps. For authentication use cases, we recommend:
   • Starting with a selfie verification for fast re-authentication
   • Optionally adding a government ID verification for first-time users or when additional verification is needed
   • Setting the inquiry expiration to approximately 10 minutes to keep authentication sessions transient
   • Configuring the final step as a Complete step type to automatically redirect users back to your application

Important: Make sure your inquiry template has been published to reflect new changes.

Step 2: Create an authentication template

Authentication templates connect your inquiry template to your identity provider via OIDC.

1. Navigate to Authentications in your Persona Dashboard
2. Click Create authentication template
3. Select your prepared inquiry template
4. Choose the User account type (this is the default and works for most use cases)
5. Configure your authentication template settings

Required configuration

Redirect URIs: Add the callback URL(s) from your identity provider. Your IdP will provide these URIs. They typically look like:

• https://your-tenant.your-idp.com/oauth2/v1/authorize/callback
• https://your-domain.your-idp.com/login/callback

You can add multiple redirect URIs if your IdP has custom domains or multiple environments.

Get your credentials

After creating your authentication template:

1. Go to the Clients section
2. Copy your Client ID and Client Secret
3. Share these credentials securely with your identity provider administrator

⚠️ Security note: Treat the Client Secret like a password or API key. Use secure methods to share it (avoid sending it via unencrypted email or chat).

Optional configurations

PKCE (Proof Key for Code Exchange): Enable this if your identity provider requires PKCE for enhanced security.

PAR (Pushed Authorization Requests): Enable this if your identity provider requires pushed authorization requests.

Step 3: Configure your account type

For most OIDC integrations, you'll need to set up email address as an account identifier:

1. Go to Account Types in your Persona Dashboard
2. Select the User account type
3. If an email address field doesn't exist, add it
4. In Field details, enable the Identifiers configuration for the email address field

This allows Persona to uniquely identify users by their email address during authentication.

Step 4: Connect your identity provider to Persona

Provide your identity provider administrator with:

• Your Persona Client ID and Client Secret
• Persona's OIDC endpoints (these are automatically generated and visible in your authentication template)

Your IdP administrator will configure Persona as an external identity provider or authentication factor in their system.

Refer to your identity provider's documentation for specific setup instructions, or contact Persona support for assistance with specific IdP configurations.

Step 5: Test your integration

After configuration is complete:

1. Attempt to authenticate through your identity provider
2. Verify you're redirected to Persona for identity verification
3. Complete the verification flow
4. Confirm you're redirected back and successfully authenticated

Advanced configuration

Integrating with your source of truth

For workforce identity use cases, we recommend integrating Persona with your directory service to retrieve employee profile information for comparison during verification.

You can set up these integrations through:

• Marketplace integrations in Persona Dashboard
• Account imports to pre-populate user data
• API integrations to fetch user data during the verification flow

This ensures Persona can verify that the person completing verification matches the expected employee profile.

Verified email and phone number claims

If you need to include email_verified or phone_number_verified claims in your OIDC tokens:

1. Add boolean fields with these names to your User account type
2. Create workflows that set these fields to true after successfully verifying email or phone number ownership

Troubleshooting

Authentication fails after completing verification: Ensure your redirect URIs are correctly configured in your authentication template and match exactly what your IdP expects.

Users can't complete verification on mobile: Check your inquiry template's device handoff settings to ensure mobile flows are properly enabled.

"Inquiries per account limit" errors: Make sure your organization doesn't have an account inquiry limit set, as authentication creates new inquiries for each login attempt.

Need help?

If you need assistance configuring Authentications with your specific identity provider, contact Persona support with details about your IdP and use case.