Clerk as an Identity Provider: OAuth 2.0 & OpenID Connect
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,
- 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 identify your application.Scopes- The scopes that you would like to leverage.
- Select Create. 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.
- 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:
| Scope | Access |
|---|---|
profile | Grant access to the user's personal information, such as first and last name, avatar, and username |
email | Grant access to the user's email address |
public_metadata | Grant access to the user's public and unsafe metadata |
private_metadata | Grant access to the user's private metadata |
openid | Enables 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:
| Property | Description |
|---|---|
user_id | The ID of the user |
sub | The ID of the user |
given_name | The user's first name |
family_name | The user's last name |
name | The user's full name |
picture | The user's avatar URL |
preferred_username | The user's username |
email | The user's primary email address |
email_verified | Whether the user's primary email address is verified |
public_metadata | The user's public metadata |
private_metadata | The user's private metadata |
unsafe_metadata | The 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.
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 claim | Description |
|---|---|
iss | The issuer of the token, which matches your Clerk Frontend API URL |
sub | The subject of the token, which matches the authenticated user ID |
aud | The intended audience of the token, which matches the used Client ID |
exp | The expiration time of the token |
iat | The time at which the token was issued |
jti | A unique identifier for the token |
Depending on the granted scopes, the ID token can include the following additional claims:
| Additional claim | Description |
|---|---|
nonce | The nonce provided and used during the request |
family_name | The user's last name |
given_name | The user's first name |
name | The user's full name |
picture | The user's avatar URL |
preferred_username | The user's username |
email | The user's primary email address |
email_verified | Whether the user's primary email address is verified |
public_metadata | The user's public metadata |
private_metadata | The user's private metadata |
unsafe_metadata | The 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
Last updated on