on this page

AccountSingle sign-on

Single sign-on

On Company and Enterprise, the people on your account can sign in through your company's identity provider over OpenID Connect. You can also require it, so a password, an email link, Google, GitHub or a passkey stops working for anyone at your domain. It covers the whole account: the Mast web app, Mast Pager, the Tissue Cloud dashboard and ribo login all go through the same sign-in.

Only an owner can set it up. It's under Sign-in and security, in the menu under your address at the top right, in the Single sign-on for this account section.


What you need

  • An owner with a passkey or two-factor sign-in. You can set up the connection without one, but you can't require single sign-on until an owner can still get in when your provider is down.
  • Access to your identity provider's admin console, to make an OpenID Connect web application.
  • Access to your domain's DNS, to publish one TXT record.

SAML isn't offered. Every provider on this page speaks OpenID Connect.


Setting it up

  1. In your provider, make an OpenID Connect web application (sometimes called a confidential client) with the authorization code flow, and give it this redirect URI:

    https://auth.tissue.systems/auth/sso/callback
  2. In Tissue, open Sign-in and security, pick the provider, and fill in the issuer, the client ID and the client secret. Tissue reads the provider's discovery document before it saves anything, so a wrong issuer is refused straight away rather than at someone's first sign-in.

  3. Add your domain and publish the TXT record Tissue shows you at _tissue-challenge.<your domain>. Press check now once it's published. DNS changes can take a few minutes to show up. A domain can be verified by one account only, and public mail domains such as gmail.com can't be claimed.

  4. Press Test the sign-in. You sign in at your provider and Tissue shows what it would do with the answer: the address, the identity, the groups it saw and the role a new member would get. Nothing changes, and the test is in the audit log.

  5. When the test works, people at the verified domain can sign in. On the sign-in page they type their address and go straight to your provider. Your sign-in address, shown on the settings page, goes there directly as well, which is handy as a bookmark or an app tile in your provider's portal.

The client secret is stored encrypted and never shown again. Leave the field empty when you save other changes and the stored one stays.


Who gets in, and with what role

The address in the token has to be at one of the domains you verified. Tissue then finds the person by their identity at your provider. The first time it sees them, it finds them by address instead.

With Add people the first time they sign in on, someone who isn't on the account yet joins it when they first sign in, as long as the plan's headcount has room. They join as developer unless you pick admin. With it off, only people already on the account can sign in through your provider.

To set roles from your provider, put the name of the groups claim (usually groups) in Groups claim and list one group per line in Group roles:

oncall-leads = admin
engineering = developer

Admin wins when someone is in several groups. A group can't make anyone an owner, so ownership only ever changes by hand. A role an owner set by hand is left alone, and a role the groups set follows the groups at each sign-in.

A single sign-on session lasts the hours you set, 24 at most, and only works for this account. Someone who is also on another account signs in to that one the usual way.


Requiring single sign-on

There are two switches.

Require it for addresses at the verified domains. Anyone with an address at one of your domains has to sign in through your provider. Their password, email links, Google, GitHub and passkeys stop working, on this account and on any other account they're on.

Require it for every member of this account. Every member who isn't an owner has to come through your provider to reach this account, including people at other domains. Someone your provider doesn't know can't get in at all, so check the count the settings page shows first.

Owners keep a way in for when your provider is down: a passkey, or a password with a two-factor code. Every sign-in that way is written to the audit log, and every owner on the account gets an email about it. An owner without either is held to single sign-on like everyone else.

Requiring single sign-on doesn't end sessions that already exist. Sign out everyone it covers does: it ends every session and every ribo token of the members the switches cover, on every device. Owners stay signed in.

If the plan stops including single sign-on, nobody can sign in through the connection and nothing is required. The settings stay for when the plan includes it again.

Mast Pager's own link to your account isn't a sign-in, so a phone already linked keeps ringing when you require single sign-on. Remove someone from the account to stop their phone.


