Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 118 additions & 0 deletions apps/landing/src/content/docs/reference/single-sign-on.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
---
title: "Single sign-on and SCIM provisioning"
description: "Sign in to Maple through your identity provider with SAML 2.0 or OIDC, verify your email domains, enforce SSO, and provision members, roles and deprovisioning with SCIM 2.0."
group: "Reference"
order: 11
---

Single sign-on (SSO) lets members sign in to Maple through your identity provider (IdP). SCIM provisioning lets the IdP create, update and remove Maple members, and set their roles from IdP groups.

Both are available on the Enterprise plan. Only organization admins can configure them, under **Settings → SSO & SCIM** in the dashboard. Every change is recorded in the organization's audit log, under **Security → Audit log**.

SSO and SCIM work the same for organizations in the US and EU [regions](/docs/reference/regions).

## Supported identity providers

| Protocol | Identity providers |
| -------- | ------------------------------------------------------------------- |
| SAML 2.0 | Okta, Microsoft Entra ID, Google Workspace, any custom SAML 2.0 IdP |
| OIDC | GitHub Enterprise, GitLab, any OpenID Connect provider |

## Set up single sign-on

Setup has four steps. Until the last one, members keep signing in the way they do today.

### 1. Verify a domain

SSO applies to email addresses on domains you have verified.

1. Under **Settings → SSO & SCIM**, add your domain, for example `example.com`.
2. Maple shows a value of the form `maple-domain-verification=...`. Publish it as a DNS TXT record named `_maple-challenge.example.com`.
3. Click **Verify**.

DNS changes can take a few minutes to be visible. If verification fails, wait and try again. Add every domain your members sign in with.

### 2. Connect your identity provider

Choose SAML or OIDC and enter your IdP's details.

**SAML 2.0**

- In Maple, give the IdP metadata URL. If your IdP has no metadata URL, give its SSO URL, entity ID and signing certificate instead.
- In your IdP, create a SAML application and paste the values Maple shows: the ACS URL, and the SP entity ID or SP metadata URL.

**OIDC**

- In your IdP, create an OIDC application.
- In Maple, give the discovery URL, client ID and client secret.

A new connection starts **not enforced**. Members who use the IdP can sign in through it, and everyone else can still sign in as before. Use this to test the connection with your own account.

### 3. Add a break-glass admin

Add at least one admin to the bypass list. Only members with a verified email on one of the connection's domains can be added. A member on this list can still sign in with an email code when the IdP is down or misconfigured, so you cannot lock the whole organization out.

### 4. Enforce SSO

Turn on enforcement. From then on, everyone who signs in with an email address on a verified domain must go through the IdP. The only exception is the bypass list.

Existing members do not need to do anything in advance. On their next sign-in they go through the IdP, and their Maple account is linked to their IdP identity.

## Set up SCIM provisioning

SCIM needs a connected IdP. Once the connection from step 2 is in place, click **Set up SCIM**. Maple shows:

- a SCIM 2.0 base URL
- a bearer token

The token is shown once. Copy it before you close the dialog.

Paste both into your IdP's provisioning settings:

| IdP | Where | What to enter |
| ------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| Okta | **Provisioning → API integration** | The base URL and the token. Then enable **Create Users**, **Update User Attributes**, **Deactivate Users** and **Push Groups**. |
| Microsoft Entra ID | **Provisioning**, mode **Automatic** | The base URL as **Tenant URL** and the token as **Secret token**. |
| Other IdPs | The SCIM or provisioning settings | The base URL and the token as a bearer token. |

Every provisioned user needs an email address on a verified domain. Users without one fail to provision.

### Manage the SCIM connection

- **Rotate token** issues a new token. The old token keeps working for a short grace period, so you can update the IdP without interrupting provisioning.
- **Pause** stops provisioning. Members already provisioned stay in the organization.
- **Remove** stops provisioning and removes the memberships that SCIM granted. Members who joined another way are not affected.

## Map groups to roles

Groups your IdP pushes appear in Maple under **Settings → SSO & SCIM**. Map each group to a Maple role: **Admin**, **Engineer**, **Member** or **Analyst**.

- The order of the mappings sets precedence. A user in several mapped groups gets the role of the highest mapping in the list.
- A user in no mapped group gets the default **Member** role.
- A new or changed mapping applies the next time your IdP pushes the group. In Okta, open **Push Groups** and choose **Push now**; Entra ID applies it on its next provisioning cycle.
- A role assigned by a mapping follows the IdP. When the user's groups change in the IdP, their Maple role changes with them.

Nested groups are not followed. Add users directly to the group you mapped.

## Deprovisioning

When you deactivate or remove a user in the IdP, Maple:

- signs them out of every session
- removes the membership that SCIM granted
- revokes their Maple API keys, CLI credentials and device credentials

## Troubleshooting

