Toucan AI Docs
Govern

Single Sign-On (SSO)

Target Audience: Professional Services & customer IT administrators

TL;DR

Connect an identity provider (SAML 2.0 or OpenID Connect) to a Toucan organization. Once the email domains are verified in DNS, users sign in with their corporate identity, and Toucan provisions their account automatically, including their user attributes.

How SSO works

Without SSO, a Toucan account has a Toucan password. With SSO, Toucan stops asking for a password and asks your own identity provider instead: the system they already sign in to on a regular basis (e.g Google Workspace, Keycloak, Microsoft 360, Okta, Entra ID, etc.)

One sign-in then looks like this:

  1. The user opens the Toucan sign-in page and is sent to the identity provider.
  2. They authenticate there, under the customer's own rules: password, MFA, whatever the customer enforces. Toucan never sees those credentials.
  3. The identity provider sends them back to Toucan with a signed message saying who they are: an email address, a stable identifier, and any extra values the customer chose to include. Each of those values is a claim.
  4. Toucan checks the signature, then creates or updates the account from those claims.

Two protocols carry that exchange: SAML 2.0, the long-standing enterprise standard, and OpenID Connect (OIDC), the more recent one. Both do the same job here; use whichever the customer's identity provider offers.

Configuring SSO is therefore mostly an exchange of values. Some come from the identity provider and are entered in Toucan; others are generated by Toucan and registered in the identity provider.

When to use it

  • The customer wants employees to reach Toucan with their corporate credentials.
  • The customer wants accounts, and the user attributes that drive Row-Level and Column-Level Security, created and kept in sync from their directory instead of managed by hand.
  • The customer wants to forbid password sign-in for their own email domains.

Core Functionality

  • One connection per organization: an organization has at most one SSO connection. Each customer is a separate organization, so each one gets its own.
  • Two protocols: SAML 2.0 or OpenID Connect. The protocol is chosen at creation and cannot be changed afterwards: switching means deleting and recreating the connection.
  • Domain-scoped: the connection declares the customer's employee email domains (1 to 10). Only identities asserting an address in those domains, or a subdomain of them, are admitted.
  • User provisioning: the first successful sign-in creates the Toucan user, adds them to the organization and synchronizes their mapped attributes. Every later sign-in re-synchronizes them.
  • SSO becomes mandatory for a verified domain: password sign-in and sign-up are refused for those addresses, and no password reset or verification email is sent to them. The reset page points the user to their identity provider instead. Owners always keep password sign-in, and an Owner or Admin can exempt other members as well (see Keeping a password account).

Prerequisites

SideWhat is needed
ToucanAn Admin or Owner role in the organization (ssoConnection permission), and an organization slug: a connection cannot be created without one.
ToucanThe organization's user attributes already created in Settings > User model, if the identity provider should feed them.
CustomerA SAML 2.0 identity provider or a confidential OIDC client (client secret authentication is required).
CustomerAbility to add a TXT record in the DNS of every declared email domain.
CustomerFor OIDC: a publicly reachable HTTPS issuer exposing a standard discovery document. Toucan refuses issuers and endpoints resolving to private addresses.

Configuration flow

Everything happens in Settings > Single sign-on.

The order matters: the values the customer needs to register in their identity provider contain the connection's own identifier, so they only exist once the connection is saved. Create it first, even if some values on the customer side are still provisional.

1. Declare the connection

  1. Choose the protocol supported by the customer's identity provider.
  2. Enter the employee email domains, separated by commas.
  3. Fill in the protocol section, then map the attributes (see Attribute mapping) and save.

SAML 2.0 fields

FieldValue
IdP Entity ID / issuerThe identity provider's entity ID.
IdP SSO URLThe HTTPS single sign-on endpoint.
IdP signing certificateThe public X.509 certificate, PEM format. Toucan rejects an expired or not-yet-valid certificate at save time.
NameID formatPersistent is preferred. Use Unspecified only when the identity provider cannot emit a persistent NameID.

OpenID Connect fields

