What is OpenID Connect (OIDC)?

OpenID Connect (OIDC) is one of the most popular authentication protocols used today. It’s easier to implement than other common protocols like SAML and it works well with a wide array of apps.

In this article, we’ll discuss what OIDC is, its benefits, how it works, and how you can use the WorkOS User Management platform to support it in your app.

What is OpenID Connect?

OpenID Connect (OIDC) is an authentication layer built on top of OAuth 2.0, an authorization framework that allows an application to access resources hosted by other apps on behalf of a user.

OIDC is commonly used for Single Sign-On (SSO), which allows users to authenticate once and gain access to multiple apps without re-authenticating. Its purpose is to allow websites and applications to verify the identity of users without needing to manage and store sensitive details like passwords. Instead, apps rely on a trusted third-party identity provider, like Google and Facebook, to confirm if someone is who they claim to be. 

Why use OpenID Connect?

The main advantages of OpenID Connect are:

• Standardization: OIDC is a standardized protocol built on top of OAuth 2.0, which is already widely adopted across the internet. This means that many developers are familiar with its concepts, and extensive resources and community support are available. Plus, standardized endpoints for token requests and user information requests enable consistent integration across different platforms and services.
• Easy to implement: Compared to other SSO protocols like SAML, OIDC is much easier to implement. OIDC uses JSON Web Tokens (JWT) which are easier to read, parse, and encode. Additionally, most programming languages offer well-maintained libraries and SDKs that simplify the authentication and JWT encoding process, making it easy to integrate OIDC with minimal effort.
• Security: Many security flaws are caused not by problems in the standards but by implementation mistakes. This makes OIDC more secure due to its simplicity of implementation. SAML, for example, is a lot harder to implement than OIDC, and thus more prone to implementation errors. Furthermore, authentication frameworks like OpenID Connect increase the security of the whole Internet by putting the responsibility for user identity verification in the hands of expert service providers.
• Broad support and wide adoption: OIDC is designed to work well across different types of clients, including web-based, mobile, and desktop apps. It's also supported by numerous identity providers, from social IdPs like Google to corporate IdPs like Microsoft Entra and Okta. This means that the vast majority of users, both individual users and enterprises, can use their existing accounts to sign into various services.

How does OpenID Connect work?

OpenID Connect extends OAuth 2.0 by adding an ID token, which is a JSON Web Token (JWT) that contains the user's authentication information. The ID token is provided by the OpenID Provider (OP) when the user authenticates.

An OpenID Provider (OP) is a service that authenticates users based on the OIDC standard (e.g., Google or Okta). It allows clients (applications needing to authenticate users) to verify a user's identity based on the authentication it does. Once authenticated, the OpenID Provider securely shares the user's identity with the applications.

The OpenID Connect protocol, in general, follows these steps:

1. The user navigates to a web application and chooses to sign-in using an available OpenID Provider (e.g., sign in with Google).
2. The app sends a request to the OpenID Provider (OP). If the user is not signed in, they are redirected to the OP's website to sign in.
3. The OP authenticates the User and obtains authorization.
4. The OP sends back to the app an ID token and usually an access token.
5. The app can decode the ID token to obtain the user information, or use the access token to call the UserInfo endpoint.

This is the abstract version of the OIDC flow. In practice, OIDC supports different flows for different types of apps. These flows are also called OAuth 2.0 grant types and some of them include:

• Authorization Code flow: Instead of directly returning a token, the server returns a single-use authorization code which can later be exchanged for the required tokens. Before issuing the tokens, the authorization server validates the application (using the provided client ID and client secret) to ensure it is authorized to access the requested resources. It's the preferred method for most server-side applications due to how secure it is.
• PKCE flow: PKCE builds on top of the Authorization Code flow. It ensures that the application that starts the authentication flow is the same one that finishes it and that access to resources is protected at all times. If you are developing a public client, like a mobile or a single-page app, and you use OAuth, you need to use PKCE.
• Implicit flow: This is a legacy flow and shouldn't be used. The tokens are sent directly to your application through the user's browser. Due to its inherent security vulnerabilities, the industry is shifting from implicit flows towards more secure methods like the authorization code flow with PKCE.
• Hybrid flow: Combines elements of both the authorization code and implicit flows. While the ID token is returned directly to the app, the access token is only returned after being exchanged for an authorization code.

What is an ID token?

An ID token consists of three parts:

• Header: Contains metadata about the token such as the token type (typ) and the signing algorithm used (alg).‍
• Payload: Contains the claims about the user. The claims are pieces of information about a subject, for example, the user's name. Common claims include:
  • iss (issuer identifier): The URL of the issuer of the token, for example https://api.workos.com
  • sub (subject identifier): A unique identifier for the user, which must be unique to the issuer.
  • aud (audience): The intended audience for the token, typically the client ID of the application.
  • exp (expiration time): The time at which the token expires.
  • iat (issued at time): The time at which the token was issued.
  • nonce: A string value used to associate a client session with an ID token and mitigate replay attacks.
