Skip to main content

Single sign-on

Each tenant can connect one identity provider (IdP) that speaks OpenID Connect — Microsoft Entra ID, Okta, Keycloak and the like. Its staff then sign in with their company account instead of a separate A2Flow password. The first sign-in creates the A2Flow account, and the IdP's groups decide which user groups — and so which roles — the person holds.

Passwords keep working alongside single sign-on. Super Admin accounts belong to no tenant and always sign in with a password.

How it works​

Before you start​

  • You need the admin role in the tenant.
  • An operator must have set the deployment's base URL when deploying — see Server settings. While it is not set, Admin Settings shows a warning in place of the Redirect URI and single sign-on stays unavailable.
  • Your IdP must be reachable from A2Flow on a public address. An IdP on a private network works only after the operator has allowed its host — see Single sign-on in the configuration reference.

To try single sign-on without an IdP of your own, start the Keycloak that comes with the Docker Compose stack — see Try single sign-on with Keycloak.

Set it up​

  1. At your IdP, register a new application for A2Flow — a web application with a client secret. Note its issuer URL, client ID and client secret.
  2. In A2Flow, open Admin Settings in the admin sidebar and find the Single sign-on section. Press Copy next to Redirect URI and register that address as the redirect URI of the application at your IdP. If your users open A2Flow at your tenant's own address, register Redirect URI (tenant address) too.
  3. At your IdP, make the application's ID token carry the list of groups each person belongs to (the groups claim). Forgetting this strips roles — see Things to know.
  4. Fill in the section, using the table below, and tick Enable single sign-on.
  5. Save. Saving checks that the issuer URL is an allowed address — https, or a host the operator has allowed — and, when Enable single sign-on is ticked, that the issuer URL, client ID and client secret are filled in. It does not contact the IdP, so the real test is the next step.
  6. On each user group that should follow an IdP group, open User Groups, open the group and fill in IdP group — see Groups and roles.
  7. Try it: open the sign-in screen, enter the tenant name and press Sign in with SSO.
FieldNotes
Enable single sign-onThe switch. Turning it on requires the issuer URL, client ID and client secret.
Issuer URLThe OpenID Connect issuer of your IdP, such as https://idp.example.com.
Client IDThe application's client ID at your IdP.
Client secretWrite-only: it is never shown back. Once saved, the field reads "Saved — leave empty to keep it".
Groups claimThe name of the ID token claim that lists a person's groups. groups unless your IdP uses another name.
Trust e-mail addresses from this IdPOff by default. Lets A2Flow link an existing account by e-mail address even when the IdP does not mark the address as verified. Microsoft Entra ID needs it.
Redirect URIRead-only. The address to register at your IdP; every tenant uses the same one.
Redirect URI (tenant address)Read-only. Where a sign-in started at your tenant's own address returns to — see At your tenant's address. Register it too if your users open A2Flow there. Not shown when the deployment's address is an IP address.

Signing in​

On the sign-in screen, enter the tenant name in Tenant and press Sign in with SSO. The button stays disabled while Tenant is empty. You are sent to your IdP, sign in there, and come back signed in to A2Flow. Signing in with a username and password works as before.

Signing out of A2Flow does not sign you out of the IdP, so pressing Sign in with SSO again may take you straight back in.

At your tenant's address​

Each tenant can also be opened at its own address — the tenant name in front of the usual address, such as acme.a2flow.example.com — once the operator has set up DNS and a certificate for it. The sign-in screen there has no Tenant field:

Your tenantWhat happens
Single sign-on is onYou are sent straight to your IdP, without seeing the sign-in screen.
Single sign-on is offThe screen asks only for Username and Password.

When you sign out, A2Flow shows a page confirming it, with Sign in again to return to the sign-in screen. With single sign-on on, that takes you to your IdP, which may sign you straight back in.

When a single sign-on attempt fails, you are not sent to the IdP again. The screen shows Sign in with SSO instead, and Sign in with password reveals Username and Password for an account that has a password. You can also sign in with a password at the usual address, entering the tenant name in Tenant.

To sign in with a password without being sent to the IdP — for an account that has no IdP identity — add ?local to the sign-in screen's address, such as https://acme.a2flow.example.com/login?local. The screen then opens with Username and Password shown.

