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. Any OIDC-compliant provider works — cloud-hosted or running inside your own network — and you can have several at once.
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:
- the feature is permitted by the instance configuration and enabled under Administration → Plugins;
- the Single sign-on configuration module is on under Administration → Settings. While it is off there are no buttons, however the providers are configured;
- 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 same page shows your instance's redirect URI — put it into the application on the provider side, character for character.
The fields are the same for any provider:
| 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. |
Changes are picked up within about ten seconds. Check queries the provider and reports whether it answers and whether the settings add up.
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"), 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. |
| 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.