Skip to content

Single sign-on ​

OpenID Connect, per workspace. The identity provider belongs to the company using the workspace, so its own workspace admin configures it — an operator who has to be asked to wire one up is a support ticket standing between a customer and their own directory.

It needs the manage_sso capability.

What it is built on ​

The same authorization-code flow as OAuth, plus two things:

  • Discovery — three URLs fetched from the provider rather than configured by hand.
  • An ID token — a signed statement of who signed in, rather than a profile fetched on trust.

The signed state cookie, the code exchange, and the single place an account comes into existence are all reused rather than reimplemented.

The ID token is verified, not decoded ​

Its signature is checked against the provider's JWKS, and then iss, aud, exp and nonce are each asserted separately.

Each of those is a real vulnerability class in somebody's integration — alg: none, RS256/HS256 confusion, a token minted for another client of the same provider, a replay into a different browser's flow — so each gets its own assertion rather than a general air of care.

The nonce is the one already inside the signed state, which binds the token to the same flow with one secret and one lifetime.

Whose account it is ​

A workspace's provider is configured by that workspace's own admin, and it can say any address it likes. So its word alone never decides whose account somebody signs in to. Trusting it once let one workspace's admin sign in as anybody on the deployment, past their password and second factor.

Instead, the provider's own identifier for the person is linked to an account once, and only with the account's consent:

  • The first sign-in through a connection sends a confirmation mail to the address the provider named. Its link works only in the browser that just went through the provider. Following it links the two, and every later sign-in through that connection goes straight in.
  • An account with two-step sign-in gives its code before anything is linked.
  • A provider that says the address is not verified is refused.
  • A link counts only while the account is a member of the connection's workspace.
  • A workspace's SSO never makes anybody an operator of the deployment, whatever NOTESFLOW_ADMIN_EMAILS says.

The sign-in page answers the same whether or not a mail went out. People see and remove their own links in Settings → Single sign-on.

At a proven domain the confirmation mail is skipped: the company controls those mailboxes already.

Two admission roads, one field apart ​

A connection either claims domains or does not, and that single field is the difference between SSO-as-onboarding and SSO-as-authentication:

  • Claims domains — anyone signing in at one of them is admitted, with the role the connection names. Nobody writes an invitation.
  • Claims none — it authenticates and nothing more. People still arrive by invitation exactly as before; SSO has only replaced the password.

Two rules follow, and both are deliberate:

  • A claimed domain admits only through that connection's SSO, never through an email link. The claim a workspace is making is "people our identity provider authenticates at this domain are ours" — not "anyone who can receive mail at this domain is ours", and only the first is something the workspace is in a position to say.
  • An invitation still beats a domain default when both apply. The specific statement wins, so turning SSO on cannot quietly re-grade people who were already invited.

A domain belongs to at most one connection deployment-wide, enforced by a primary key rather than resolved at sign-in. Two workspaces claiming example.com is a configuration mistake to refuse where somebody can read the reason, not an ambiguity to break a tie in.

A domain's role applies when the membership is made. Later sign-ins leave the role alone, so somebody promoted by hand stays promoted; to have the provider decide roles on purpose, use group mappings.

Proving a domain ​

A claim on its own is first come, first served — a squatter could keep a company out of its own domain. So each claimed domain can be proven by DNS. The console shows a TXT record to publish under it:

_notesflow.example.com   TXT   "notesflow-verification=…"

Press Check and the proof is recorded. Then:

  • People at that domain sign in through SSO without a confirmation mail. An account with its own second factor still gives its code.
  • Nobody else can take the domain. Proving a domain another workspace claimed but never proved takes it over, and the losing workspace's audit log says so. A proven claim cannot be taken.

Proof is checked when you ask, not on a schedule, and a domain stays proven if the record is later removed. Rotating NOTESFLOW_SECRET changes the value for new proofs only.

Roles and groups from the provider ​

