Single sign-on
With single sign-on, people type their work e-mail on the login page and continue at your company’s identity provider — Keycloak, Okta, Microsoft Entra ID, Google Workspace, Authentik or any OpenID Connect or SAML 2.0 provider. The provider says who they are and which groups they are in; Waiso turns those groups into access at every sign-in.
- Connect a provider and prove it with a test sign-in
- Connect a SAML 2.0 provider from its metadata
- Route your company domains to it
- Map provider groups to admin or per-area access
- Turn on SSO only and keep break-glass accounts
How it works
An administrator connects the provider under Settings → SSO and claims the company’s e-mail domains. From then on, typing an address at one of those domains on the login page shows Continue with and the provider’s name. The person signs in at the provider and comes back signed in to Waiso — two actions after the e-mail.
Connect your provider (Keycloak)
- Start the wizard
Open Settings → SSO and press Connect your identity provider. Choose Keycloak.
- Create the client in Keycloak
In your realm create an OpenID Connect client (for example
waiso) with Client authentication on, and paste the redirect URI the wizard shows. Add a Group Membership mapper with the claim namegroups. - Paste what Keycloak gave you
The issuer (
https://<host>/realms/<realm>), the client ID and the client secret. The secret is stored encrypted and never shown again — editing later says Secret set with a Replace button. - Run a test sign-in
Press Run a test sign-in and sign in at Keycloak in the window that opens. The result lists the e-mail, name, subject and groups that came back — or names the problem (wrong secret, wrong issuer, clock out of step, bad signature). Nothing is on yet.
- Turn it on
Turn on is enabled only after a test passed since the last change to the issuer, client or secret.
Connect a SAML 2.0 provider
Prefer SAML? The wizard has a SAML 2.0 group with the same providers and an Other SAML card. Everything after the sign-in — domains, the first sign-in, groups, SSO only and the sign-ins list — works exactly as for OpenID Connect.
- Copy three values into your provider
The Copy step shows the Entity ID, the ACS URL and the Metadata URL, each with a copy button. Most providers take the Entity ID and the ACS URL; some can import the metadata URL instead.
- Give Waiso your provider’s metadata
Paste its metadata URL (read again every day, so a new certificate is picked up on its own) or the metadata file’s contents. Waiso reads the sign-in address and the signing certificates from it.
- Send the e-mail and the groups
Have the provider send an
emailattribute and the person’s groups in agroupsattribute (Microsoft Entra ID and Authentik use their own attribute names, which the presets fill in). Sign the assertion or the response with RSA-SHA256, without encryption. - Test, then turn it on
The test sign-in shows the e-mail, the subject and the attributes that came back — or names the problem, such as a wrong ACS URL, an expired response or a signature that does not match the certificate.
Sign-in from the provider’s app dashboard
By default a sign-in must start on the Waiso login page. If your people open Waiso from the app tile in Okta, Microsoft Entra ID (My Apps) or Keycloak, turn on Allow sign-in from the provider’s app dashboard on the Paste step. It is off by default and per provider.
- Every other check still applies: the signature against the stored certificate, the audience, the ACS URL, the issuer — with a tighter clock window (one minute) and an assertion issued in the last five minutes.
- Each sign-in works once: the same assertion sent again is refused.
- People land on Waiso’s home. A default RelayState is followed only when it is a path of this site, such as
/projects; any full address is ignored. - In Keycloak, set the client’s IDP-Initiated SSO URL name (for example
waiso); the tile is then/realms/<realm>/protocol/saml/clients/waiso. Okta and Entra ID add the tile when the app is assigned.
Company domains
Add the domains your people’s addresses end in. On the cloud a domain must be proven: add the TXT record the page shows (_waiso-verify.<domain>) at your DNS host and press Check now — only a verified domain routes sign-ins. On a self-hosted installation a domain is verified when you save it. Public mail domains such as gmail.com are refused, and a domain belongs to one provider.
The first sign-in
- Create the account — anyone your provider lets in gets an account on their first sign-in, with the default access you choose.
- Invited only — only people you invited or added get in; anyone else is told to ask an administrator.
- An existing account with the same address is linked to the provider the first time, when the provider confirms the address. After that the provider’s stable subject id finds the person, even if their e-mail changes.
Groups decide access
Map each provider group to Admin or to levels per area, for all projects or one. At every sign-in the person’s groups are read again: the highest level per area wins, and when groups disagree on the project the first group in your order wins. A person with at least one mapped group gets exactly that access — the Users tab shows Managed by and the provider’s name, and hand edits are locked. A person in no mapped group keeps the access set in Waiso.
| Provider | Where the groups come from |
|---|---|
| Keycloak | A Group Membership mapper (claim groups) |
| Okta | The groups scope and a groups claim |
| Microsoft Entra ID | A groups claim with object IDs — map the IDs |
| Authentik | The profile scope carries groups |
| Google Workspace | None: everyone gets the default access |
SSO only
Turn on Only company sign-in for these domains and password sign-in and password reset stop for those addresses: the login page shows only Continue with. The workspace owner always keeps a password, and so do up to two admins you choose — for the day the provider is down, when one of them signs in with a password and turns SSO off.
Sign-ins
Every company sign-in and every refusal is listed at the bottom of the SSO page for 90 days: when (to the second), who, the outcome and, for a refusal, the reason in words.