SSO and SCIM

Every Fermium account can sign in with Google. On Business and above, a workspace can also connect its own identity provider over OpenID Connect, so that people on the company's email domains sign in with Microsoft Entra ID, Okta, or any OIDC-compliant provider. On Enterprise, the same provider can create, update and deactivate members and push groups through SCIM.

How workspace SSO works

You register Fermium as an application in your identity provider and give Fermium three things: the provider's issuer URL, the client id, and the client secret. You also list the email domains that should sign in this way.

Sign-in is the standard authorization code flow with PKCE and a nonce. Fermium reads the provider's discovery document at <issuer>/.well-known/openid-configuration, sends the person to the provider's authorization endpoint with the scopes openid email profile, exchanges the code, and verifies the ID token's signature against the provider's published keys, its issuer, its audience and the nonce. The email comes from the email claim, or from preferred_username, upn or unique_name when the provider does not send email; a token that marks the email as unverified is refused.

The email's domain must be one of the domains you configured, otherwise the sign-in is refused with a 403 even if the token is valid. That is what stops a shared identity tenant from landing people in the wrong workspace. Matching accounts are found by the provider's subject identifier first, then by email, so a person who used Google before keeps the same account. New accounts are created as members if the workspace has a seat free; a full workspace refuses the sign-in with a message naming the plan.

A successful sign-in sets the same 90-day session cookie as Google sign-in and is recorded in the audit log as user.sign_in with method: sso.

The client secret is stored encrypted and is never returned by the API; settings only report whether one is set.

Configuring it

Workspace owners and admins configure SSO with PUT /api/sso:

{
  "issuer": "https://login.microsoftonline.com/<tenant-id>/v2.0",
  "client_id": "…",
  "client_secret": "…",
  "domains": ["acme.com"],
  "enforced": false
}

Rules:

• issuer must be an https URL.
• At least one domain, and each domain must have a current member of the workspace with an address on it. A domain can be routed to one workspace's provider at a time; a clash is a 409.
• client_secret may be omitted on later updates to keep the stored one.

GET /api/sso returns the settings (without the secret), the redirect URI to register with your provider, https://fermium.app/auth/sso/callback, and the workspace's sign-in URL, https://fermium.app/auth/sso/<workspace-slug>. DELETE /api/sso turns SSO off; accounts stay and people sign in with Google again. Configuration changes are audited as sso.config and sso.delete.

The app's Settings, then Sign-in page does not hold these fields yet; use the API.

Microsoft Entra ID

1. In the Entra admin center open App registrations and create a new registration. Any name; single tenant is fine.
2. Under Authentication add a Web platform with the redirect URI https://fermium.app/auth/sso/callback.
3. Under Certificates & secrets create a client secret and copy its value.
4. Under Token configuration add the optional claim email to the ID token. Entra otherwise sends only preferred_username, which Fermium accepts when it is an address, but the email claim is the reliable one.
5. Copy the Application (client) ID and the Directory (tenant) ID from the overview page.
6. Send to Fermium: issuer https://login.microsoftonline.com/<tenant-id>/v2.0, the client id, the secret, your domains.

Okta

1. In the Okta admin console open Applications, then Create App Integration, and choose OIDC with the Web Application type.
2. Set the sign-in redirect URI to https://fermium.app/auth/sso/callback. Assign the users or groups who should have access.
3. Copy the Client ID and Client secret.
4. The issuer is your org's authorization server, https://<org>.okta.com, or the URL of a custom authorization server if you use one. The default scopes openid email profile are all Fermium asks for.
5. Send to Fermium: the issuer, the client id, the secret, your domains.

Any other provider

Any OpenID Connect provider that publishes a discovery document and signs ID tokens with RSA or ECDSA keys works. Register the redirect URI, allow the three scopes, and make sure the ID token carries an email.

Enforced mode

With enforced: false, people on your domains can sign in either way. With enforced: true, a Google sign-in for an address on one of your domains is redirected to your identity provider instead of completing, so the provider's own controls (MFA, device policy, offboarding) are the only way in.

The sign-in lookup

A public endpoint, GET /auth/sso/lookup?email=ada@acme.com, answers whether that address signs in through a workspace provider: {"sso": true, "url": "https://fermium.app/auth/sso/acme?next=...", "enforced": true} or {"sso": false}. It never says which workspace or provider. It is rate limited per IP. The sign-in URL it returns, https://fermium.app/auth/sso/<workspace-slug>, can also be bookmarked or put on your intranet; it starts the flow directly.

SCIM provisioning (Enterprise)

SCIM lets your identity provider manage the workspace's members for you: create accounts when people are assigned to the Fermium app, update them, deactivate them when they leave, and push groups that you can then use in access grants.

Setup:

1. In Fermium, mint a SCIM token: POST /api/scim/tokens with an optional {"label": "Entra"} (owner or admin). The response contains the token, starting with fsc_, once. Fermium stores only a hash. GET /api/scim/tokens lists tokens with their last-used time; DELETE /api/scim/tokens/{id} revokes one. Both are audited.
2. In your provider, configure SCIM provisioning with the tenant URL https://fermium.app/scim/v2 and the token as the bearer secret. Entra calls this "Secret Token"; Okta calls it "HTTP Header" authentication with a bearer token.
3. Assign users and groups to the application and start provisioning.

What it does:

The details of the SCIM surface (filters, PATCH operations, errors) are in the SCIM reference. Provisioned members and groups appear in the audit log as member.join, member.leave, group.create and group.delete with via: scim.

What SSO does not change

• Documents and their access work exactly as before. A Restricted document still opens only for people with permission; SSO changes how they prove who they are.
• Agents keep authenticating with OAuth 2.1 in the browser, or with static tokens for headless jobs.
• A person removed by SCIM or by an admin keeps their documents in a personal workspace; nothing is deleted.