Each connection can name the claim that lists the person's groups (groups by default; Entra often uses roles), and map provider groups, in order, to a role here and/or a Notesflow group. At every sign-in through the connection:

  • the first matching mapping decides the role, and none matching gives the connection's default role — so leaving notes-admins at the provider stops being an admin here at the next sign-in;
  • mapped groups follow the provider: in if a matching group says so, out otherwise. Groups no mapping names are the workspace's own and are never touched;
  • the last admin is never demoted this way; the demotion is skipped and logged;
  • a token with no group claim at all changes nothing, which is different from an empty list.

Changes apply from each person's next sign-in and are written to the audit log.

Directory sync (SCIM) ​

Okta, Entra ID or any SCIM 2.0 directory can keep the member list in step. Under Directory sync in the console (manage_members), Make a token — shown once — and give the directory it and the SCIM endpoint shown there. The token names the workspace.

  • A person the directory adds becomes an invitation, at the workspace's default role, which their own first sign-in — by any road — spends. The directory never makes a membership itself, and no mail is sent; the company tells people where to sign in.
  • A person it deactivates or deletes is removed exactly as the console's Remove would: membership, groups, keys and open pages. The last admin is refused.
  • Directory groups are Notesflow groups, shareable like any other. Membership waits for people who have not signed in yet and applies when they do.
  • Invitations the directory has made count against the workspace's member limit.

Filters, PATCH shapes and errors follow what Okta and Entra actually send. Bulk operations, sorting and ETags are not supported.

The workspace's sign-in rules ​

Three switches in the console's SSO section, behind manage_sso:

  • Members must sign in through single sign-on
  • Members must use two-step sign-in — the workspace's own SSO counts as two-step
  • Members may not sign in with a password

The second and third suit a company with no identity provider. A member whose session does not meet a rule is shown which one, and for two-step, Settings opens over it: turning two-step on there lets them in at once. None of them can be switched on by an admin whose own session would fail it.

Requiring SSO ​

Turn on Members must sign in through single sign-on in the console's SSO section and a member reaches this workspace only on a session made through one of this workspace's enabled connections. Another workspace's SSO does not count: it says nothing about whether this company still employs them.

Why it matters: a password or an emailed link outlives the directory account a company closes when somebody leaves. With the requirement on, a member signed in any other way reaches their own Settings and nothing else here, is shown which connection to sign in through, and any pages they already have open close the moment it is turned on.

  • Not affected: visitors (somebody shared one page is not the company's to govern), an operator's break-glass access, and API keys — review those when somebody leaves; removing the member revokes theirs.
  • You cannot lock yourself out. Turning it on needs an enabled connection and that you signed in through one, and while it is on, the last enabled connection cannot be disabled or deleted.

Refusing passwords for everybody at a claimed domain — personal accounts included — is not built. It was first declined because claims were unverified; now that domains can be proven, it waits on a decision about whose choice that is.

Client secrets are sealed at rest ​

AES-256-GCM, keyed from the server secret, and never returned by any route.

A session id opens this application; a client secret opens an account at a provider this deployment does not control, and a leaked backup holding one is somebody else's incident.

Rotating NOTESFLOW_SECRET breaks existing connections

The sealing key is derived from it, so rotating it makes stored client secrets unreadable and the connections have to be set up again. It also makes every two-step sign-in secret unreadable; see authentication. It fails loudly, with the fix in the message — but plan for it rather than discovering it.

In a package ​

On a deployment that sells packages, SSO, directory sync and the sign-in rules are features a package may leave out. A lapse never locks anybody out: rules already on stay on, and require SSO yields rather than shutting members out.

Not built ​

SAML — OIDC was chosen; reopening it is on the wish list. Also re-checking proven domains on a schedule, and SCIM's roles attribute, bulk, sorting and ETags.

Blocks and the op log are canonical. Markdown is a projection. Git is a target.