shiftlabs Start free
Menu Single sign-on

Single sign-on

An Enterprise workspace's admins connect its identity provider, prove its email domain with a DNS record, and can make single sign-on the only way in.

Before you start

Single sign-on comes with Enterprise. Elsewhere, Settings → Single sign-on shows Enterprise only: email sales@shiftlabs.org to ask about it.

  • Who sets it up

    An admin of the workspace, in Settings → Single sign-on. Developers and viewers see the providers and whether single sign-on is enforced, and change nothing.

  • What you need

    An admin account at your identity provider, to add an app for shiftlabs, and access to your domain's DNS, to add a TXT record.

  • One provider per domain

    A provider signs in the people of one email domain, such as acme.com, and of the names below it, such as eu.acme.com. A workspace can have several providers.

Set it up

In Settings → Single sign-on, Add provider takes you through these steps. You can close it after any of them: the provider's Continue setup picks up where you left off.

  1. Protocol and domain

    SAML or OIDC, and the email domain of the people who sign in with it.

  2. Identity provider

    For SAML, the identity provider's metadata: its XML, pasted or as the downloaded file, or its https URL, read once. For OIDC, the issuer, the client ID and the client secret, which is write-only. Add provider saves it.

  3. Service provider details

    What to enter in your identity provider's app: the ACS URL and entity ID for SAML, or the redirect URI for OIDC. See The values.

  4. Domain

    A TXT record for your domain's DNS, then Verify. See Verify the domain.

  5. Test sign-in

    Opens your workspace's single sign-on link in a new tab. Sign in there as someone at the domain.

  6. Enforce single sign-on

    Optional. Makes your identity provider the only way in for the domain's addresses. See Enforce single sign-on.

  • Where your identity provider wants shiftlabs' URLs before it shows its own details, enter https://app.shiftlabs.org/pending there, and replace it with the values of step 3.
  • A provider's identity provider can't be changed afterwards. For another app or IdP, delete the provider and add a new one, with a new TXT record.

The values

Each provider has an id, saml- or oidc- and 12 letters and digits, made when you add it. Its URLs end in the id, here <id>.

textstep 3
# SAML: the ACS URL
https://app.shiftlabs.org/api/auth/sso/saml2/sp/acs/<id>

# SAML: the entity ID, also the address of shiftlabs' SP metadata
https://app.shiftlabs.org/api/auth/sso/saml2/sp/metadata?providerId=<id>

# OIDC: the redirect URI
https://app.shiftlabs.org/api/auth/sso/callback/<id>

# The test sign-in, and the single sign-on page your people can bookmark
https://app.shiftlabs.org/auth/sso?provider=<id>
  • ACS URL

    Okta: Single sign-on URL. Entra ID: Reply URL (Assertion Consumer Service URL). Google Workspace: ACS URL.

  • Entity ID

    Okta: Audience URI (SP Entity ID). Entra ID: Identifier (Entity ID). Google Workspace: Entity ID. Download SP metadata saves the metadata it serves.

  • Redirect URI

    Okta: Sign-in redirect URI. Entra ID: Redirect URI, on the Web platform. Google Cloud: Authorized redirect URI.

  • SAML: an email attribute, or else the Name ID, is the person's address at the domain, and assertions must be signed. givenName and surname attributes, or else displayName, name the person.
  • OIDC: shiftlabs asks for the scopes openid email profile, with PKCE, and sends the client secret as client_secret_basic, or client_secret_post where the identity provider takes only that. The email claim is the person's address at the domain.
  • OIDC: the issuer must match the issuer of its discovery document exactly, trailing slash included, and its endpoints must be https.

Okta

In the Okta Admin Console, under Applications → Applications, choose Create App Integration.

SAML

  • Choose SAML 2.0 and name the app shiftlabs.
  • Single sign-on URL and Audience URI (SP Entity ID): https://app.shiftlabs.org/pending for now. Name ID format: EmailAddress. Application username: Email.
  • Attribute statements, optional: email as user.email, givenName as user.firstName, surname as user.lastName.
  • Finish. On the Sign On tab, copy the Metadata URL, or save the metadata, for step 2.
  • After step 3, edit the SAML settings: the ACS URL as Single sign-on URL, with Use this for Recipient URL and Destination URL, and the entity ID as Audience URI.
  • On the Assignments tab, assign the people or groups who sign in.

