OAuth and OIDC overview

OAuth (Open Authorization)⁠ is a widely adopted standard designed by the IETF⁠ to provide a secure way for users to grant third-party applications limited access to their data and resources without providing their login credentials directly.

This guide explains the fundamentals of OAuth using practical examples and outlines its different use cases, helping developers navigate the complexities of implementing OAuth in modern apps.

What is OAuth?

OAuth enables users to grant applications access to their resources without sharing their username and password directly. This ensures secure, limited, and auditable access.

For example, consider a brand manager who wants to schedule marketing content to be published across various social platforms, such as LinkedIn, Twitter or Facebook. Many content management tools exist to help with this but they would need permission to post on the manager's behalf.

Rather than asking for a username and password for each social media platform, which could compromise account security, OAuth allows the chosen content management tool to request limited permissions (such as posting content) while restricting sensitive actions like deleting the account or changing the password.

Key terminology

Before diving deeper, it’s essential to understand some common terminology around OAuth:

• Client: The application requesting access to a user’s data/ resources. For example, in the earlier scenario, the content management tool acts as the client, since it needs permission to make posts from Twitter, Facebook, LinkedIn, etc.
• Authorization service: The service responsible for authenticating the user and granting third-party apps access to a user’s account, based on user consent. For instance, Facebook's auth service manages this process for apps wanting to access Facebook resources. This is also known as an authorization server or Identity Provider (IdP).
• Resource service: The service that holds the data or resources the client wants to access. Following the same example, Facebook's API would be the resource service. This is sometimes referred to as a resource server or Service Provider (SP).
• OAuth access token: A randomly generated string or JSON Web Token (JWT) that is given to the client by the authorization service if the OAuth process is completed successfully. The client can then send this token to the resource service to be allowed to access the relevant resources and data.
• Scopes: Permissions that define which specific actions or data a client can access on the resource service on behalf of the user. For example, a scope might allow readings emails but not sending them. Scopes are requested by the client during the OAuth flow and are displayed to the user, usually via a consent screen.

OAuth flow overview

Here is what a typical OAuth flow, known as the Authorization Code Flow⁠, looks like:

1. The user selects a "Connect" or "Sign in with" option in your app.
2. They’re redirected to the OAuth provider’s authorization page.
3. After they approve the request, the provider redirects them back to your app with a short-lived authorization code.
4. Your server exchanges this code (along with the client_id and client_secret) for an access token.
5. Your app can now use this access token to make authorized requests on behalf of the user.

OAuth use cases

OAuth extends beyond the single use case described above. The diagram above illustrates only one scenario: granting third-party apps scoped access to a user’s data – but OAuth can also be used in many other scenarios, such as:

1. OAuth Scoped Access: granting a third-party app limited access to a user’s data through Clerk's API, given the user's consent. This is the use case described in the diagram above. If you'd like to implement this flow, see the Use OAuth for scoped access guide.
2. OAuth Single Sign-On (SSO): allowing users to sign up/sign in to an app using a third-party provider (e.g. “Sign in with Google"). If you’d like to implement this flow, see the Use OAuth for SSO guide.
3. OAuth User Management: using OAuth as a full user registration and sign-in/out mechanism (a full authorization service built with OAuth). Please note this is not currently supported by Clerk, as Clerk uses a different architecture for user management. If you'd like to learn how to get started with user management using Clerk, check out this quickstart guide.

OpenID Connect (OIDC)

OpenID Connect (OIDC)⁠ is an extension to OAuth written and maintained by a different standards committee, the OpenID Foundation⁠. Built on top of OAuth 2.0 and often used with it, OIDC provides a simple, reliable process for a client to verify the authenticating user's identity and retrieve basic user details as part of the OAuth flow.

The key addition that OIDC makes to OAuth is that, when returning the access and refresh tokens, as long as an openid scope is included, the authorization server should also return an additional property called id_token. This ID token is a JSON Web Token (JWT) containing basic user information such as name, email, and profile photo, helping the client identify the user who just went through the flow. Without OIDC, the client would need to use the access token to make another request to a separate API endpoint to retrieve user details. With OIDC, this extra step can be skipped since the user information is already included in the initial OAuth response.

For more details on how Clerk supports OAuth & OIDC, including features and configuration options, refer to the OAuth reference documentation.