Skip to main content
Docs

Clerk as an Identity Provider: OAuth 2.0 & OpenID Connect

Warning

This feature is not designed for handling authentication directly in your application. To handle authentication in your application, you can configure one of the many social providers that Clerk offers, such as Google.

Clerk can be configured as an OAuth 2.0 and OpenID Connect (OIDC) provider to facilitate Single Sign-On (SSO) with other clients that support the protocols. This feature allows users to authenticate to other applications using their Clerk credentials, enabling user information sharing between your Clerk application and OAuth clients.

When should you use Clerk as an Identity Provider?

You can use Clerk as an Identity Provider (IdP) if you want your users to authenticate to a third party site or a tool using their credentials from your application. This is not the same as supporting an OAuth provider, such as Google, in your application. If you want your users to be able to sign in to your application with an OAuth provider, see the dedicated guide.

How it works

Clerk is the OAuth 2.0 and OIDC provider for your application. The "client" is the third party site or tool that you want your users to authenticate to.

In order to make your Clerk instance operate as a provider, create an OAuth application in the Clerk Dashboard. Then, configure the client to work with your Clerk instance, using the necessary data from your Clerk OAuth application.

Create a Clerk OAuth application

To create an OAuth application,

  1. In the Clerk Dashboard, navigate to the OAuth Applications page.
  2. Select the Add OAuth application button. A modal will open.
  3. Complete the following fields:
    • Name - Helps you identify your application.
    • Scopes - The scopes that you would like to leverage.
  4. Select Create. You'll be redirected to your app's settings page.
  5. In the Redirect URI field, add the redirect URI that the client provides. This is the URL that Clerk will redirect to after the user has authenticated.

Warning

For security reasons, Clerk does not store your Client Secret and cannot show it to you again, so we recommend you download the secret and store it someplace secure.

Configure your client

Now that you have set up a Clerk OAuth application, you will need to configure any of the following settings needed in your client.

  • Client ID: Public identifier of your Clerk OAuth application.
  • Client Secret: Confidential secret used to authenticate your Clerk OAuth application.
  • Discovery URL: Used by the client to retrieve the configuration data of the Clerk OAuth application.
  • Authorize URL: Used by the client to request authorization from your user.
  • Token URL: Used by the client to exchange an authorization code for an access token and a refresh token.
  • User Info URL: Used by the client to retrieve additional user data upon authentication.

Scopes

Scopes define the level of access and specific user data that will be shared with the client application during authentication. The following scopes are currently supported:

ScopeAccess
profileGrant access to the user's personal information, such as first and last name, avatar, and username
emailGrant access to the user's email address
public_metadataGrant access to the user's public and unsafe metadata
private_metadataGrant access to the user's private metadata
openidEnables the OpenID Connect flow

OAuth 2.0

Get additional user information

After a user has successfully completed an OAuth 2.0 flow, you can retrieve additional user information from Clerk's /oauth/userinfo endpoint. When making the request to this endpoint, you must include the Clerk access token in the Authorization header.

The /oauth/userinfo endpoint provides the following user properties, depending on the granted scopes:

PropertyDescription
user_idThe ID of the user
subThe ID of the user
given_nameThe user's first name
family_nameThe user's last name
nameThe user's full name
pictureThe user's avatar URL
preferred_usernameThe user's username
emailThe user's primary email address
email_verifiedWhether the user's primary email address is verified
public_metadataThe user's public metadata
private_metadataThe user's private metadata
unsafe_metadataThe user's unsafe metadata

Get token information

For validating access tokens or refresh tokens and retrieving additional token metadata, Clerk provides a standard OAuth 2.0 Token Introspection Endpoint at /oauth/token_info.

The endpoint returns detailed token information such as if the token is still active, the client ID, and the granted scopes.

Warning

This endpoint is protected. You must provide your Clerk Client ID and Client Secret credentials to authenticate.

Grant types

Clerk's OAuth 2.0 IdP implementation supports the following authorization flows and grant types:

OpenID Connect (OIDC)

After a user successfully authenticates using the OIDC flow, they receive an ID token along with other tokens.

The ID token is a JWT (JSON Web Token) that contains standard JWT claims as defined in RFC 7519, as well as additional custom claims that represent the authenticated user's profile information. The token is signed using your instance's private key.

You must validate the ID token before using any of the user information it contains. Validation requires verifying the token signature using your instance's public key. You can find your instance's public key at https://clerk.<INSERT_YOUR_APP_DOMAIN>.com/.well-known/jwks.json.

The ID token includes the following standard claims:

Standard claimDescription
issThe issuer of the token, which matches your Clerk Frontend API URL
subThe subject of the token, which matches the authenticated user ID
audThe intended audience of the token, which matches the used Client ID
expThe expiration time of the token
iatThe time at which the token was issued
jtiA unique identifier for the token

Depending on the granted scopes, the ID token can include the following additional claims:

Additional claimDescription
nonceThe nonce provided and used during the request
family_nameThe user's last name
given_nameThe user's first name
nameThe user's full name
pictureThe user's avatar URL
preferred_usernameThe user's username
emailThe user's primary email address
email_verifiedWhether the user's primary email address is verified
public_metadataThe user's public metadata
private_metadataThe user's private metadata
unsafe_metadataThe user's unsafe metadata

OIDC prompt

As part of an OIDC request, you can indicate the desired sign-in experience for the user by using the prompt parameter. The following values are supported:

  • none: The user doesn't interact with the provider, thus they need to have an active session already. If not, the provider responds with an error.
  • login: The user is forced to re-authenticate, even if they already have an active session. If there was already an active session, the provider ends it.

Frequently asked questions (FAQ)

When do the tokens expire?

Authorization codes expire after 10 minutes. Access tokens expire after 2 hours. Refresh tokens expire after 3 days. ID tokens expire after 1 hour.

Feedback

What did you think of this content?

Last updated on