Use Clerk as an OAuth 2.0 provider
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,
- In the Clerk Dashboard, navigate to the OAuth Applications page.
- Select the Add OAuth application button. A modal will open.
- Complete the following fields:
Name
- Helps you to identify your application.Scopes
- The scopes that you would like to leverage.
- Select the Create button. You'll be redirected to your app's settings page.
- 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.
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:
Scope | Access |
---|---|
profile | Grant access to the user personal information, such as first and last name, avatar and username |
email | Grant access to the user email address |
public_metadata | Grant access to the user public and unsafe metadata |
private_metadata | Grant 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:
Property | Description |
---|---|
user_id | The ID of the user |
given_name | The first name of the user |
family_name | The last name of the user |
name | The full name of the user |
picture | The avatar URL of the user |
preferred_username | The username of the user |
email | The primary email address of the user |
email_verified | Whether the primary email address of the user is verified |
public_metadata | The public metadata of the user |
private_metadata | The private metadata of the user |
unsafe_metadata | The 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.
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
Last updated on