An accessible, in-depth introduction to OpenID Connect for developers.
OpenID Connect (OIDC) is a widely adopted standard for securely handling user authentication and obtaining identity information. This guide is designed to provide developers with a clear and practical introduction to OIDC.
Whether you’re new to the protocol or looking to refine your understanding, you’ll find explanations of key concepts, examples of common use cases, and details on how OIDC builds on OAuth 2.0 to enable secure, seamless user authentication for modern applications.
OpenID Connect (OIDC) allows applications and services to securely acquire tokens from a central authorization server, enabling access to protected resources.
Think of it like checking into a hotel: you authenticate at the front desk and receive a key (the access token) to access a specific room during your stay.
OpenID Connect (OIDC) is an identity layer on top of the OAuth 2.0 protocol. It enables applications to verify users’ identities and securely obtain basic profile information.
The OpenID Connect specification defines OIDC as follows:
OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It enables Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.
In the context of OpenID Connect, OAuth version 2.x can be thought of as the “underlying plumbing” that provides the framework for secure, delegated access to resources. OAuth handles the mechanics of authorization; it allows applications to request permissions on behalf of a user without directly handling their passwords.
However, OAuth 2 alone doesn’t verify a user’s identity. It simply grants access tokens that represent permissions—not who the user is. OpenID Connect builds on OAuth 2.x and adds identity verification alongside authorization to provide users with secure authentication features.
Resources:
OpenID Connect (OIDC) extends OAuth 2.0 by adding an identity layer, enabling applications to authorize access and authenticate users securely.
Key additions include:
These features make OIDC a convenient, effective, and simple solution for identity verification in modern applications.
OAuth has evolved over time through several versions, with each version improving on the last to address new security and usability needs:
In OAuth 2.0, authorization grants define how an application requests tokens from the authorization server. Each grant outlines the credentials or interactions needed to obtain the token required for user access.
Common OAuth 2.0 Authorization Grants include:
The following image summarizes these grants:
OAuth 2.0 primarily defines authorization grants, which specify the methods for obtaining access tokens. OpenID Connect is built on top of OAuth 2.0 and adds a structured approach to authentication flows. These provide clear guidelines for verifying user identities across various application types, including single-page and server-side apps.
These flows aim for a client application or service to authenticate with the authorization server and receive tokens, such as an access token. These can then be used to allow secure access to protected resources.
The most common OAuth 2.0 and OpenID Connect flows are:
Many other flows exist, but the flows above are the most widely used in OAuth 2.0 and OpenID Connect implementations.
The Client Credentials Flow is used for service-to-service communication, where an application (the client) needs to access resources or APIs on behalf of itself rather than a user. In this flow, the client application authenticates directly with the authorization server using its client ID and secret to obtain an access token. This token then grants the client permission to call APIs and perform tasks like retrieving data or managing resources without user involvement.
How the Client Credentials Flow works:
This flow is typically used by background processes, automated jobs, or applications that must interact securely with other services. It does not involve user involvement.
The Device Code Flow (OAuth 2.0 Device Authorization Grant) is designed for devices with limited input capabilities, like smart TVs or IoT devices. Since these devices can’t easily handle user logins, the flow allows users to authorize the device on a separate device, like a smartphone or computer.
Here’s how the Device Code Flow works:
This approach makes it user-friendly for constrained environments while keeping the authentication secure.
The Authorization Code Flow is a highly secure OAuth 2.0 and OpenID Connect flow designed for applications that can protect client secrets, such as server-side web apps. It is now the recommended alternative to the Implicit Flow, which is deprecated due to security vulnerabilities, especially token exposure in browsers.
How the Authorization Code Flow works:
The Authorization Code Flow mitigates many of the security risks associated with front-end token handling by keeping tokens secure on the backend.
The Implicit Flow is designed primarily for client-side applications, such as single-page applications (SPAs) that run in a browser. Unlike the Authorization Code Flow, where tokens are retrieved through a secure server-to-server exchange, the Implicit Flow delivers tokens—both ID and access tokens—directly to the client application via the browser.
This approach removes the need for a backend server in the authentication process, which makes it simpler and faster. However, it is also less secure, as the tokens are exposed in the URL and, therefore, susceptible to interception.
Another use case involves authenticating a user in the frontend and passing tokens to a backend via the browser for further processing or resource access. While rare, this approach is covered by the Auth 2.0 Form Post Response Mode specification, which allows tokens to be delivered more securely in an HTTP POST body rather than in the URL.
The Implicit Flow was developed in an era when:
These constraints led to the creation of the Implicit Flow as a simpler, client-side solution for retrieving tokens. However, with the advancement of web standards like CORS and the rise of SPAs and mobile apps, the Authorization Code Flow with PKCE is now the preferred method for secure client-side authentication.
The Hybrid Flow is unique to OpenID Connect, combining features of both the Authorization Code Flow and the Implicit Flow. This gives more flexibility by allowing applications to obtain ID tokens immediately while securely exchanging an authorization code for access tokens.
How the Hybrid Flow Works:
This flow benefits applications needing immediate user information and enhanced security for subsequent API requests.
The Resource Owner Password Credentials (ROPC) Flow is an OAuth 2.0 method in which users provide their username and password directly to the application, which then uses these credentials to obtain tokens from the authorization server. While this flow can be useful for trusted applications, it has many more security risks since it exposes user credentials to the client.
Deprecation Note: Due to these vulnerabilities and the availability of more secure flows, ROPC is now considered deprecated and is generally discouraged in favor of safer options like the Authorization Code Flow with PKCE.
Proof Key for Code Exchange (PKCE) is a security enhancement for the Authorization Code Flow. PKCE was initially designed for mobile and public clients who can’t securely store a client’s secret. PKCE helps protect against interception attacks, such as the authorization code interception attack.
How PKCE works:
This mechanism ensures that an attacker can’t use an authorization code without the code verifier even if the authorization code is intercepted.
Pushed Authorization Requests (PAR) enhance OAuth and OpenID Connect flows by securely transmitting authorization parameters through a back channel instead of browser URLs.
Traditionally, sensitive data like client credentials and scopes are exposed in URLs, significantly increasing security risks. PAR addresses this by allowing these parameters to be sent via a direct HTTP request from the client to the authorization server, making them less susceptible to tampering and interception.
PAR greatly improves security, ensures tamper resistance, and prevents issues caused by excessively long URLs in complex authorization scenarios.
For more details about PAR, head over to my Pushed Authorization Requests (PAR) in ASP.NET Core 9 blog post, which covers this topic in more depth.
Scopes in OpenID Connect serve a dual purpose: they request information about a user and define access to specific resources. This dual role is sometimes misunderstood, as scopes relate to gathering user details and specifying permissions for an application to act on the user’s behalf.
For example:
Using scopes, applications can limit their data requests to what is necessary, promoting security and privacy. Just as we try to show in the following image:
The OpenID Connect scopes are defined in the OpenID Connect Core 1.0 specification. The document outlines standard scopes such as openid, profile, email, address, and phone, which dictate the user information a client can request from an identity provider.
Claims are key-value pairs that convey information about the user or the authentication event. Technically, claims are just strings that can hold any name and value. Each claim has:
For instance:
These claims help applications personalize and manage access securely, while custom claims can also be defined to fit specific application needs.
If you’re encountering issues with claims in your application, check out these posts for practical debugging tips:
Claim resources
With OpenID Connect, we deal with three types of tokens:
Let’s explore these tokens and what they represent.
A common myth about the ID token is that it represents the user’s identity, but this is not entirely true.
The ID token confirms the user’s identity but also includes important details about the authentication process. For example, the token not only identifies the user but also claims to show when and how the user authenticated.
What the ID Token Represents:
To keep the ID token compact, identity claims like the user’s name, email, or profile information may not always be fully included. Instead, OpenID Connect provides a way to fetch additional user information using the UserInfo endpoint.
Here is a sample ID-Token with a header and payload:
Header:
{
"alg": "RS256",
"kid": "585070ED8E048DC512D28B7BA794A23C",
"typ": "JWT"
}
Payload:
{
"iss": "https://identityservice.com",
"nbf": 1731175206,
"iat": 1731175206,
"exp": 1731175506,
"aud": "localtestme-addoidc-client",
"amr": [
"pwd"
],
"nonce": "638667720018252814.YjdmYTdhOTgtND...",
"at_hash": "awuoS2auAy_XxhsNNSPg8Q",
"sid": "B26D5BCAF60E97F157BBD7C5A005F2EF",
"sub": "2",
"auth_time": 1731175205,
"idp": "local",
"name": "Bob Smith",
"given_name": "Bob",
"family_name": "Smith",
"email": "BobSmith@email.com",
"email_verified": true,
"website": "http://bob.com"
}
An access token is like a hotel key; just as a hotel key gives you access to specific rooms and areas within the hotel, an access token grants an application access to specific resources on behalf of a user.
What it is:
What it does:
Key elements of an Access Token:
Sample access token:
Header:
{
"alg": "RS256",
"kid": "585070ED8E048DC512D28B7BA794A23C",
"typ": "at+jwt"
}
Payload:
{
"iss": "https://identityservice.com",
"nbf": 1731175206,
"iat": 1731175206,
"exp": 1731175221,
"scope": [
"openid",
"profile",
"email",
"offline_access"
],
"amr": [
"pwd"
],
"client_id": "localtest",
"sub": "2",
"auth_time": 1731175205,
"idp": "local",
"sid": "B26D5BCAF60E97F157BBD7C5A005F2EF",
"jti": "65797782F504C3E1E5A0039D8038076F"
}
console.log( 'Code is Poetry' );
A refresh token is like the keycard you keep after your hotel room key expires. Imagine staying in a hotel where your room key only works 24 hours. Instead of going through the entire check-in process daily, you use your keycard at the front desk to get a new room key. Similarly, a refresh token is used to get a new access token when the old one expires.
What It Is:
What It Does:
Security Considerations:
Sample refresh token:
FFC28AEE658D1D0EA63C3FFA267BBF5FA70B953842AB62BBAA35A5749E68627-1
A refresh token typically looks like a long, random string of characters designed to be unique and impossible to guess. It may be an opaque string or, in some cases, a structured token like a JSON Web Token (JWT). However, it usually doesn’t contain readable information and is primarily used securely between the client and the authorization server.
With many authorization services supporting OpenID Connect, choosing the right one can be challenging. A certified implementation is highly recommended, as certified servers will have passed the OpenID Foundation’s compatibility tests, ensuring they meet the OIDC standard.
Popular OpenID Connect implementations include:
Let me know if you want to contribute an entry to this FAQ.
A common confusion is about the difference between authentication and authorization:
The important thing to remember is that you always do authentication first and then authorization. You can’t decide if the request is allowed or not if you don’t know the caller’s identity first.
FAPI stands for Financial-grade API, a set of security standards developed by the OpenID Foundation for protecting highly sensitive financial data in APIs. FAPI is designed to enhance security and privacy in the financial sector, such as in open banking systems, by ensuring that API requests and responses are secure and tamper-proof.
FAPI includes specifications like:
FAPI is crucial in environments where protecting user data is a legal or regulatory requirement, and it is being widely adopted in industries like banking and financial services
Read more at the FAPI Working Group website.
Relying Parties (RPs), or clients, are applications or systems that use OpenID Connect or OAuth to authenticate users and access their data. The RP depends on an identity provider (IdP) to handle user authentication and issue tokens, which the RP then uses to authorize and personalize the user’s experience.
Relying Parties can be any type of client, such as a web app, mobile app, or a service that interacts with APIs. While the RP itself does not act as an API, it may use APIs provided by identity providers to manage authentication and authorization flows.
In simpler terms, the RP is always the client application in the OAuth or OpenID Connect ecosystem that seeks to authenticate users and access protected resources.
In OAuth and OpenID Connect, the resource owner is typically the user who owns the data that an application (or client) wants to access. The resource owner has control over the data and must give explicit permission for a client to access it.
For example, you are the resource owner if you’re using an app that wants to access your email contacts through Google. You decide whether or not to grant the app permission to access your information. In most scenarios, the resource owner is a human user, but it could also be a service or application in specific automated environments.
A Resource Server is the server that hosts the protected resources an application wants to access using OAuth 2.0 or OpenID Connect. It receives and processes requests containing access tokens issued by the authorization server and determines whether the request is valid and authorized. This server is typically an API or a database that accepts access tokens for authentication to control and manage access to its data
Although the names are similar, OpenID and OpenID Connect are different protocols, both managed by the OpenID Foundation.
Security Assertion Markup Language (SAML) and OpenID Connect (OIDC) are both protocols for federated identity, but they serve different environments and use cases.
SAML is an older protocol designed for secure, single sign-on (SSO) primarily in enterprise environments and on-premise solutions. It uses XML for data exchange, which can make it more complex to implement and troubleshoot compared to OpenID Connect’s JSON-based structure. Despite its age, SAML is still widely used in enterprises due to legacy compatibility and strong support within existing infrastructure.
For new projects, migrating to OpenID Connect is often recommended because of its streamlined integration, mobile support, and ease of use.
In OAuth and OpenID Connect, a grant refers to a specific way an application requests a token (like the Authorization Code Grant). At the same time, a flow describes the entire process and steps involved in obtaining those tokens. Essentially, a grant is the type of permission, and the flow is how it’s carried out.
The subject (sub) claim is the unique, unchanging identifier for a user within a specific identity provider. It can be a GUID, user ID, email, or random string as long as it remains stable. This consistency is vital, especially in federated authentication scenarios (like social logins with Google, Facebook, or GitHub), where each provider has its own sub format. Because of this, sub values can vary widely, and there’s potential for collisions across providers.
Many different factors, such as whether you’re implementing OIDC for the first time, the flows and amount of customizability desired, security needs, and ensuring smooth integration with your technology stack, can all influence the ideal choice for your OIDC authorization server service.
OIDC may not work with legacy systems, and if you’re looking to implement it for the first time, your service provider must have simple but detailed documentation that you can access. Consider whether the authorization service can meet any particular cyber security or compliance standards like FAPI, and finally, take care to right-size it to the complexity, costs, and customization requirements that you have and will likely need in the future.
If you want to learn all of this in a more structured way, then I provide several workshops, both in-person and online, some of the related workshops are:
These workshop provides the foundational knowledge you need about OIDC and security in general. Thee covers how they work together to secure web applications and APIs, key concepts, practical uses, and how to implement these standards effectively for secure user authentication and access control. More workshops and talks can be found on my training page.
I offer tailored mentoring and coaching services in areas like OpenID Connect, OAuth, and web security. Whether you need individual guidance or team training, I can help you deepen your knowledge and tackle technical challenges.
Reach out to discuss how I can support your learning or project needs!
I frequently write blog posts about authentication, security, and OpenID Connect on my blog, and some of the popular posts are:
Have a challenge on your hands? Looking to upskill your team? I’m here to help! If you like, let’s have an informal, no-obligation chat. I can help you with: