Single sign-on (SSO)

This page is for administrators. Single sign-on lets your staff sign in to TaskFlow with their corporate identity, over OIDC or SAML 2.0. Any compliant provider works — cloud-hosted or running inside your own network (Keycloak, ADFS or Microsoft Entra ID, for instance) — and you can have several at once, including ones on different protocols.

Licensed separately

Single sign-on isn't part of the base package: it has to be permitted by your instance's configuration. If there's no Administration → Single sign-on section, start there — see Features & settings.

What signing in looks like

The sign-in screen gains a "Sign in with …" button for each enabled provider. The person is taken to the provider, and comes back signed in to TaskFlow.

On first sign-in the account is created automatically (you can forbid this, see below): the name and email come from the provider, and the role from group mapping if you configured one. Such an account takes a licensed seat exactly like one created by hand, and the seat limit applies to it.

Accounts created by a provider have no TaskFlow password — password sign-in is impossible for them until the person sets one through "Forgot password".

Three switches

A button appears on the sign-in screen only when all three conditions are met. That's deliberate, so the feature can't switch itself on:

1. the feature is permitted by the instance configuration and enabled under Administration → Plugins;
2. the Single sign-on configuration module is on under Administration → Settings. While it is off there are no buttons, however the providers are configured;
3. the provider itself is filled in and enabled under Administration → Single sign-on.

Setting up a provider

Open Administration → Single sign-on and add a provider. It needs an ID — lowercase latin letters, digits and hyphens, up to 32 characters: it goes into the sign-in URL and cannot be changed later, only removed and created again. The Protocol field selects OIDC or SAML 2.0; the name, allowed domains, groups → roles and icon are shared by both.

OIDC

The page shows your instance's redirect URI — put it into the application on the provider side, character for character.

OIDC provider fields:

Field	What it sets
Provider	The display name — it becomes the text of the "Sign in with …" button.
Issuer	The provider's base address that serves the OIDC description. Everything else — endpoints and keys — is discovered from there.
Client ID / Client secret	Credentials of the application registered on the provider side. The secret is never handed back out: the interface only shows whether it is set.
Scopes	At least openid email profile. Add groups if the provider sends groups and you want role mapping.
Allowed domains	A comma-separated list of email domains. Empty means no restriction.
Extra authorize parameters	Parameters your provider accepts beyond standard OIDC. Standard protocol parameters cannot be overridden.
Groups → roles	Maps provider groups to global roles. Order sets priority; no match means the default role (member). Applied when the account is created.
Trust email without email_verified	For your own provider, which doesn't report whether an address is verified.
Icon (URL)	The image on the sign-in button.

SAML 2.0

Sign-in always starts on the TaskFlow side: a request goes to the provider and the response comes back to the assertion consumer address. Sign-in started from the provider's portal (IdP-initiated) is not accepted.

1. Provider (IdP) metadata. Upload the provider's metadata file, or enter its URL (https only) and press Load from URL. It supplies the provider's entityID, sign-in address and signing certificates — provider responses are verified with those alone. There is no auto-refresh: if the provider rotates its certificate, load the metadata again. Certificate expiry dates are shown alongside.
2. Our side (SP) — give this to the IdP administrator. It shows the SP entityID (Audience) and the ACS URL (HTTP-POST), both of the form https://<your-host>/auth/sso/saml/<ID>…. The simplest route is Download SP metadata and hand the whole file to the provider's administrator.
3. Sign AuthnRequest — on by default and recommended. The signing key is created automatically for 10 years and never leaves the server; turn it off only if the provider rejects signed requests.
4. Response attributes — the names of the email, name and groups attributes. Empty means the standard names (mail/email, displayName/cn, groups/memberOf and their ADFS and Entra ID variants). A NameID of emailAddress format works as email too.
5. Treat email as verified — SAML carries no "address verified" flag. Turn it on for your own provider, otherwise the sign-in won't link to an existing local account with the same address.

A persistent NameID is required

The provider must send a persistent user identifier (persistent, emailAddress or unspecified). A temporary one (transient) changes on every sign-in — a returning employee would look like a new person — so such a sign-in is rejected with a message about a temporary identifier.

A provider (its entityID) can be connected once: a second connection to the same provider cannot be saved.

Checking

Changes are picked up within about ten seconds. Check queries the provider and reports whether it answers and whether the settings add up; for SAML it looks at the metadata, certificate expiry and the request signing key.

Allowed domains with a public provider

With a public provider, leaving Allowed domains empty means any account of that provider can sign in — and, with automatic creation on, get an account here. Restrict the domains.

Your own provider with a self-signed certificate

Such a certificate isn't accepted by default and sign-in fails with a TLS error. The root certificate has to be added to the instance at deploy time — see Configuration → Single sign-on.

Linking and automatic creation

Two options decide what happens to someone signing in for the first time. They have no interface yet — they are changed on the installation side, in the configuration of the single sign-on module; both are on by default:

• Link by email address (on by default) — if a local account with that address already exists, the sign-in is attached to it. This works only for an address the provider states as verified: otherwise an unverified address in someone else's directory would unlock an existing account.
• Automatic creation (on by default) — create an account on first sign-in. Turn it off if your user list must be maintained by hand: only people who already have an account will get in.

Break-glass access

Don't disable password sign-in ahead of time

First confirm that at least one administrator has actually signed in through the provider. Disabling passwords before that risks locking everyone out of the instance.

If access is lost anyway — the provider is down, its application was revoked — there are two routes, and neither depends on it:

• the installation's owner token: it grants administrative access to the API without signing in to the interface, which is enough to restore password sign-in. See Configuration → The owner token;
• "Forgot password" — whoever owns the mailbox can still reset a password, even for an account the provider created.

When sign-in fails

The person is returned to the sign-in screen with a message. Typical causes:

What the user sees	Where to look
The sign-in timed out	More than ten minutes passed between pressing the provider button and coming back, or the same link was reused (it is single-use) — just start again.
The provider rejected the sign-in	A refusal on the provider side: the person cancelled, or the application isn't approved.
The provider is unavailable	The plugin isn't running, the provider doesn't answer, or the issuer is wrong. With the feature switched off there is no error — the sign-in screen simply has no buttons.
The address is taken by a local account	Linking by address is off, or the provider didn't mark the address verified. Enable linking and make sure the address arrives verified (for your own provider — "Trust email without email_verified", for SAML — "Treat email as verified"), or free up the address: there is no manual account linking in the interface.
The address belongs to a portal customer	Staff and Service Desk customers are separate worlds — a different address is needed.
The provider didn't send an email address	The application on the provider side doesn't grant the required scopes (OIDC), or no email attribute is configured (SAML).
The provider sent a temporary identifier	SAML: the provider is set to a transient NameID — a persistent one is needed.
Automatic creation is off	Create the account in advance, or turn automatic creation on.
The account is disabled	Sign-in for this account was disabled by an administrator — see Users & permissions.
The user limit was reached	No licensed seats left — see Users & permissions.
Adding users is suspended	The instance has an outstanding payment — new accounts aren't created until it is settled.

Where to go next

• Users & permissions — roles, seats and sign-in control.
• Features & settings — enabling features.
• Configuration — provider secrets and certificates.

See also

• Profile & security → Signing in through your organisation's provider — what this looks like for an employee.
• Plugins → The permitted set of features — why the section may be missing altogether.
• Getting started — the sign-in screen with provider buttons.