| Problem | What to do |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Domain verification says the TXT record is not found | Wait a few minutes for DNS to update, then click **Verify** again. Check that the record is named `_maple-challenge.<domain>`, not the bare domain. |
| "Verify the domain before using it for SSO" | The domain is added but not verified yet. Finish [step 1](#1-verify-a-domain) first. |
| A user fails to provision | The user has no email address, or it is not on a verified domain. Set an email on a verified domain in the IdP, or verify that domain in Maple. |
| A user gets the Member role instead of a mapped role | Push the group again from your IdP after saving the mapping. If they are only in a group nested inside the mapped group, add them to the mapped group directly. |

## Next steps

- [Authentication](/docs/reference/authentication): the API keys and other credentials deprovisioning revokes
- [Regions](/docs/reference/regions): US and EU hosts
- [Audit log detections](/docs/alerting/alert-rules#audit-log-detections): alert on SSO and membership changes
16 changes: 16 additions & 0 deletions apps/web/src/lab/entries/sso.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
import { defineShellLab } from "../shell-lab"
import { breadcrumbs, Flags, flags, init, Message, Model, update, view } from "../sso-lab"

// `/lab/sso`: the settings SSO & SCIM tab over fixtures, its states and dialogs on demand (`?state=`).

export const lab = defineShellLab("SSO & SCIM", {
Model,
Message,
Flags,
flags,
init,
update,
view,
currentPath: "/lab/sso",
breadcrumbs,
})
8 changes: 8 additions & 0 deletions apps/web/src/lab/registry.ts
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,14 @@ export const LAB_ENTRIES: ReadonlyArray<LabEntry> = [
kind: "lab",
session: "none",
},
{
path: "/lab/sso",
title: "SSO & SCIM",
description:
"The settings SSO & SCIM tab: not entitled, empty, a pending domain, connected, fully configured, the one-time token, the enforce confirm and a read-only member (`?state=`).",
kind: "lab",
session: "none",
},
{
path: "/lab/members",
title: "Members",
Expand Down
242 changes: 242 additions & 0 deletions apps/web/src/lab/sso-lab.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,242 @@
import {
EnterpriseSsoDocument,
IsoDateTimeString,
ScimDirectoryDocument,
ScimGroupDocument,
ScimRoleMappingDocument,
ScimTokenIssued,
SsoBypassUserDocument,
SsoConnectionDocument,
SsoDomainDocument,
UserId,
} from "@maple/domain/http"
import { Array as Arr, Effect, Option, Result, Schema } from "effect"
import { Command, type Update } from "foldkit"
import type { Html, HtmlBuilder } from "foldkit/html"
import { defineMessageUnion } from "foldkit/message"
import * as SsoModel from "../page/settings/sso/model"
import * as SsoUpdate from "../page/settings/sso/update"
import * as SsoView from "../page/settings/sso/view"
import type { Resources } from "../platform/resources"
import { keepLocal } from "./local-commands"

// `/lab/sso`: the settings SSO & SCIM tab over fixtures. `?state=` picks one: not-entitled, empty,
// pending (a domain awaiting its TXT record), connected, configured, token, enforce, member.

export const LabState = Schema.Literals([
"not-entitled",
"empty",
"pending",
"connected",
"configured",
"token",
"enforce",
"member",
])
export type LabState = typeof LabState.Type

export const Flags = Schema.Struct({ state: LabState })
export type Flags = typeof Flags.Type

export const flags: Effect.Effect<Flags> = Effect.sync(() => ({
state: Option.getOrElse(
Schema.decodeUnknownOption(LabState)(new URLSearchParams(window.location.search).get("state")),
(): LabState => "configured",
),
}))

export const Model = Schema.Struct({ sso: SsoModel.Model })
export type Model = typeof Model.Type

export const Message = defineMessageUnion({ GotSsoMessage: { message: SsoModel.Message } })
export type Message = typeof Message.Type

type Return = Update.Return<Model, Message, Resources>

const iso = Schema.decodeSync(IsoDateTimeString)
const userId = Schema.decodeSync(UserId)

const pendingDomain = new SsoDomainDocument({
domain: "acmelabs.io",
status: "pending",
recordName: "_maple-challenge.acmelabs.io",
recordValue: "maple-domain-verification=3f9c2a71d04b4e8e9a6b51c07d2e8f14",
verifiedAt: null,
})
const verifiedDomain = new SsoDomainDocument({
domain: "acme.com",
status: "verified",
recordName: "_maple-challenge.acme.com",
recordValue: "maple-domain-verification=91b0c4d2e7f84a3b8c5d6e7f9a0b1c2d",
verifiedAt: iso("2026-11-14T09:12:00.000Z"),
})

const connection = (enforced: boolean) =>
new SsoConnectionDocument({
name: "Acme Okta",
provider: "saml_okta",
protocol: "saml",
domains: ["acme.com"],
enforced,
acsUrl: "https://clerk.maple.dev/v1/saml/acs/samlc_2xAcmeOkta",
spEntityId: "https://clerk.maple.dev/saml/samlc_2xAcmeOkta",
spMetadataUrl: "https://clerk.maple.dev/v1/saml/metadata/samlc_2xAcmeOkta",
idpMetadataUrl: "https://acme.okta.com/app/exk1a2b3c4/sso/saml/metadata",
idpSsoUrl: null,
idpEntityId: null,
idpCertificateExpiresAt: iso("2029-03-01T00:00:00.000Z"),
oidcDiscoveryUrl: null,
oidcClientId: null,
createdAt: iso("2026-11-14T09:20:00.000Z"),
})

const directory = new ScimDirectoryDocument({
endpointUrl: "https://api.clerk.com/scim/v2",
enabled: true,
paused: false,
createdAt: iso("2026-11-14T09:30:00.000Z"),
})

const groups = [
new ScimGroupDocument({ groupId: "grp_eng", displayName: "Engineering" }),
new ScimGroupDocument({ groupId: "grp_fin", displayName: "Finance" }),
new ScimGroupDocument({ groupId: "grp_it", displayName: "IT Admins" }),
new ScimGroupDocument({ groupId: "grp_sre", displayName: "SRE" }),
]

const bypass = [new SsoBypassUserDocument({ userId: userId("user_ada"), identifier: "ada@acme.com" })]

const documentOf = (state: LabState): EnterpriseSsoDocument => {
const base = {
entitled: true,
domains: [] as Array<SsoDomainDocument>,
connection: null,
directory: null,
roleMappings: [] as Array<ScimRoleMappingDocument>,
groups: [] as Array<ScimGroupDocument>,
bypassUsers: [] as Array<SsoBypassUserDocument>,
}
switch (state) {
case "not-entitled":
return new EnterpriseSsoDocument({ ...base, entitled: false })
case "empty":
return new EnterpriseSsoDocument(base)
case "pending":
return new EnterpriseSsoDocument({ ...base, domains: [verifiedDomain, pendingDomain] })
case "connected":
case "enforce":
return new EnterpriseSsoDocument({
...base,
domains: [verifiedDomain, pendingDomain],
connection: connection(false),
bypassUsers: bypass,
})
case "configured":
case "token":
case "member":
return new EnterpriseSsoDocument({
...base,
domains: [verifiedDomain],
connection: connection(true),
directory,
groups,
bypassUsers: bypass,
roleMappings: [
new ScimRoleMappingDocument({
groupId: "grp_it",
groupName: "IT Admins",
role: "org:admin",
}),
new ScimRoleMappingDocument({
groupId: "grp_sre",
groupName: "SRE",
role: "org:engineer",
}),
new ScimRoleMappingDocument({
groupId: "grp_eng",
groupName: "Engineering",
role: "org:member",
}),
new ScimRoleMappingDocument({
groupId: "grp_fin",
groupName: "Finance",
role: "org:analyst",
}),
],
})
}
}

const MEMBERS: ReadonlyArray<SsoModel.MemberOption> = [
{ userId: "user_ada", name: "Ada Lovelace", identifier: "ada@acme.com" },
{ userId: "user_grace", name: "Grace Hopper", identifier: "grace@acme.com" },
{ userId: "user_linus", name: "Linus Contractor", identifier: "linus@gmail.com" },
]

const step = (model: SsoModel.Model, message: SsoModel.Message): SsoModel.Model =>
SsoUpdate.update(model, message).model

export const init = (flags: Flags): Return => {
const document = documentOf(flags.state)
const loaded = Arr.reduce(
[
SsoModel.Message.CompletedFetchDocument({ result: Result.succeed(document) }),
SsoModel.Message.CompletedFetchMembers({ result: Result.succeed(MEMBERS) }),
],
SsoUpdate.init(flags.state !== "member").model,
step,
)
const opening =
flags.state === "token"
? SsoModel.Message.CompletedIssueToken({
action: "rotateToken",
result: Result.succeed(
new ScimTokenIssued({
document,
token: "scim_live_7Qm2c9VxR4tLpZ8aKfJ3wY6nB1hD5sE0",
}),
),
})
: flags.state === "enforce"
? SsoModel.Message.ToggledEnforcement()
: null
if (opening === null) return { model: { sso: loaded } }
// The dialog's open commands run, so it mounts as it would from a click.
const opened = SsoUpdate.update(loaded, opening)
return {
model: { sso: opened.model },
commands: Command.mapMessages(keepLocal(opened.commands), (message) =>
Message.GotSsoMessage({ message }),
),
}
}

/** Kit commands run; every API read and write is dropped. */
export const update = (model: Model, message: Message): Return =>
Message.match<Return>(message, {
GotSsoMessage: ({ message: child }) => {
const next = SsoUpdate.update(model.sso, child)
return {
model: { sso: next.model },
commands: Command.mapMessages(keepLocal(next.commands), (message) =>
Message.GotSsoMessage({ message }),
),
}
},
})

export const breadcrumbs = [{ label: "Lab", href: "/lab" }, { label: "SSO & SCIM" }] as const

export const view = (model: Model, h: HtmlBuilder<Message>): Html =>
h.div(
[h.Class("mx-auto w-full max-w-4xl p-6")],
[
h.submodel({
slotId: "lab-sso",
model: model.sso,
view: SsoView.view,
viewInputs: { isKnownMember: true },
toParentMessage: (message: SsoModel.Message) => Message.GotSsoMessage({ message }),
}),
],
)
Loading
Loading