āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š shadcn/directory/clerk/clerk-docs/guides/configure/auth-strategies/oauth/single-sign-on ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
Clerk supports two primary Single Sign-On (SSO) options using OAuth:
These features help you streamline authentication for your users, whether they're signing into your Clerk-powered app or accessing external apps with their Clerk credentials. This guide covers both options in detail and provides links to additional resources where applicable.
This feature allows users to sign up/sign in to your Clerk app using their existing credentials from popular social providers, also known as IdPs, like Google, Facebook, or GitHub. For example, if you enable GitHub as a social provider, then a user can sign in to your Clerk app by selecting GitHub as an option and authenticating with their GitHub account credentials.
Refer to the appropriate provider's guide for implementation details.
Clerk can be configured as an OAuth 2.0 and OpenID Connect (OIDC) IdP to enable Single Sign-On (SSO) with other clients that support these protocols. This feature allows users to authenticate to other applications using their Clerk credentials, enabling user information sharing between your Clerk app and OAuth clients.
For example, if your user wants to sign in to a third-party app, they can select Clerk as the IdP and use their Clerk credentials to sign in. It's similar to the first option, but in reverse: instead of using an external app to authenticate into your Clerk app, users use their Clerk credentials to sign in to an external app.
In this case, Clerk is the IdP for your application. The client is the third party site or tool that you want your users to authenticate to.
Here is the general flow to set up your Clerk instance as an OAuth provider:
Ensure you have setup a new connection within the third-party client or tool where your users will authenticate. As part of this process, you'll be provided a redirect URL that you'll need to use in the next step.
To create a Clerk OAuth application:
Name - Helps you identify your application.Scopes - The scopes that you would like to leverage. Learn more about the scopes currently supported by Clerk.To learn more about the other OAuth application configuration settings, like Dynamic client registration, see the dedicated guide.
Once you have set up a Clerk OAuth app, you'll need to configure a few settings in your client to establish the connection. All the necessary information can be found in your Clerk OAuth app's settings, starting with two key parameters:
Both of these are available in your Clerk OAuth app's settings in the Clerk Dashboard. They need to be entered into your client's setup interface to complete the integration. Once completed, your users will be able to authenticate into your app using their Clerk credentials.
Other available settings that may be useful include:
After a user has successfully completed an OAuth 2.0 flow, you can retrieve additional user information from Clerk's /oauth/userinfo{{ target: '_blank' }} endpoint. When making the request to this endpoint, you must include the OAuth access token in the Authorization header.
This example is written for Next.js App Router but can be adapted for any framework/language. It assumes the OAuth flow has already been completed and that you have obtained an access token from Clerk.
import { NextResponse } from 'next/server'
export async function GET() {
// Assume you already have the access token available here
const accessToken = 'YOUR_ACCESS_TOKEN_HERE'
try {
// Your Frontend API URL can be found on the API keys page in the Clerk Dashboard
// https://dashboard.clerk.com/~/api-keys
const response = await fetch(`${process.env.CLERK_FRONTEND_API_URL}/oauth/userinfo`, {
headers: {
// Include the access token as a Bearer token in the Authorization header
Authorization: `Bearer ${accessToken}`,
},
})
if (!response.ok) {
const errorData = await response.json()
return NextResponse.json(errorData, { status: response.status })
}
const data = await response.json()
return NextResponse.json(data)
} catch (error: unknown) {
return NextResponse.json(
{ error: 'Failed to fetch user info', details: (error as Error).message },
{ status: 500 },
)
}
}
Example response
{
"object": "string",
"instance_id": "string",
"user_id": "string",
"sub": "string",
"email": "string",
"email_verified": true,
"family_name": "string",
"given_name": "string",
"name": "string",
"username": "string",
"preferred_username": "string",
"picture": "string",
"public_metadata": {},
"private_metadata": {},
"unsafe_metadata": {}
}
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 |
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{{ target: '_blank' }}.
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.
This example is written for Next.js App Router but can be adapted for any framework/language. It demonstrates how to call the /oauth/token_info endpoint, assuming you already have the access token and refresh token available.
import { NextRequest, NextResponse } from 'next/server'
// Assume you already have the access token and refresh token available here
const tokens = {
accessToken: 'YOUR_ACCESS_TOKEN_HERE',
refreshToken: 'YOUR_REFRESH_TOKEN_HERE',
}
export async function POST(req: NextRequest) {
try {
// Your Frontend API URL can be found on the API keys page in the Clerk Dashboard
// https://dashboard.clerk.com/~/api-keys
const response = await fetch(`${process.env.CLERK_FRONTEND_API_URL}/oauth/token_info`, {
method: 'POST',
headers: {
// Include the access token as a Bearer token in the Authorization header
Authorization: `Bearer ${tokens.accessToken}`,
'Content-Type': 'application/x-www-form-urlencoded',
},
body: new URLSearchParams({
// Include the refresh token in the body
token: tokens.refreshToken,
}),
})
if (!response.ok) {
return NextResponse.json({ error: 'Failed to fetch token info' }, { status: response.status })
}
const data = await response.json()
return NextResponse.json(data)
} catch (error) {
return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
}
}
Example response
{
"active": true,
"client_id": "string",
"iat": 0,
"scope": "string",
"sub": "string"
}
[!IMPORTANT] Not all third-party apps expect or use OIDC. However, this feature was designed with OIDC compatibility in mind, which is why it's included in this guide. Ensure that your integration target supports OIDC before proceeding.
In order to enable OIDC in your OAuth flow, you can follow the same steps outlined above, but ensure to select the openid scope when configuring your OAuth app in the Clerk Dashboard. This scope triggers OIDC and instructs the authorization server to issue an ID token alongside your access token.
You'll also need to include this openid scope in the query parameters of your authorization endpoint when initiating the OAuth flow. For example:
GET /oauth/authorize?
client_id=x&
response_type=code&
state=y&
code_challenge=z&
redirect_uri=a&
scope=openid%20profile%20email&...
Host: clerk.<INSERT_YOUR_APP_DOMAIN>.com
Once a user successfully authenticates using the OIDC flow, you'll receive:
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 verify the signature on the ID token before using any of the user information it contains. This will require your instance's public key. You can find your instance's public key by loading your Frontend API URL with /.well-known/jwks.json appended to it. For example:
https://verb-noun-00.clerk.accounts.dev/.well-known/jwks.json for a development environment.https://clerk.<INSERT_YOUR_APP_DOMAIN>.com/.well-known/jwks.json for a production environment.Your Frontend API URL can be found on the API keys page in the Clerk Dashboard.
Here is an example verifying the ID token using the jsonwebtoken library in a production environment:
const jwt = require('jsonwebtoken')
function verifyIdToken(idToken) {
jwt.verify(
idToken,
PUBLIC_KEY,
{
algorithms: ['RS256'],
issuer: 'https://clerk.<YOUR_APP_DOMAIN>.com',
audience: '<YOUR_CLIENT_ID>',
},
(err, decoded) => {
if (err) {
console.error('Token verification failed:', err)
} else {
console.log('Token is valid:', decoded)
}
},
)
}
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 |
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā