āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š shadcn/directory/clerk/clerk-docs/guides/configure/auth-strategies/oauth/scoped-access ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
Clerk's OAuth implementation supports OAuth scoped access, which lets third-party applications request limited access to specific parts of a user's data through Clerk's API. This enables applications to interact with user data in a secure and controlled manner, based on the user's explicit consent. The most common implementation of OAuth scoped access is the "Authorization Code Flow", which is the flow covered in this guide.
Before diving into implementations details, it's important to understand the different actors involved in this flow:
[!NOTE] If you would like to know more about the terminology around OAuth, check out the OAuth terminology guide.
This guide provides step-by-step instructions on how to build OAuth scoped access into a Clerk app.
<Steps> ### Create a Clerk OAuth applicationTo 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.http://localhost:3000/oauth_callback as an example.To learn more about the other OAuth application configuration settings, like Dynamic client registration, see the dedicated guide.
If you are aiming to integrate your Clerk app with a third-party app that acts as an OAuth client, you can reference their documentation on how to integrate OAuth connections in order to test your OAuth flow. It will likely be necessary to provide the client_id and client_secret from the OAuth app created above.
If you don't have a specific, existing OAuth client in mind, you can use the following OAuth test client project. It contains a minimal Express.js server that can run through an OAuth flow. Let's walk through how to use this test client below.
[!NOTE] This implementation follows the OAuth specification, and is not specific to Clerk or this test project. Any compliant OAuth client will behave the same way.
cp .env.sample .env
.env file, add the required credentials:
CLERK_PUBLISHABLE_KEY: Your Clerk Publishable Key from the API keys page in the Clerk Dashboard.CLIENT_ID: The client ID of your OAuth app from the Clerk Dashboard.CLIENT_SECRET: The client secret of your OAuth app from the Clerk Dashboard.npm i
npm start
Once this is complete, you'll be able to see the OAuth flow begin. If you are not currently signed in, you'll first be presented with a sign in screen. After signing in, Clerk will redirect to an OAuth consent screen, showing the requested scopes and asking for your consent.
[!NOTE] The consent screen uses the scopes passed in the authorization request to inform the user exactly what they're granting access to, and to whom.
By default, the consent screen is shown for all newly created OAuth apps, but this can be disabled in each app's settings in the Clerk Dashboard, although not recommended. Learn more about how Clerk's OAuth consent screen works.
Once you have accepted, you'll be redirected to the OAuth callback route, the redirect_uri specified earlier. This process will exchange the authorization code for an access token, and return the access token and refresh token as a JSON response, similar to this:
{
"access_token": "xxx",
"expires_in": 7200,
"id_token": "xxx",
"refresh_token": "xxx",
"scope": "openid email profile",
"token_type": "bearer"
}
With the OAuth flow complete, the client now has a working access token. The next step would normally be for the client to use that token to make an authenticated request to your app's API endpoints. To learn more about how to accept and verify OAuth tokens using Clerk, see the guide on verifying OAuth tokens. </Steps>
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā