Single sign-on

Let members sign in to the console through your identity provider, over SAML 2.0 or OpenID Connect. You can also create members on their first sign-in, and turn off passwords for your email domains.

Who can do it

Every member can read the page. Saving, testing and turning it on need Manage workspace settings (settings:manage), which only the Owner role holds. Everyone else sees "Changing single sign-on needs the settings:manage permission." and every control is disabled.

Where: Settings › Access › Single sign-on. The header badge reads Not configured, Configured or On.

How sign-in works

A member goes to the sign-in page, chooses Continue with SSO, types their work email, and is sent to your identity provider. The address's domain decides which workspace's provider they reach, so the domain must be listed under Email domains.

Sign-in always starts from Oxelone. A response your identity provider sends without being asked, such as a tile in its app launcher, is refused.

Single sign-on signs in only accounts it created itself. The first sign-in of a new address creates the account, when Create members on first sign-in is on. A person who already has a password account, in this workspace or another, is refused with "An account with this email already exists. Sign in with your password."

Set it up

SAML 2.0

1. Open Settings › Access › Single sign-on and set Protocol to SAML 2.0.
2. Create a SAML app in your identity provider and give it the two values the console shows. Use Copy beside each. The name ID must be the person's email address.
   • ACS URL: where the identity provider sends the signed response.
   • Entity ID: the audience of the SAML app. The console's SAML metadata is at the address in the hint beside Entity ID.
3. Back in the console, paste the identity provider's metadata XML, or its URL, into IdP metadata. A URL must use https. The metadata must name a sign-on URL for the redirect binding and a signing certificate.
4. Under Email domains, add the domains whose addresses should sign in this way, for example acme.com.
5. Choose Test connection. For SAML it checks the signing certificate and answers "The IdP's signing certificate is valid until …".
6. Switch on Sign in with SSO, then choose Save.

Your identity provider must sign the assertion, or the whole response. Encrypted assertions are not supported. The person's email address is read from the name ID, or from an attribute named email, mail or emailaddress.

Step by step for Okta, Microsoft Entra ID and Google Workspace.

OpenID Connect

1. Set Protocol to OpenID Connect.
2. Create a client in your identity provider and register the Redirect URI the console shows as a valid redirect URI.
3. Enter the Issuer URL, the Client ID and the Client secret. The secret is write-only: once saved, the box shows "Stored · …" and its last four characters, and leaving it empty keeps the stored one.
4. Add Email domains, choose Test connection, then switch on Sign in with SSO and choose Save.

The console asks for the scopes openid email profile, uses PKCE, and needs the identity provider to confirm the email address.

Every setting

Before you turn on Require SSO

Require SSO stops passwords for every member of this workspace whose address is on one of your domains, whether or not the password was right. The sign-in page says "This workspace signs in with single sign-on. Use Continue with SSO." People at the same domain who are not members are not affected.

There is no exception for Owners. Platform admins are the only accounts exempt from the rule.

Because single sign-on signs in only accounts it created, a member who already has a password account cannot move to single sign-on. They are refused, and then Require SSO also blocks their password. Before you turn it on, open Members and read the Sign-in column. Every member who must still get in needs to say SSO.

You cannot turn Require SSO on while single sign-on is off. Neither can be turned on until Test connection has passed for the settings as they are now. Changing the issuer, client, secret or certificate means testing again.

When it goes wrong

On the settings page:

• Test the connection before turning single sign-on on. Choose Test connection, then save.
• Turn single sign-on on before requiring it. Switch on Sign in with SSO as well.
• Add at least one email domain before turning single sign-on on. Add a domain.
• … is already used by another workspace. A domain can belong to one workspace. The sentence starts with the domain.
• You can't give new members a role with more access than your own. Choose a lower role.
• Choose the role new members get. Pick one under Role for new members.
• Paste the IdP metadata, or its URL., The IdP metadata isn't valid SAML metadata., The metadata URL must use https. and The metadata URL couldn't be read. Check the metadata.
• The IdP's signing certificate has expired. Download current metadata from your identity provider and paste it.
• Enter the issuer URL and the client ID. Both are needed for OpenID Connect.
• The issuer's discovery document isn't valid OpenID Connect. and The provider says its issuer is …, not …. The issuer must match what the provider publishes, exactly.
• This deployment has no credential encryption key (OXEL_CREDENTIAL_KEY is unset), so a client secret cannot be stored. A secret is never stored unencrypted. Whoever runs your deployment must set the key.

On the sign-in page:

With the API

Not available with an API key. Only an Owner can change single sign-on, in the console.