OIDC

  • Choose OIDC - OpenID Connect, then Web Application, and name the app shiftlabs.
  • Grant type: Authorization Code. Sign-in redirect URI: https://app.shiftlabs.org/pending for now.
  • On the General tab, Client authentication is Client secret. Copy the Client ID and the secret for step 2.
  • The issuer is your Okta domain, such as https://acme.okta.com.
  • After step 3, replace the sign-in redirect URI with the redirect URI.
  • On the Assignments tab, assign the people or groups who sign in.

Microsoft Entra ID

In the Microsoft Entra admin center.

SAML

  • Under Enterprise applications, choose New application, then Create your own application. Name it shiftlabs and pick Integrate any other application you don't find in the gallery.
  • Under Single sign-on, choose SAML. Under SAML Certificates, copy the App Federation Metadata Url, or download the Federation Metadata XML, for step 2.
  • After step 3, edit Basic SAML Configuration: the entity ID as Identifier (Entity ID), the ACS URL as Reply URL (Assertion Consumer Service URL).
  • Under Attributes & Claims, the Unique User Identifier (Name ID) is user.userprincipalname. Where that isn't each person's email address, make it user.mail.
  • Under Users and groups, assign the people or groups who sign in.

OIDC

  • Under App registrations, choose New registration. Name it shiftlabs, for accounts in this organizational directory only, with the redirect URI https://app.shiftlabs.org/pending on the Web platform for now.
  • Under Certificates & secrets, add a client secret and copy its Value, not its Secret ID. On Overview, copy the Application (client) ID and the Directory (tenant) ID.
  • The issuer is https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0.
  • After step 3, under Authentication, replace the redirect URI with the redirect URI.

Google Workspace

SAML is set up in the Google Admin console, OIDC in the Google Cloud console of your organization.

SAML

  • Under Apps → Web and mobile apps, choose Add app, then Add custom SAML app, and name it shiftlabs.
  • On Google Identity Provider details, download the metadata for step 2, and leave the page open.
  • After step 3, on Service provider details: the ACS URL, the entity ID, Name ID format EMAIL, and Name ID Basic Information › Primary email.
  • Attribute mapping, optional: Primary email to email, First name to givenName, Last name to surname.
  • Under User access, turn the app on for the people who sign in.

OIDC

  • Under APIs & Services → OAuth consent screen, choose the Internal user type.
  • Under Credentials, create an OAuth client ID of type Web application. Copy the client ID and secret for step 2.
  • The issuer is https://accounts.google.com.
  • After step 3, add the redirect URI under Authorized redirect URIs.

Verify the domain

The Domain step shows a TXT record. Add it to your domain's DNS first, then press Verify, which is the one time shiftlabs looks the record up.

  • The record's name is _better-auth-token-<id>.<domain>. Where your DNS host adds the domain itself, enter _better-auth-token-<id>.
  • Its value lasts 7 days from when you add the provider. After that, the step shows a new value to put in the record.
  • DNS can keep the answer to a lookup made before the record existed, often for 30 minutes. When Verify finds no record, it says when to try again. Nothing tries again by itself.
  • Once the domain is verified, anyone with a verified address there who already has a shiftlabs account can sign in to that account through your identity provider. An account whose address isn't verified yet needs a password reset first, which the single sign-on page offers.
  • A first sign-in through the provider makes the person a viewer of the workspace, or gives them the role of their pending invitation.

Enforce single sign-on

Enforcing makes your identity provider the only way in for the addresses at the workspace's verified domains.

  • Password sign-ins, sign-ups, password resets and Google or GitHub sign-ins are refused for those addresses, which are sent to single sign-on instead. An address that isn't verified yet can still be reset, which verifies it.
  • Turning it on ends their password, Google and GitHub sessions at once, in every workspace, with the access those gave MCP clients. Single sign-on sessions stay. Verifying another domain while it's on ends that domain's too.
  • One admin is the break-glass admin, who keeps signing in with a password and an authenticator app while your identity provider is down, as long as they stay an admin. They need both, and a verified address, when you choose them.
  • Choosing another break-glass admin ends those sessions again, the previous break-glass admin's included.
  • Turning it off lets the other sign-ins in again and forgets the break-glass admin.
  • While it's on, the last verified provider can't be deleted.

People and sessions

  • A single sign-on session opens every workspace its person is a member of, as long as the provider's domain stays verified and your workspace Enterprise.
  • Deleting a provider ends the sessions it made and unlinks the accounts it signed in. Their people stay members.
  • A Google or GitHub sign-in makes no one a member of your workspace. People join through your identity provider or an invitation.
  • Every provider added or deleted, domain verified and change to enforcing is in the workspace's audit log, which admins read.

Reference