Skip to main content
Docs

Use OAuth for 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.

How the flow works

Before diving into implementations details, it's important to understand the different actors involved in this flow:

  • Client: The third-party app that wants to access a user's data from your application (resource service). This app is configured to obtain OAuth tokens from Clerk.
  • Authorization service (or Identity Provider, IdP): The service that authenticates the user and grants the OAuth tokens. In this example, Clerk would be the authorization service or IdP.
  • Resource service (or Service Provider, SP): The backend server that hosts the user's data that the client wants to access. In this example, this would be your own application that uses Clerk for authentication and route protection.

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.

Create a Clerk OAuth application

To create a Clerk OAuth application:

  1. In the Clerk Dashboard, navigate to the OAuth Applications page.
  2. Select Add OAuth application. A modal will open.
  3. Complete the following fields:
  4. Select Add. A modal will open with your Client Secret. For security reasons, Clerk does not store your Client Secret and cannot show it to you again, so ensure that you copy it and store it somewhere secure, like an environment variable.
  5. You'll be redirected to your app's settings page. Under Application credentials, save the Client ID somewhere secure as you'll need it later.
  6. In the Redirect URIs field, add the redirect URI provided by your client. This is the URL that Clerk will redirect to with an authorization code after the user has authenticated and consented to the access request. This guide uses 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.

Test the OAuth flow

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.

  1. Clone the following repository to your machine.
  2. In your terminal and within your project, run the following command:
    terminal
    cp .env.sample .env
  3. In your newly created .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.
  4. In your terminal, run the following command to install dependencies:
    terminal
    npm i
  5. In your terminal, run the following command to start the server:
    terminal
    npm start

Finished 🎉

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.

Feedback

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

Last updated on