Authentication

Set up OAuth for RBAC

Integrate your OAuth provider with Fern Docs to authenticate users and assign roles
View as Markdown

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). If you haven’t already, start by defining your roles in docs.yml.

1

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.

2

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.

3

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>)
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>

Send these details to support@buildwithfern.com or in your dedicated Slack channel.

4

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.

5

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:

1{
2  "iss": "https://your-tenant.us.auth0.com/",
3  "sub": "auth0|507f1f77bcf86cd799439011",
4  "aud": "your_client_id_here",
5  "iat": 1728388800,
6  "exp": 1728475200,
7  "email": "user@example.com",
8  "email_verified": true,
9  "name": "John Doe",
10  "nickname": "johndoe",
11  "picture": "https://s.gravatar.com/avatar/...",
12  "roles": [
13    "custom-role",
14    "user-specific-role"
15  ]
16}

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.

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.
    Example Action
    1exports.onExecutePostLogin = async (event, api) => {
    2  const roles = event.user.app_metadata?.roles; // or however you store user roles
    3
    4  if (roles) {
    5    const namespace: "https://<your-domain>.com"; // important: custom claims must be namespaced
    6    api.accessToken.setCustomClaim(`${namespace}/roles`, roles);
    7  }
    8};
  5. Click Create.
  6. Add the action to your Post Login Flow.

If you are using a different OAuth provider, reach out to Fern with any questions on setting up a custom claim.