Skip to main content
Docs

Use Clerk as an OAuth 2.0 provider

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 provider to facilitate Single Sign-On (SSO) with other clients that support the OAuth 2.0 protocol. 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 OAuth 2.0 provider?

You can use Clerk as an OAuth 2.0 provider 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 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 an OAuth 2.0 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 to identify your application.
    • Scopes - The scopes that you would like to leverage.
  4. Select the Create button. 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.
  • 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.
  • Discovery URL: Used by the client to retrieve the configuration data of the Clerk OAuth application.

OAuth 2.0 Scopes

OAuth 2.0 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 personal information, such as first and last name, avatar and username
emailGrant access to the user email address
public_metadataGrant access to the user public and unsafe metadata
private_metadataGrant access to the user private metadata

Get 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, based on the granted scopes. 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
given_nameThe first name of the user
family_nameThe last name of the user
nameThe full name of the user
pictureThe avatar URL of the user
preferred_usernameThe username of the user
emailThe primary email address of the user
email_verifiedWhether the primary email address of the user is verified
public_metadataThe public metadata of the user
private_metadataThe private metadata of the user
unsafe_metadataThe unsafe metadata of the user

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.

OAuth 2.0 grant types

Clerk OAuth 2.0 provider supports the following flows and grant types:

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.

Is OpenID Connect (OIDC) supported?

At this time, OIDC is not supported.

Feedback

What did you think of this content?

Last updated on