FieldValue
Issuer URLThe HTTPS issuer. Toucan fetches its discovery document and stores the endpoints itself.
Client IDThe client registered by the customer for Toucan.
Client secretThe client secret. The client must be confidential.
ScopesOptional extras. Toucan always includes openid, email and profile.

Discovery runs at creation and whenever the issuer changes.

2. Give the Toucan values to the customer

Once the connection is saved, the Toucan configuration values card shows what must be registered in the identity provider:

ProtocolToucan valueAlso called, depending on the identity provider
SAMLReply URL (ACS)Assertion Consumer Service URL, Single sign-on URL, Reply URL
SAMLIdentifier (Entity ID) / audienceSP Entity ID, Audience URI, Audience restriction
SAMLSP metadata URLService provider metadata
OIDCRedirect URLRedirect URI, Callback URL, Sign-in redirect URI

The SAML application must also be set to send the authentication request over HTTP-Redirect, the response over HTTP-POST, and to sign the assertion with SHA-256.

These values contain the connection's provider ID. Deleting and recreating a connection changes them, and the identity provider has to be updated accordingly.

3. Verify domain ownership

A connection is only usable once its domains are verified.

  1. Click Generate DNS records.
  2. For each declared domain, give the customer the TXT record name and value shown on the card.
  3. Once the records are published, click Verify DNS records. DNS propagation can take a while; retry if the record is not visible yet.
  4. Keep the records in place for as long as the connection exists.

While the domains are unverified, the connection exists but is not enforced: users of those domains can still sign in with a password. The connection can therefore be prepared well before the customer switches over.

Successful verification is what makes SSO mandatory. From that moment, every account on those domains can only sign in through the identity provider: password and social sign-in are refused, and password reset emails are no longer sent. Admins are not spared: only Owners, and the members explicitly exempted, keep their password.

Deleting the connection requires being signed in, so make sure at least one of those accounts can still get in without the identity provider (see below).

Keeping a password account

Owners are exempt by construction. The organization must keep a way in when the identity provider is unreachable or misconfigured, so the rule never applies to them, and nothing has to be configured for that. A customer who wants the Owner account to belong to the company rather than to a person, under a generic address such as owner@customer.com, is covered as soon as that account is an Owner.

Any other member can be exempted individually: a service account, or an Admin who has to keep working during an identity-provider outage.

  1. Create the account before verifying the domain (sign-up on a verified domain is refused) and give it the role it needs.
  2. Once the connection exists, open the Password sign-in exemptions card in Settings > Single sign-on, select the members (the list is searchable by name and email) and click Save exemptions. Only the members the connection actually constrains are listed: Owners, and addresses outside the declared domains, are not offered. Exemptions can be set before the domains are verified, and changed at any time afterwards.
  3. Verify the domain. Exempted members keep password sign-in and password reset; everyone else on the domain is redirected to the identity provider.

Limit this to one or two break-glass accounts: each exemption is an account that the identity provider's rules (MFA, offboarding) no longer protect. If the identity provider later asserts the same email address, that SSO identity is linked to the existing account, which then accepts both sign-in methods.

Attribute mapping

For each Toucan field, enter the name of the claim that carries its value in the identity provider.

Toucan fieldPurposeTypical claim
Stable external IDImmutable identifier used to recognize the same account at every sign-in.nameID (SAML), sub (OIDC)
Email addressThe address of the Toucan account. It must belong to a declared domain.email
Display nameThe name shown in Toucan. If the claim is missing, Toucan keeps the existing name.displayName, name

Below the core fields, every organization user attribute can be mapped to a claim:

  • A mapped attribute is synchronized from the identity provider at every sign-in and becomes read-only in Toucan: the identity provider is authoritative for it.
  • An attribute left empty stays manually managed in Toucan.
  • Attribute values feed Row-Level and Column-Level Security, so mapping them is what lets the customer's directory drive data access.

If a claim carries a value that does not fit the attribute's type, the whole sign-in fails. Check the attribute types in Settings > User model before mapping.

What user provisioning does

No account has to be created in Toucan beforehand.

At the first successful SSO sign-in, Toucan:

  1. creates the user from the claims it received, with the email already verified and no manual approval step;
  2. adds them to the organization with the Explorer role;
  3. writes the mapped user attributes.

At every later sign-in, Toucan re-synchronizes the display name and the mapped attributes. If the identity provider stops sending a mapped claim, the attribute it fed is cleared.

QuestionAnswer
Which role do provisioned users get?Always Explorer. Promote them afterwards in Settings > Members.
Can a user belong to two organizations?No. An identity already a member of another organization is refused.
How do I remove someone?In Settings > Members. Removing them from the SSO application only blocks their next sign-in.
Are existing password accounts kept?Yes. An existing user whose email matches the connection is linked to the identity provider, and password sign-in stops being allowed for them once the domain is verified, unless they are an Owner or were exempted (see Keeping a password account).

How users sign in

Two entry points, both from the standard sign-in page:

  • Connect with SSO: the user enters the organization identifier (the organization slug) given by their administrator.
  • Their email address: if it belongs to a verified domain, Toucan refuses the password and offers Continue with SSO instead (unless they are an Owner or an exempted member, see Keeping a password account).

Both start the flow from Toucan.

Testing the connection

The Test and manage card runs a real sign-in through the identity provider.

  1. Click Test in a new window (available once the domains are verified).
  2. Open it in a private browser window, so an existing session with the identity provider does not interfere: you want to see the full sign-in, not a silent reuse of a session opened earlier.
  3. Sign in with a user actually assigned to the SSO application in the identity provider.
  4. On success, the page shows the organization, the email and the Toucan role of the resulting session.

The test is a real sign-in: it may create an Explorer in the customer's organization. Use an account the customer expects to see there.

What is not supported

  • Importing IdP metadata XML: the SAML values are entered field by field.
  • Changing the protocol: a SAML connection cannot become an OIDC one. Delete and recreate it, which changes the values registered on the customer side.
  • Single Logout: signing out of Toucan does not sign the user out of the identity provider.
  • Automatic de-provisioning: removing a user from the SSO application blocks their next sign-in, but their Toucan member entry stays until someone removes it.

Troubleshooting

SymptomLikely cause
The certificate is refused at save timeExpired, not yet valid, or not a PEM X.509 certificate.
OIDC discovery failsIssuer not reachable over HTTPS, no discovery document, issuer mismatch inside the document, or endpoints resolving to a private address.
"The OpenID Provider does not support client secret authentication"The client was registered as public. Register a confidential client.
DNS verification never succeedsThe record was published under the wrong name (copy the TXT record name exactly as displayed, domain suffix included), or propagation is not finished yet.
Sign-in rejected right after the identity provider redirects backThe email it asserted is outside the declared domains, or that identity already belongs to another organization.
"Some identity fields can no longer be changed"Users have already signed in through this connection, and their Toucan accounts are bound to the identity it asserts (issuer, client ID or entity ID, endpoints, subject mapping). Changing those values would detach every linked account, so they are frozen. To point the connection elsewhere, delete it and create a new one: users are provisioned again on their next sign-in.
SAML assertions rejected as expired or invalidThe two servers' clocks differ by more than 2 minutes, the assertion is older than 5 minutes, or the identity provider signs with a deprecated algorithm (only RSA-SHA256 and SHA-256 are accepted).
Sign-in works but attributes are emptyThe claim names do not match what the identity provider emits, or the attribute is not mapped.

Deleting a connection

Deleting the connection removes the SSO account links, and users of the domain can sign in with a password again. Toucan users, their memberships and their last known attribute values are kept: those values stop being owned by the identity provider and become editable again.

A replacement connection gets a new provider ID, so its callback URLs and DNS verification record differ from the previous ones and must be re-registered on the customer side.

Manage organization and users

Previous Page

Security model

Next Page

On this page

TL;DRHow SSO worksWhen to use itCore FunctionalityPrerequisitesConfiguration flow1. Declare the connection2. Give the Toucan values to the customer3. Verify domain ownershipKeeping a password accountAttribute mappingWhat user provisioning doesHow users sign inTesting the connectionWhat is not supportedTroubleshootingDeleting a connection