Okta

  1. In the Okta admin console, go to Applications, Create App Integration, pick OIDC - OpenID Connect and Web Application.
  2. Under Sign-in redirect URIs, put https://auth.tissue.systems/auth/sso/callback. Leave the grant type at Authorization Code.
  3. Assign the people or groups who should be able to sign in.
  4. The issuer is your Okta domain, such as https://yourcompany.okta.com. If you use a custom authorization server, it's that server's issuer URI instead, such as https://yourcompany.okta.com/oauth2/default.
  5. In Tissue, pick Okta, JumpCloud, Keycloak or another OpenID Connect provider.

For groups, open the application's Sign On tab, edit OpenID Connect ID Token, set Groups claim type to Filter, the claim name to groups, and a filter such as Matches regex .*. Then put groups in Tissue's Groups claim. With a custom authorization server, add a groups claim to the server instead.

Microsoft Entra ID

  1. In the Entra admin center, go to App registrations, New registration. Pick Accounts in this organizational directory only.
  2. Under Redirect URI, pick Web and put https://auth.tissue.systems/auth/sso/callback.
  3. Under Certificates & secrets, make a client secret. Its value is the client secret, and Entra shows it only once. Entra secrets expire, so set a reminder to make a new one before the date it shows.
  4. The issuer is https://login.microsoftonline.com/<tenant id>/v2.0, with your directory (tenant) ID from the app's Overview. Tissue refuses the shared common and organizations endpoints, which would let in every tenant.
  5. In Tissue, pick Microsoft Entra ID.

Tissue identifies people by their object ID in your tenant and checks that every token comes from that tenant. The address comes from the email claim, or from the sign-in name when there's none.

For groups, open Token configuration, Add groups claim, and pick Security groups. Entra sends group object IDs rather than names, so map the IDs:

3f6b7a52-0c1d-4e8a-9b2f-5d7e1a2c4b6d = admin

Entra leaves the groups out of the token for someone in more than about 200 groups. Tissue then sees no groups and leaves that person's role where it is.

Google Workspace

  1. In the Google Cloud console, pick a project in your Workspace organization, then APIs & Services, OAuth consent screen, and set the user type to Internal.
  2. Under Credentials, Create credentials, OAuth client ID, pick Web application and add https://auth.tissue.systems/auth/sso/callback under Authorized redirect URIs.
  3. The issuer is https://accounts.google.com.
  4. In Tissue, pick Google Workspace.

Google uses one issuer for every Google account, so Tissue also checks the hd claim, which says which Workspace vouched for the person, against the address's domain. A personal Gmail account can't get through.

Google doesn't put groups in its tokens. Everyone joins with the default role, and you change roles by hand.

JumpCloud

  1. In the JumpCloud admin portal, go to SSO Applications, Add New Application, Custom Application, and pick Manage Single Sign-On (SSO) with Configure SSO with OIDC.
  2. Put https://auth.tissue.systems/auth/sso/callback under Redirect URIs, pick Client Secret Post as the client authentication type, and set the login URL to your sign-in address from the Tissue settings page.
  3. Under Attribute Mapping, include the email and profile standard scopes. To send groups, turn on Include group attribute and name it groups.
  4. Bind the user groups who should be able to sign in.
  5. The issuer is https://oauth.id.jumpcloud.com/.
  6. In Tissue, pick Okta, JumpCloud, Keycloak or another OpenID Connect provider.

Keycloak

  1. In your realm, go to Clients, Create client, with the client type OpenID Connect.
  2. Turn on Client authentication and leave Standard flow on.
  3. Put https://auth.tissue.systems/auth/sso/callback under Valid redirect URIs.
  4. The client secret is on the client's Credentials tab.
  5. The issuer is https://<your keycloak host>/realms/<realm>. Keycloak has to be reachable from the internet at a public hostname.
  6. In Tissue, pick Okta, JumpCloud, Keycloak or another OpenID Connect provider.

Keycloak only puts email_verified in the token as true when the address is verified in Keycloak, and Tissue refuses a sign-in without it. Mark the addresses verified, or turn on email verification for the realm.

For groups, open the client's dedicated scope, Add mapper, By configuration, Group Membership, with the token claim name groups and Full group path off.


Provisioning with SCIM

Single sign-on lets people in. SCIM lets your identity provider manage who is on the account: it adds people you assign to the application, keeps their names and addresses current, and takes them off the account when you unassign or deactivate them. It comes with single sign-on on Company and Enterprise, and needs the connection set up with at least one verified domain.

