Company SSO

Each SSO provider adds a "Continue with …" button to the sign-in page. All six presets use OpenID Connect with the authorization code flow and PKCE. You register the docs as an app with the provider, then copy its client ID into the config and its secret into an environment variable.

How every provider is set upCopy Anchor Link

https://<docs host><basePath>/_auth/callback/<id>

access: {
  groups: { staff: { domains: ['acme.com'] } },
  rules: [{ path: '/internal/*', groups: ['staff'] }],
  providers: [
    { type: 'google', clientId: '1234-abc.apps.googleusercontent.com', clientSecretEnv: 'GOOGLE_CLIENT_SECRET', hostedDomain: 'acme.com' },
  ],
},

ORBITDOCS_AUTH_SECRET=<32+ random characters>
GOOGLE_CLIENT_SECRET=<client secret from the provider>

Options every provider takesCopy Anchor Link

What the server reads from the provider:

• Email: the email claim, else preferred_username. If neither looks like an email, it calls the provider's userinfo endpoint. A reader with no email can't sign in.
• Name: the name claim.
• Groups: the claim named by groupsClaim (default groups), as a list. It is matched against idpGroups in your access groups.

To offer two apps of the same provider (say, two Okta orgs), give them different ids. Each gets its own callback URL.

GoogleCopy Anchor Link

Google accounts and Google Workspace.

providers: [
  {
    type: 'google',
    clientId: '1234-abc.apps.googleusercontent.com',
    clientSecretEnv: 'GOOGLE_CLIENT_SECRET',
    hostedDomain: 'acme.com',
  },
],

• hostedDomain limits sign-in to one Workspace domain. The server asks Google to show only that domain's accounts, then checks the hd claim of the token. Other accounts see "Sign in with your acme.com account."
• Issuer: https://accounts.google.com.
• Google ID tokens carry no groups. Use emails and domains in your access groups, or add groups with personalization.

Microsoft Entra IDCopy Anchor Link

Microsoft Entra ID (formerly Azure AD) work and school accounts.

providers: [
  {
    type: 'microsoft',
    tenantId: '72f988bf-86f1-41af-91ab-2d7cd011db47',
    clientId: 'b3c1a2d4-0000-4000-8000-123456789abc',
    clientSecretEnv: 'ENTRA_CLIENT_SECRET',
  },
],

• tenantId is required. Use your tenant's ID, not common or organizations: the issuer must be a single tenant (https://login.microsoftonline.com/<tenantId>/v2.0).
• Email: Entra often omits the email claim, so the server falls back to preferred_username (the user principal name, usually an email address).
• Groups: under Token configuration → Add groups claim, choose Security groups. Entra then puts group object IDs (GUIDs) in groups, so list those IDs in idpGroups.
• App roles instead of groups: define roles under App roles, assign users to them in Enterprise applications, and set groupsClaim: 'roles'. idpGroups then lists role values.

OktaCopy Anchor Link

providers: [
  {
    type: 'okta',
    domain: 'acme.okta.com',
    clientId: '0oa1b2c3d4e5f6g7h8i9',
    clientSecretEnv: 'OKTA_CLIENT_SECRET',
    scopes: ['openid', 'email', 'profile', 'groups'],
  },
],

• domain is your Okta domain, with or without https://.
• authorizationServer: leave it out to use the org authorization server (issuer https://acme.okta.com). Set it to a custom server id, such as default, to use that one (issuer https://acme.okta.com/oauth2/default).
• Groups with the org authorization server: on the app's Sign On tab, edit OpenID Connect ID Token, set the Groups claim type to Filter, name it groups, and pick a filter (for example Matches regex .*). Request the groups scope as shown above.
• Groups with a custom authorization server: under Security → API → Authorization Servers → (server) → Claims, add a groups claim of type Groups, included in the ID token.

Auth0Copy Anchor Link

providers: [
  {
    type: 'auth0',
    domain: 'acme.us.auth0.com',
    clientId: 'Xyz123AbC456dEf789',
    clientSecretEnv: 'AUTH0_CLIENT_SECRET',
    groupsClaim: 'https://docs.acme.com/groups',
  },
],

• domain: your Auth0 domain, or your custom domain if you use one. The issuer is https://<domain>/.
• Auth0 adds no groups claim by default. Add one with a post-login Action, then set groupsClaim to the same claim name:

exports.onExecutePostLogin = async (event, api) => {
  // Roles assigned to the user in Auth0 become docs groups.
  api.idToken.setCustomClaim('https://docs.acme.com/groups', event.authorization?.roles ?? []);
};

ClerkCopy Anchor Link

Use this preset for staff who sign in to a Clerk instance through Clerk's OAuth applications. To reuse the Clerk session your customers already have in your product, use an app session instead.

providers: [
  {
    type: 'clerk',
    domain: 'clerk.acme.com',
    clientId: 'abc123XYZ',
    clientSecretEnv: 'CLERK_OAUTH_SECRET',
  },
],

• domain is your Clerk Frontend API domain, such as clerk.acme.com or example-name.clerk.accounts.dev. The issuer is https://<domain>.
• Clerk ID tokens carry no groups. Use emails and domains, or personalization.

KeycloakCopy Anchor Link

providers: [
  {
    type: 'keycloak',
    name: 'Acme SSO',
    url: 'https://auth.acme.com',
    realm: 'acme',
    clientId: 'docs',
    clientSecretEnv: 'KEYCLOAK_CLIENT_SECRET',
  },
],

• url is the Keycloak base URL; the issuer is <url>/realms/<realm>. Older Keycloak versions served under /auth need it in the URL: https://auth.acme.com/auth.
• Groups: open the client's Client scopes tab, then its dedicated scope, and Add mapper → By configuration → Group Membership. Set Token Claim Name to groups and turn Full group path off, so groups arrive as staff rather than /staff.
• For local testing over http://, the server allows an http issuer.

Combine providersCopy Anchor Link

You can list several providers, and add an appSession too. Each gets its own button. A common setup: staff use company SSO, customers use their product account.

access: {
  groups: {
    staff: { idpGroups: ['docs-staff'] },
    partners: { idpGroups: ['partner'] },
  },
  providers: [
    { type: 'okta', domain: 'acme.okta.com', clientId: '0oa1b2c3', clientSecretEnv: 'OKTA_CLIENT_SECRET', scopes: ['openid', 'email', 'profile', 'groups'] },
  ],
  appSession: { type: 'supabase', projectUrl: 'https://abcd1234.supabase.co', loginUrl: 'https://app.acme.com/login' },
},

TroubleshootingCopy Anchor Link

Next stepsCopy Anchor Link