Guide

Single sign-on

Let people sign in to the workspace with your company's own identity provider, by SAML or OpenID Connect, give them roles from what it says about them, and require it for everyone.

5 min read

Ways to sign inCopy link to this section

  • Sign in with Google, Microsoft or Okta buttons are switched on for the whole workspace by whoever runs it. They do not appear on the administrator's pages and need nothing from you.
  • Your company's own identity provider, by SAML or OpenID Connect (OIDC), is registered by an administrator in Admin › Identity providers. Somebody types their work email on the sign-in page and its domain sends them to your provider. Microsoft Entra ID, Okta and Google Workspace can all be registered this way, as below.
  • Email and password: each person an administrator adds on Admin › People sets their own password from a one-time link. See Signing in and adding people.

The addresses your provider needsCopy link to this section

Pick the provider's Name first, such as acme-okta: it is part of these addresses. Replace <your-workspace> with your workspace's address and <name> with that name.

WhatAddress
OIDC redirect (sign-in callback) URIhttps://<your-workspace>/api/auth/sso/callback/<name>
SAML reply (ACS) URLhttps://<your-workspace>/api/auth/sso/saml2/sp/acs/<name>
SAML audience (SP entity ID)The exact value you enter as Issuer when you add the provider
SAML service provider metadata, once addedhttps://<your-workspace>/api/auth/sso/saml2/sp/metadata?providerId=<name>
Test sign-in redirect URI (OIDC)https://<your-workspace>/api/admin/identity-provider-tests/callback

Add a providerCopy link to this section

  1. Open Admin › Identity providers and select Add a provider.
  2. Choose SAML or OIDC, and fill in Name, Email domain (separate several with commas) and Issuer.
  3. For SAML, add the Sign-on URL and paste the Metadata XML your provider gives you; it carries the signing certificate. For OIDC, add the Client ID and Client secret; the workspace reads everything else from <Issuer>/.well-known/openid-configuration.
  4. Select Add. The provider appears under Registered, with its protocol, domain, issuer and signing certificate. Providers belong to the workspace, so every administrator sees them. The client secret is stored encrypted.

Microsoft Entra IDCopy link to this section

By OIDC: in the Entra admin center, under App registrations, create a registration with a Web redirect URI set to the OIDC redirect URI above. Create a client secret. In the workspace use the Application (client) ID as Client ID, the secret's value as Client secret, and https://login.microsoftonline.com/<tenant-id>/v2.0 as Issuer.

By SAML: under Enterprise applications, create your own application and choose SAML. Set Identifier (Entity ID) to the value you will enter as Issuer and Reply URL to the SAML reply URL above, then download the Federation Metadata XML and paste it into the workspace with its sign-on URL.

OktaCopy link to this section

By OIDC: in the Okta admin console create an app integration of type OIDC, Web Application, with the OIDC redirect URI above as its sign-in redirect URI. Use its client ID and secret, and your Okta address, such as https://acme.okta.com, as Issuer.

By SAML: create an app integration of type SAML 2.0. Set Single sign-on URL to the SAML reply URL above and Audience URI (SP Entity ID) to the value you will enter as Issuer, then copy the app's IdP metadata into the workspace.

Google WorkspaceCopy link to this section

In the Google Admin console add a custom SAML app under Web and mobile apps. Set ACS URL to the SAML reply URL above and Entity ID to the value you will enter as Issuer, download the IdP metadata, and turn the app on for the people who should use it.

Test before anyone depends on itCopy link to this section

For an OIDC provider, Test sign-in on its row sends you through the provider and back, then shows what it returned: whether the issuer matches, the token was issued for this client, the nonce matches and the token has not expired, and the claims it carried. Nobody is signed in and no account is created. Allow the test redirect URI above at your provider first. Test sign-in is not yet available for SAML providers; sign in once with a test account instead.

Roles from sign-in claimsCopy link to this section

At the foot of the Identity providers page, Roles from sign-in claims reads one claim, groups by default, at every sign-in through a registered provider and gives people a role and groups from its values. Turn on Apply the rules at sign-in, add up to 50 rules (When the claim contains a value, give a Role and Groups), and check them with Try claim values before saving. Values match without regard to case. Administrator beats a custom role, which beats Member, and the rules never lower the last administrator or a role they did not give. A rule that cannot be applied never stops anyone signing in.

Require single sign-onCopy link to this section

  • In Admin › Enterprise controls › Sign-in, turn on Require SSO. From then on only a registered SAML or OIDC provider signs anybody in; the Google, Microsoft and Okta buttons are refused. The sign-in page asks for a work email and offers Continue with your company account.
  • It cannot be turned on until a provider is registered, and changing it asks you to have signed in recently.
  • Saving it ends everyone else's sessions, except people who already signed in through a registered provider and the workspace's emergency administrators.
  • The workspace's emergency administrators can still sign in another way, under Administrator sign-in, so a broken provider never locks everyone out. Every such sign-in is recorded in the audit trail.

Signing certificatesCopy link to this section

Each provider's row shows when its signing certificate expires, read from the SAML metadata or from the OIDC provider's published keys. Administrators are notified 30, 7 and 1 days before it expires and once after, and the row turns amber 30 days ahead and red once it has expired, when sign-in through that provider stops working. To change the certificate, remove the provider and add it again with the new metadata, at a quiet time.

Provisioning from your directoryCopy link to this section

When provisioning is turned on for the workspace, Admin › Enterprise controls shows SCIM provisioning as On with the directory base address, https://<your-workspace>/api/auth/scim/v2. Under Directory tokens, issue a token for Okta, Entra or another directory; it is shown once, up to five can be active, and an old one can overlap a new one for up to a week while you switch. Deactivating someone in the directory ends their sessions, stops their computers and retires the accounts they connected. They still sign in through your provider.

Last updated