Sign-in error messages​

A failed attempt returns you to the sign-in screen with one of these messages.

MessageWhat it means and what to do
Single sign-on is not available for this tenant.The tenant name is wrong, the tenant is disabled, or its single sign-on is not set up or not switched on. A2Flow deliberately does not say which, so the message cannot be used to find out which tenants exist. Check the name, then ask your tenant admin.
Single sign-on failed. Please try again.The exchange with the IdP did not complete, or the IdP sent no e-mail address or one that is not a usable address, or two accounts in the tenant share your e-mail address, or an account with your e-mail address is already linked to a different IdP identity, or the IdP's e-mail address is not trusted and an A2Flow account with that address already exists. In the last case ask your tenant admin to turn on Trust e-mail addresses from this IdP, or to change the e-mail address of one of the two accounts. Otherwise try again; if it keeps failing, ask your tenant admin to check the settings and the application registered at the IdP.
Your account is disabled.Your A2Flow account or your whole tenant is disabled, or the account was deleted. An admin can switch the account on again with Enabled.
Your identity provider account is not allowed to sign in to A2Flow.You have no A2Flow account yet and belong to no IdP group that a user group is mapped to — or the IdP left your group list out because you belong to very many groups. Ask the IdP's administrator to add you to a mapped group.

How people are matched to accounts​

At every sign-in A2Flow looks for the account in this order:

  1. An account already linked to this IdP identity is used.
  2. An existing account with the same e-mail address is linked, once. The address is compared without regard to case, and is accepted only when the IdP marks it as verified or Trust e-mail addresses from this IdP is on. Exactly one unlinked account must match; if two or more do, the sign-in fails.
  3. Otherwise a new account is created, but only for a person who belongs to at least one IdP group that a user group is mapped to. Anyone else is refused. A new account is never created for an e-mail address that an account in the tenant already has, nor when the IdP's e-mail address is not a usable address; the sign-in fails instead.

A new account takes its username from the IdP's preferred username, else from the part of the e-mail address before the @. Characters other than letters, digits, ., _ and - are dropped, the name falls back to user when too little is left, and -2, -3 and so on are added when the name is taken. The first and last name come from the IdP. The account has no direct roles and no password: its roles come from its groups, and an admin can set a password later as a fallback.

The names and e-mail address of an existing account are never overwritten from the IdP.

Groups and roles​

On each user group, IdP group holds the value that the IdP's groups claim lists for that group. Microsoft Entra ID sends the group's object id, not its name, so enter that id. The match is exact and case-sensitive.

At every SSO sign-in, for each user group that has an IdP group:

  • the person joins the group when the claim contains the value, and
  • leaves it when the claim does not.

User groups with no IdP group, and roles granted directly on an account, are never touched. Group changes made at the IdP take effect at the person's next SSO sign-in, not at once.

The members of a group with an IdP group are managed by the IdP and cannot be edited by hand. On the group's page the Members list is read-only and says "Managed by your IdP", and such a group cannot be added to or removed from a user's Groups either. If you fill in IdP group on a group that already has members, they stay until each one's next SSO sign-in.

Things to know​

SituationWhat happens
The IdP sends no groups claim, or the Groups claim name does not matchEvery person who signs in is removed from every mapped group and loses the roles those groups gave. Check the claim at the IdP before enabling single sign-on.
Microsoft Entra IDIt sends group object ids, not names. For a person in very many groups it leaves the list out. A2Flow then keeps that person's current memberships and cannot create a new account for them.
You change Issuer URL or Client IDEvery account in the tenant is unlinked from its IdP identity, because the IdP issues different identities for a different application. People are linked again by e-mail address at their next sign-in, which needs a trusted address (marked verified by the IdP, or Trust e-mail addresses from this IdP on). Otherwise the sign-in fails, because the old account still has that address.
Someone is removed at the IdPThey can no longer sign in through SSO, but A2Flow does not disable their account. Clear Enabled on it to block password sign-in too.
An account carries the SSO badgeIt has signed in through single sign-on. The badge appears in the Users list and on the account's detail page.
Your users open A2Flow at your tenant's own addressA single sign-on started there returns there, through Redirect URI (tenant address). Until that address is registered at your IdP, the IdP refuses the sign-in.