Under Provisioning with SCIM on Sign-in and security you'll find the base URL and a Make a token button. The token is shown once, so copy it straight into your provider. Two tokens can be live at once, which lets you move to a new one before you revoke the old. A token only works for this account's connection.

What happens to the people your provider sends:

  • Added. Someone at a verified domain joins as the role New members join as sets, or the role their groups map to, as long as the plan's headcount has room. When it's full, your provider gets an error naming the plan limit and nobody is added. They sign in through your provider, and nobody gets an invite email.
  • Already a member. Someone you added by hand is taken over by your provider and keeps the role they had.
  • Deactivated or unassigned. They leave the account the same way a removal on the members page works: their sessions and ribo tokens end, they come off every on-call rotation, and Mast Pager stops ringing their phone. Signing in through your provider doesn't add them back while your provider has them deactivated.
  • Groups. Push groups and the Group roles map applies to them, by group name or, for Entra, by the group's object ID. A role an owner set by hand is left alone.

Someone your provider manages is changed there, not on the members page, which shows managed by your identity provider next to them and offers no role change or removal. An owner is never removed or demoted over SCIM. Your provider gets an error and the other owners get an email.

If your provider tries to remove more people in ten minutes than about a quarter of those it manages (at least 3, at most 10), Tissue stops removing anyone, and every owner gets an email. Your provider retries on its own. Once you've checked it was meant, press Approve the removals and the next hour of removals goes through.

Removing the single sign-on connection stops its SCIM tokens. Everyone stays on the account, managed on the members page again.

SCIM with Okta

  1. Open the OpenID Connect application you made for single sign-on. On its General tab, edit App Settings and set Provisioning to SCIM.
  2. On the new Provisioning tab, under Integration, put the base URL in SCIM connector base URL and userName in Unique identifier field for users.
  3. Tick Push New Users, Push Profile Updates and Push Groups. Set Authentication Mode to HTTP Header and paste the token as the bearer token. Press Test Connector Configuration, then save.
  4. Under To App, turn on Create Users, Update User Attributes and Deactivate Users.
  5. To set roles from groups, add the groups under Push Groups and map their names in Group roles.

SCIM with Microsoft Entra ID

  1. In the Entra admin center, open Enterprise applications and pick the application with the same name as the app registration you made for single sign-on.
  2. Open Provisioning, and set Provisioning Mode to Automatic.
  3. Under Admin Credentials, put the base URL with ?aadOptscim062020 on the end in Tenant URL, for example https://auth.tissue.systems/scim/v2/ssoc_…?aadOptscim062020, and the token in Secret Token. The suffix turns on the standard SCIM behaviour in Entra. Press Test Connection, then save.
  4. Under Settings, set Scope to Sync only assigned users and groups, and assign people and groups under Users and groups.
  5. Turn Provisioning Status on. Entra runs a cycle every 40 minutes or so, so changes show up then, not straight away.

Entra sends the user principal name as the address by default. If that isn't the address people get mail at, change the userName mapping under Mappings to mail.


When a sign-in fails

Test the sign-in names the reason. The usual ones:

  • The address is not at a domain this connection has verified. The person's address is at a domain you haven't added, or the TXT record isn't verified yet.
  • The code exchange with your provider failed. The client ID or secret is wrong, the secret has expired, or the redirect URI in the provider doesn't match exactly. If your provider asks how the client authenticates, pick the client secret sent in the request body (client_secret_post).
  • The provider did not say the address is verified. Your provider didn't send email_verified as true. See the Keycloak note above.
  • The token came from a different Entra tenant. The issuer names another tenant than the one the person signed in to.
  • Google did not say the address belongs to its Workspace domain. The person signed in with a personal Google account, or one from another Workspace.

Someone held to single sign-on who tries a password sees a message and is taken to your provider. An owner whose provider is down signs in with a passkey, or with a password and a two-factor code.

Every change to the connection, its domains and the switches, every test, every owner sign-in past single sign-on, and every change your provider makes over SCIM is in the account's audit log under Activity.