***

title: Set up OAuth for RBAC
subtitle: >-
Integrate your OAuth provider with Fern Docs to authenticate users and assign
roles
-----

This guide walks you through connecting your OAuth provider to Fern so that users are authenticated and assigned roles for [role-based access control (RBAC)](/learn/docs/authentication/rbac). If you haven't already, start by [defining your roles](/learn/docs/authentication/rbac#define-all-the-roles-in-your-docsyml) in `docs.yml`.

<Steps>
  <Step title="Create an OAuth client">
    Go to your OAuth provider's dashboard. Create a new **web application** client. This is the client that will be used by Fern to authenticate users with your OAuth provider.
  </Step>

  <Step title="Allowlist Fern callbacks">
    You will need to allowlist the following callback in your OAuth provider:
    `https://<your-domain>/api/fern-docs/oauth2/callback`.

    Replace `<your-domain>` with whatever domain you are using for your Fern Docs site. If you want to authenticate both your `.docs.buildwithfern.com` and custom domain, you will need to allowlist both.
  </Step>

  <Step title="Send OAuth client details to Fern">
    Fern will need the following details to configure OAuth authentication:

    * [ ] Docs domain
    * [ ] Client ID
    * [ ] Client secret
    * [ ] Authorization URL (e.g. `https://<your-oauth-tenant>/oauth2/authorize`)
    * [ ] Token URL (e.g. `https://<your-oauth-tenant>/oauth2/token`)
    * [ ] Scopes (e.g. `openid`, `profile`, `email`)
    * [ ] Issuer URL (e.g. `https://<your-domain>`)

    <Note title="Specifying an audience">
      If your client is connected to an API, you may need to specify an audience in the authentication request.

      The updated authorization URL may look like this: `https://<your-oauth-tenant>/oauth2/authorize?audience=<your-api-identifier>`
    </Note>

    Send these details to [support@buildwithfern.com](mailto:support@buildwithfern.com) or in your dedicated Slack channel.
  </Step>

  <Step title="Wait for Fern to configure OAuth">
    Wait for Fern to configure OAuth. You will receive a notification when the site is ready to use authentication.
  </Step>

  <Step title="Add a custom claim to set user roles">
    Add a custom claim to your OAuth provider's token response. This claim will be used to set the user's roles in Fern Docs. The resulting token response should look something like this:

    ```json {12-15}
    {
      "iss": "https://your-tenant.us.auth0.com/",
      "sub": "auth0|507f1f77bcf86cd799439011",
      "aud": "your_client_id_here",
      "iat": 1728388800,
      "exp": 1728475200,
      "email": "user@example.com",
      "email_verified": true,
      "name": "John Doe",
      "nickname": "johndoe",
      "picture": "https://s.gravatar.com/avatar/...",
      "roles": [
        "custom-role",
        "user-specific-role"
      ]
    }
    ```

    <Warning title="Using a claim other than `roles`">
      Some OAuth providers have strict requirements for custom claims. If you need to use a claim other than `roles`, reach out to Fern and specify which claim should be parsed for the user's roles.
    </Warning>

    <AccordionGroup>
      <Accordion title="Using Auth0">
        To add a custom claim to Auth0, you need to create a **custom action**. This action will be used to add the custom claim to the token response.

        1. Go to the **Actions** tab in the Auth0 dashboard.
        2. Create a **Custom Action**.
        3. Select **Login/Post Login**.
        4. Add logic to set a roles.
           ```js Example Action
           exports.onExecutePostLogin = async (event, api) => {
             const roles = event.user.app_metadata?.roles; // or however you store user roles

             if (roles) {
               const namespace: "https://<your-domain>.com"; // important: custom claims must be namespaced
               api.accessToken.setCustomClaim(`${namespace}/roles`, roles);
             }
           };
           ```
        5. Click **Create**.
        6. Add the action to your **Post Login Flow**.
      </Accordion>

      <Accordion title="Using another provider">
        If you are using a different OAuth provider, reach out to Fern with any questions on setting up a custom claim.
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>