Persona Authentications sits inside your sign-in flow as an identity provider, using OpenID Connect (OIDC) to talk to whatever sends users to it. This article covers the OIDC concepts the rest of the Authentications articles assume: the roles in the protocol, the tokens it issues, and how a Persona authentication template and inquiry line up with those concepts. For the setup steps themselves, see How to configure Persona Authentications with OpenID Connect.
The two roles in OIDC
OIDC is an identity layer on top of OAuth 2.0. It defines two parties:
- The relying party (RP), the application that wants to know who a user is. This is your identity provider (IdP) or your own application, depending on how you have wired up your sign-in flow.
- The OpenID provider (OP), the service that authenticates the user and issues tokens vouching for their identity.
Persona Authentications is the OpenID provider. Your IdP (or your application, if it talks to Persona directly) is the relying party.
The authorization code flow
Persona implements the OIDC authorization code flow, which moves through three endpoints:
| Endpoint | Purpose |
|---|---|
/authorize | Starts the flow. The relying party sends the user’s browser here. |
/token | Exchanges a one-time authorization code for tokens, over a direct backend request. |
/userinfo | Returns account-backed claims for the authenticated user, filtered by scope. |
At a protocol level, the flow looks like this:
- The relying party redirects the user’s browser to Persona’s
/authorizeendpoint with aclient_id,redirect_uri, and the requestedscope. - Persona authenticates the user, in our case by running them through a verification inquiry, then redirects back to the relying party’s
redirect_uriwith a one-time authorizationcode. - The relying party exchanges that
codeat/tokenfor anid_tokenand anaccess_token. - The relying party can optionally call
/userinfowith theaccess_tokento fetch additional claims.
id_token vs. access_token
| Token | What it’s for |
|---|---|
id_token | A signed JWT asserting who the user is. Read its claims directly; it’s meant for the relying party, not for calling an API. |
access_token | An opaque or signed credential the relying party presents to /userinfo to fetch more claims about the user. |
Scopes (like openid) and claims requests determine what shows up in each token. Persona publishes OIDC issuer and discovery endpoints for sandbox and production; see How to configure Persona Authentications with OpenID Connect for the exact URLs.
How Persona’s objects map onto OIDC
The protocol concepts above map onto three Persona objects:
- Authentication template is the OIDC client configuration: redirect URIs, scopes, the client authentication method, and any claim mappings. Every authentication template is bound to one inquiry template, which is what actually verifies the user.
- Authentication is a single run of that flow, one sign-in attempt by one user. It’s the object that ties together the inquiry Persona ran and the tokens Persona issued.
- Account is where verified identity data ends up. When an authentication uses verified claims, the ground-truth values you send land on the account tied to the authentication, not on the inquiry itself.
What happens during a sign-in
- A user attempts to sign in to your application.
- Your IdP redirects them to Persona’s
/authorizeendpoint (optionally after a pushed authorization request to the IdP’s backend). - Persona finds or creates the account tied to the sign-in attempt, then runs the user through the inquiry bound to the authentication template.
- Once the inquiry completes, Persona redirects back to your IdP with an authorization code.
- Your IdP exchanges the code for tokens and lets the user into your application.
Debugging a failed authentication
When an authentication fails, the error redirect includes a link back to that authentication in the Persona Dashboard, and the error message carries the authentication, inquiry, and account tokens. To get the same data programmatically instead of reading it off a redirect, subscribe to the authentication.failed webhook event.
Where to go from here
- How to configure Persona Authentications with OpenID Connect walks through setting up an authentication template end to end.
- Using Pushed Authorization Requests (PAR) for Persona Authentications covers sending identity data to Persona over a backend call instead of the browser.
- Using Verified Claims for Persona Authentications covers asking Persona to verify claims you already believe are true, including Okta’s custom IDV integration.
- Deferring account creation for Persona Authentications covers starting an authentication before Persona can identify which account it belongs to.