Docs

Use Clerk as an OAuth 2 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 identity provider to facilitate Single Sign-On (SSO) with other clients that support the OAuth 2.0 protocol. This feature allows users to sign in to other applications using their Clerk credentials, enabling user information sharing between your Clerk application and external websites.

When should you use Clerk as an OAuth provider?

You can use Clerk as an OAuth provider if you want your users to sign in 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

The following diagram shows the flow for using Clerk as an OAuth provider.

Diagram of the Clerk as an IdP flow

Retrieve callback URL from the client application

Retrieve the Callback URL for the client application you want to configure. This is where your users will be redirected to after a successful authentication and is required to successfully create your OAuth application in the next step.

Create an OAuth application in Clerk

Next, you need to create an OAuth Application in Clerk via the Backend API by providing the Callback URL and a Name. Note that in this context the name is used to help you identify your application and is not displayed anywhere publicly.

POST /v1/oauth_applications
curl
 -X POST https://api.clerk.com/v1/oauth_applications \
 -H "Authorization: Bearer <CLERK_SECRET_KEY>"  \
 -H "Content-Type: application/json" \
 -d {"callback_url":"https://oauth-client.com/oauth2/callback", "name": "oauth_app_1", "scopes": "profile email"}

To create an OAuth Application that uses the authorization code flow with proof of key exchange (PKCE), set public to true in the POST request body.

{
  "callback_url": "https://oauth-public-client.com/oauth2/callback",
  "name": "oauth_app_pkce",
  "public": true
}

Clerk creates an OAuth application and returns it's configurations back to you.

RESPONSE
{
  "object": "oauth_application",
  "id": "oa_2O4BCh3zUONvWlZHtBXv6s6tm7u",
  "instance_id": "ins_2O4Ak02T4fDmKKv6tK5h0WJ8ou8",
  "name": "oauth_app_1",
  "client_id": "d9g4CT4WYiCBm7EU",
  "client_secret": "VVgbT7i6sPo7sTljq2zj12fjmg0jPL5k",
  "scopes": "profile email",
  "callback_url": "https://oauth-client.com/oauth2/callback",
  "authorize_url": "https://clerk.your-domain.com/oauth/authorize",
  "token_fetch_url": "https://clerk.your-domain.com/oauth/token",
  "user_info_url": "https://clerk.your-domain.com/oauth/userinfo",
  "created_at": 1680809847940,
  "updated_at": 1680810135145
}

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 OAuth application in client

Now that you have set up an OAuth application in Clerk, you will need to configure these settings in your Client.

  • Client ID: Public identifier of your OAuth application
  • Client Secret: Confidential secret used to authenticate your OAuth application
  • Authorization URL: Used by the Client to request authorization from your user
  • Token URL: Used by the Client to retrieve access tokens
  • Scopes: OAuth scopes used to grant access to the Client. Clerk supports profile, email, public_metadata, and private_metadata. The metadata scopes ensure that the user info endpoint returns the user's public, private and unsafe metadata.
  • User Info URL: Used by the Client to retrieve the email address and profile (username, first and last name) associated to your user

Below is an example of a response from /oauth/userinfo.

RESPONSE
{
  "object": "oauth_user_info",
  "instance_id": "ins_2O4Ak02T4fDmKKv6tK5h0WJ8ou8",
  "email": "me@oauth-client.com",
  "email_verified": true,
  "family_name": "last_name",
  "given_name": "first_name",
  "name": "first_name last_name",
  "username": "my_username",
  "picture": "https://profile_image_public_url/img.png",
  "user_id": "my_user_id",
  "public_metadata": {},
  "private_metadata": {},
  "unsafe_metadata": {}
}

Frequently asked questions (FAQ)

How can the access tokens obtained from the Token URL be used?

Access tokens retrieved from the Token URL are used in the Authorization header when the OAuth2 client retrieves user information from the /oauth/userinfo endpoint. They are not the same as Clerk's JWT session tokens.

When do the tokens expire?

Access tokens expire after 2 hours, and refresh tokens expire after 3 days.

Is OpenID Connect supported?

At this time, OIDC is not supported.

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on