• Signature: Used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn't changed along the way.

The payload of a decoded ID token looks like this:

	
{
  "iss": "https://api.workos.com",
  "sub": "user_01HBEQKA6K4QJAS93VPE39W1JT",
  "aud": "my_client_id",
  "exp": 1709193857,
  "iat": 1709193857,
  "sid": "session_01HQSXZGF8FHF7A9ZZFCW4387R"
  "name": "John Doe",
  "email": "johndoe@example.com",
  "picture": "http://example.com/johndoe.jpg"
}
  

The app can extract user information from the ID token, like a user's name or profile picture, and use it to personalize a user's experience.

Best practices

• Use secure connections: Always use HTTPS to protect the data transmitted between your users, your application, and the identity provider (IdP). This prevents interception and manipulation of sensitive data, such as tokens and user information.
• Use PKCE: For public clients (e.g., applications running on a user’s device like mobile and single-page applications), use Proof Key for Code Exchange (PKCE) to protect against interception attacks during the Authorization Code flow.
• Validate ID tokens: Properly validate the ID token to ensure it is actually issued by the expected IdP and is intended for your application.
  • Check the issuer (iss): Ensure it matches the IdP’s expected URL.
  • Verify the audience (aud): Confirm it matches your application’s client ID.
  • Examine the expiration (exp): Ensure the token has not expired.
  • Verify the signature: Use the IdP’s public key to verify the token's signature.
• Handle redirect URIs securely: Register redirect URIs precisely with the OIDC provider and avoid using wildcard entries. This prevents attackers from redirecting users to malicious sites after the authentication process.
• Use state parameters to prevent CSRF: Use the state parameter in your authorization request to mitigate CSRF attacks. The state parameter should be a unique and non-guessable value that is verified in the callback to ensure that the response corresponds to the request made by the same user.
• Implement appropriate OAuth scopes: Limit the scope of access when requesting tokens. Only request access to the information and services necessary for your application. This principle of least privilege reduces the impact in case a token is compromised.
• Secure client secrets: Store and handle client secrets securely. Do not expose them in client-side code or anywhere that could be accessible by unauthorized parties. Use environment variables and secure vaults or key management systems to manage secrets.

When should you use OpenID Connect?

You should use OIDC when:

• You want to enable SSO in your SaaS for a wide range of apps such mobile, web, desktop, SPAs, or even APIs.
• You need access to basic user profile information such as their name and email.
• You want to outsource authentication to external identity providers like Google, Facebook, or enterprise providers like Okta.

You shouldn't use OIDC when:

• You only need access to APIs. Use regular OAuth 2.0 for this.
• Your customer's IdPs use a protocol other than OIDC, such as SAML (Security Assertion Markup Language) or WS-Federation.

Can you use OpenID Connect without OAuth 2.0?

OpenID Connect (OIDC) cannot be used without OAuth 2.0 because OIDC is designed as an identity layer on top of the OAuth 2.0 authorization framework. Therefore, OIDC cannot function independently of OAuth 2.0. 

However, you can use OAuth 2.0 without OIDC if your needs are limited to authorization without identity verification.

OpenID Connect vs SAML

OpenID Connect and SAML accomplish the same thing (SSO) but they do it in different ways.

OIDC uses RESTful HTTP endpoints and lightweight JWTs, which makes it the go-to choice for web and mobile apps. SAML is XML-based and is typically used for enterprise SSO.

OIDC is easier to implement and less prone to implementation errors that can lead to vulnerabilities. SAML, however, has a longer track record since SAML 2.0 has been around since 2005.

Choosing between OIDC and SAML depends largely on your needs:

• Use OIDC if you need to implement SSO in a contemporary environment that includes many web and mobile applications.‍
• Use SAML for legacy enterprise SSO.

You can also use a hybrid approach. An application can initiate an OAuth/OIDC flow using a SAML assertion. The SAML assertion, which confirms a user's identity, is exchanged for an access token. This access token then allows the application to request access to protected resources on behalf of the user.

For more information on this topic, see OIDC vs SAML and SAML vs OAuth.

Implement OpenID Connect with WorkOS

The easiest way to implement OpenID Connect authentication is with AuthKit, the customizable UI hosted by WorkOS. Configure the OIDC provider in your WorkOS dashboard, and AuthKit will handle the authentication flow, all the redirects, and the authentication error messages.

If the OIDC provider is not listed in the WorkOS dashboard, set up a generic OIDC connection.

Alternatively, if you’d rather build and manage your own authentication UI, use the User Management Authentication API.

Sign up for WorkOS and start building today.