bablsoft/accessflow Quick start Get AccessFlow
Guides

Connect single sign-on.

Last updated

What you are building

Sign-in through your existing identity provider, so AccessFlow stops being another password to manage and offboarding somebody in one place actually removes their access. There are three pieces, and you do not need all of them:

  • OAuth 2.0 / OIDC — the simplest path, with ready-made templates for Google, GitHub, Microsoft and GitLab, and a generic option for anything else.
  • SAML 2.0 — for enterprise identity providers that expect it.
  • SCIM 2.0 — provisioning, so accounts are created and deactivated by the identity provider rather than by hand.

Should I use OAuth, SAML or SCIM for AccessFlow single sign-on?

If your provider speaks both, prefer OAuth 2.0 / OIDC — the setup is one redirect URL and a client secret. Reach for SAML when that is what your identity team supports. Add SCIM on top of either once you care about accounts disappearing automatically when somebody leaves.

Everything here hangs off one setting. The redirect and endpoint URLs your provider needs point at the backend, and AccessFlow builds them from the API base URL the frontend is configured with. Get that wrong and the URLs you copy will be wrong too. Each screen shows you the exact string to register — copy it from there rather than assembling it yourself.

1. OAuth 2.0 / OIDC

Admin section → OAuth providers. Each provider is a tab: Google, GitHub, Microsoft, GitLab, GitHub Enterprise, GitLab (self-managed), and OpenID Connect for everything else — Keycloak, Auth0, Okta, Authentik, Zitadel and the rest.

  1. Copy the redirect URI first. The page shows it read-only with a copy button, labelled Redirect URI to register with the provider. Paste that exact string into your provider's console — AccessFlow accepts the callback at that path and no other.
  2. Create the application in your identity provider and collect its client id and secret.
  3. Fill in AccessFlow. Client ID and Client secret, then set Default role for new users, and switch Active on.

Two provider-specific fields appear where they apply. Microsoft asks for a Tenant ID — common for any Microsoft account, organizations for any work or school account, or a specific tenant. The two self-hosted templates require a Server base URL: the origin of your instance, with no path and no query string.

Using the generic OpenID Connect tab? It asks for five URLs — authorization, token, UserInfo, JWK set and issuer — all required, plus a display name for the sign-in button. The four claim-name fields underneath are optional and fall back to the standard OIDC claims. Unlike the named templates, whose endpoints are compiled in and cannot be repointed, these URLs are yours to set, so check them carefully.

Restrict who can get in. Allowed email domains accepts a list matched case-insensitively against the email domain; empty means any domain is accepted, which on a public provider like Google means anyone with an account. On GitHub and GitLab, Allowed organizations restricts sign-in to members of named organizations — on GitHub that needs the read:org scope, and the page warns you when you set a list without it.

New users arrive as Analyst, not read-only. That is the default in every one of the three SSO paths, and an analyst can submit writes. Set Default role for new users to Read-only if you would rather grant upwards deliberately. Bear in mind a role grants no database access on its own — see granting datasource access.

The client secret is encrypted at rest and never returned; the form shows a mask, and leaving it untouched keeps the stored value.

2. SAML 2.0

Admin section → SAML / SSO. The form has three parts: what your identity provider is, what AccessFlow calls itself, and how attributes map onto users.

Both identity-provider fields are required, not alternatives. IdP metadata URL and Signing certificate (PEM) must both be filled in. If either is blank, SAML stays switched off — it logs a warning and declines to build the configuration rather than failing loudly at sign-in, so a half-filled form looks saved but does nothing.

Under Service provider, set ACS URL explicitly to your backend origin followed by /api/v1/auth/saml/acs/default. That is the path AccessFlow actually processes assertions on, and the same URL you register with your identity provider as the assertion consumer service.

Most identity providers would rather import metadata than have you type fields. Point yours at your backend origin followed by /api/v1/auth/saml/metadata/default.

Under Attribute mapping, Email attribute and Display-name attribute are required and default to email and displayName. Role attribute is optional: set it and AccessFlow reads the user's role from that assertion attribute, falling back to the default role when it is missing or unrecognised.

The signing certificate you paste is encrypted at rest and masked on read. AccessFlow signs its own requests with a keypair it generates and stores on first use, unless you pin one with ACCESSFLOW_SAML_SP_SIGNING_KEY_PEM and ACCESSFLOW_SAML_SP_SIGNING_CERT_PEM. Configuration changes take effect immediately — there is no restart, and no metadata refresh cycle to wait for.

Single logout is not implemented. The SLO URL field stores what you type and nothing consumes it. Signing out of AccessFlow ends the AccessFlow session only.

3. SCIM provisioning

Admin section → SCIM Provisioning. This is the piece that makes offboarding real: your identity provider creates, updates and deactivates AccessFlow accounts as people join and leave.

  1. Switch it on and copy the Base URL the page shows — your backend origin followed by /scim/v2. That is what your identity provider asks for.
  2. Create a token. Under Bearer tokens, choose Create token and name it after the system that will use it. The raw af_scim_… value is shown once and never again — paste it into your provider immediately. Only a hash is stored, and the list shows a short prefix so you can tell tokens apart.
  3. Map the attributes. Choose which SCIM attribute carries the email and which carries the display name, and set the role provisioned users get.

Tokens are scoped to your organization, and revoking one cuts that identity provider off immediately.

What deactivation actually does. When your identity provider marks someone inactive, AccessFlow disables the account, revokes every one of its sessions straight away, and revokes each active just-in-time access grant it holds. Standing grants an admin created by hand are not removed — remove those explicitly.

If sign-in does not work

  • The provider rejects the redirect. The registered URL does not match the one AccessFlow expects, character for character. Re-copy it from the OAuth providers page rather than retyping.
  • Sign-in succeeds, then the app rejects it. Read the error code on the callback screen. It distinguishes a missing email claim, an unverified email, a domain or organization that is not on the allow-list, an address that already exists as a local account, and a disabled account.
  • SAML appears configured but nothing happens. Almost always one of the two required identity-provider fields is blank. Fill in both.
  • Browser errors about origins. Check CORS_ALLOWED_ORIGIN: AccessFlow allows exactly one frontend origin, and the post-sign-in redirect targets are derived from it.

Provider-by-provider walkthroughs, the full field reference and the error-code list: Auth & SSO.