# How to configure Persona Authentications with OpenID Connect

> Set up Persona Authentications with your identity provider via OpenID Connect: prepare inquiry and authentication templates, then connect the IdP and test.

Source: https://help.withpersona.com/articles/1Acdx2QDfwgE1q3DTVPqW4/
Section: Authentications > Introduction > Using Authentications

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**](https://app.withpersona.com/dashboard/inquiry-templates?filter=%7B%22status%22%3A%5B%22active%22%5D%7D&sort=%7B%22sort%22%3A%22updated_at%22%2C%22shouldSortDescending%22%3Atrue%7D&currentPage=1&pageSize=25) 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-tenant.your-idp.com/oauth2/v1/authorize/callback)
- [`https://your-domain.your-idp.com/login/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

⚠️

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. See [Using Pushed Authorization Requests (PAR) for Persona Authentications](https://help.withpersona.com/articles/x9fUiSBIizAnfHL0o6a3SR/) for how the request and redemption steps work.

### TEFCA IAS configuration

If you are setting up Persona Authentications as a TEFCA Individual Access Services (IAS) provider, you must enable and configure the TEFCA extension:

1.  Enable the **TEFCA extension** toggle on your authentication template
2.  Enter your **Healthcare Common Identifier (HCID)** in the URN format: `urn:oid:` followed by your OID
    - Example: `urn:oid:2.16.840.1.113883.3.7204`

When enabled, Persona automatically includes your HCID in the `aud` (audience) claim of every ID token issued from this template. This audience value is required by the TEFCA network for token validation.

ℹ️

These controls are only available if your Persona account is configured for TEFCA Individual Access Services. Contact Persona support if you do not have access to the TEFCA extension settings. [See this article](https://help.withpersona.com/articles/ARLLoIOGw9P5nGlnC53uc/) for more information.

## Step 3: Configure your account type

By default, Persona resolves the account for an authentication using the `login_hint` your identity provider sends, so most OIDC integrations don't need any extra configuration here. Set up email address as an account identifier only if you want accounts keyed by email address specifically:

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.

### OIDC Issuer & Discovery Endpoints

Persona has a set of OIDC issuer and well-known discovery endpoints for sandbox testing and production environments.

**Sandbox**

| Property                 | Value                                                                                             |
| ------------------------ | ------------------------------------------------------------------------------------------------- |
| **Issuer (`iss`)**       | `https://authenticate.withpersona.com/authenticate/oidc-sandbox`                                  |
| **OpenID Configuration** | `https://authenticate.withpersona.com/authenticate/oidc-sandbox/.well-known/openid-configuration` |

**Production**

| Property                 | Value                                                                                     |
| ------------------------ | ----------------------------------------------------------------------------------------- |
| **Issuer (`iss`)**       | `https://authenticate.withpersona.com/authenticate/oidc`                                  |
| **OpenID Configuration** | `https://authenticate.withpersona.com/authenticate/oidc/.well-known/openid-configuration` |

## 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

If you need to inspect the token contents Persona returns as part of the OIDC flow, you can run a test directly in the Persona Dashboard:

- Open [Authentication Templates](https://app.withpersona.com/dashboard/authentication-templates?filter=%7B%22status%22%3A%5B%22active%22%5D%2C%22showArchived%22%3Afalse%7D&currentPage=1&pageSize=25)
- Click into the authentication template you want to test
- Scroll down to **Integration Guide**
- Click `Run Test` to view the resulting `authorization_code`, `id_token`, and `userinfo`

## 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.

_Last updated on August 21, 2026._