AuthenticationSetup

Set up OAuth

Fern-managed authentication integrated with your login system

View as Markdown

With OAuth, Fern manages the auth flow for you. You give Fern access to your OAuth provider, and Fern handles the fern_token cookie that integrates your docs with your existing login system. Like JWT, OAuth enables:

How it works

  1. A user clicks Login on your docs site and Fern initiates an OAuth flow with your provider.
  2. The user authenticates on your OAuth provider’s login page.
  3. Your provider redirects back to Fern with an authorization code, which Fern exchanges for an access token.
  4. Fern sets a fern_token cookie containing the user’s access and credentials.

Configuration

1

Create an OAuth client

Go to your OAuth provider’s dashboard and create a new web application client.

2

Allowlist Fern callbacks

Allowlist the following callback in your OAuth provider: https://<your-domain>/api/fern-docs/oauth2/callback.

Replace <your-domain> with your Fern Docs domain. If you use both a .docs.buildwithfern.com and a custom domain, allowlist both.

3

Send OAuth client details to Fern

Send the following to support@buildwithfern.com or your dedicated Slack channel:

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

4

Wait for Fern to configure OAuth

Fern will configure OAuth on your site. You’ll receive a notification when authentication is ready.

5

Enable RBAC or API key injection (optional)

Once OAuth is working, configure the features you need:

1

Add a custom claim

Add a custom claim to your OAuth provider’s token response so that Fern can determine each user’s roles. 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.
2

Configure RBAC

Once your token response includes roles, define those roles in docs.yml and assign them to navigation items and page content. See Role-based access control for the full setup.

Set up an authenticated account for Fern so Fern can authorize users on your behalf, and configure your OAuth application to return user API keys when Fern requests tokens. Contact support@buildwithfern.com to coordinate this setup.