Single Sign-On
Enterprise organizations can connect their own identity provider so members sign in with their corporate credentials instead of a personal Google, Microsoft, or LinkedIn account. Both OpenID Connect and SAML 2.0 are supported, and your directory can provision and offboard members through SCIM.
What it is
Single sign-on lets members authenticate against your organization’s own identity provider rather than a social login. It is configured from Organization -> Single Sign-On, and only organization admins can view or change the configuration.
Single sign-on is available on the Enterprise plan. Setting it up requires an Owner or Admin role in the organization.
Domain capture
Before single sign-on can take effect, the organization has to claim an email domain and prove it owns it. Capturing a domain is a two-step process:
- Enter the domain, and the screen shows a DNS TXT record to publish: the record name is
_ruleengine-verification.{domain}, and the value is shown on screen for you to copy. - Publish that record with your DNS provider, then verify. Verification checks the record is present before the domain is marked captured.
Most DNS providers, such as Namecheap and GoDaddy, add your domain to the host name themselves. Enter only _ruleengine-verification as the host: entering the full record name publishes it at _ruleengine-verification.{domain}.{domain}, where verification will not find it. Paste the value exactly as shown, including the ruleengine-verification= at its start.
An unverified domain grants nothing: it does not enable single sign-on and does not affect how members with that email domain sign in. Consumer email domains, such as gmail.com or outlook.com, cannot be claimed.
Once a domain is verified, you can optionally turn on enforcement for it. Enforcing single sign-on refuses Google and Microsoft social sign-in for addresses on that domain, so members on it must use the connected identity provider.
Turning on enforcement before you have confirmed that a real member can sign in end to end through the connected provider can lock every member on that domain out at once, including administrators. Complete a successful sign-in first, then enforce.
Setting up OpenID Connect
You configure an OpenID Connect connection with three values from your provider:
- Issuer URL - the provider’s OpenID Connect issuer.
- Client ID - the identifier the provider issued for this application.
- Client secret - the credential that authenticates the connection.
The screen also shows the redirect (reply) URL to paste into the provider’s app registration, with a copy button next to it.
Once saved, the client secret is never returned by the API or shown again. If you save the configuration later and leave the field blank, the stored secret is kept as is; you only need to fill it in when you are setting or rotating it. While a secret is stored, the Client secret box shows a row of dots, so you can tell one is on file without it ever being sent back to your browser.
Setting up SAML 2.0
The screen shows three values to paste into the identity provider, each with a copy button:
- ACS (reply) URL - where the provider sends its response.
- SP entity ID - identical to the ACS URL by design.
- Metadata URL - a link most providers can import directly instead of entering the other values by hand.
In return, you supply the provider’s own details:
- IdP entity ID
- Sign-on URL
- Signing certificate(s), in PEM or base64 format.
You can add more than one signing certificate. That is what makes it possible to rotate a certificate without downtime: add the new certificate before removing the old one, so there is no window where a response signed with either one is rejected. The screen lists each certificate’s subject, thumbprint, and expiry date, and warns when a certificate is within 30 days of expiring.
Name ID format
The name ID format must be persistent or emailAddress. Transient is refused: a transient identifier changes on every sign-in, so using one would create a new user each time a member signed in rather than recognizing the same person.
Email address
An email address must be present in the response for a sign-in to succeed. Standard attribute names are recognized automatically, covering the ones used by Entra ID / AD FS, Shibboleth, and Okta. If your provider sends the email under a different attribute name, an override field lets you specify it directly.
Allow IdP-initiated sign-in
This setting is off by default. With it off, every sign-in must start from the application: a response that does not answer a request the application actually issued is refused. Turning it on permits the identity provider’s own app-tile style flow, where the member starts from the provider instead of from the sign-in page. Only enable it if members actually use that flow; leaving it off is the stricter and safer default.
How a sign-in works
A member types their work email address on the sign-in page. If that domain has been captured, they are sent to the connected identity provider and, after signing in there, returned to the app already signed in.
The email address the provider returns must land on a domain that this organization has verified. If it does not, the sign-in is refused even though the provider authenticated the person, because nothing ties that identity to this organization.
Troubleshooting
| What you see | Likely cause |
|---|---|
| “The response could not be verified.” | The signing certificate on file is wrong or has changed. Add the current certificate. |
| “The provider refused the request.” | The member’s account is not assigned to the application in the identity provider. |
| “No email address was returned.” | The email attribute is not mapped. Check the attribute name or set the override. |
| The member is signed in as a different user each time. | The name identifier changes on every sign-in. Switch the name ID format off Transient. |
| “This sign-in has already been used” or “does not match a request.” | The response does not correspond to a request the app issued. Start again from the sign-in page rather than reusing a link or a provider app tile. |
Directory provisioning (SCIM)
The Directory provisioning card on the same screen lets your identity provider create, update and offboard members through SCIM 2.0, so removing someone from your directory is what removes their access here. Save your identity provider first: provisioning is set up against it, so no token can be issued until it exists.
- Copy the Tenant URL and paste it into your provider’s provisioning settings as the SCIM endpoint.
- Choose Generate token and copy the token into the same settings. It is shown only once, because only a hash of it is stored. Afterwards the card shows the start of the token and when it was issued.
- Map your directory groups to roles, as described below, and choose Save mappings.
Regenerate token replaces the token, and the old one stops working immediately. Your directory stops provisioning until the new token is pasted into its connector, so regenerate when a token has leaked rather than as routine maintenance.
What provisioning does to your members:
- A person your directory provisions joins the organization with the role their groups map to.
- A person your directory deactivates or deletes is removed from the organization. Their account itself is kept, as it is when an admin removes a member by hand.
- The organization’s owner is never changed or removed by provisioning.
- A group that maps to Admin needs an author seat for each person in it. If the plan has none left, that person is not provisioned, and your directory reports the reason.
Group to role mapping
Each mapping pairs a Directory group name with a role, Admin or Member. A group that is not listed grants nothing, so creating a group in your directory cannot give anyone more access by itself. Someone in more than one mapped group gets the most privileged role, and with no mappings at all, everyone your directory provisions joins as a Member. Owner is never granted by a group. Group names are matched ignoring capitals and extra spaces.
Once your directory has sent at least one group, each mapping shows whether it matched:
| Status | What it means |
|---|---|
| Matched | The mapping matches a group your directory provisioned, shown with the group’s name and how many members it has. |
| No members | The group exists, but nobody your directory has provisioned is in it, so nobody receives the role. Check that the group’s members are assigned to the provisioning app in your directory. |
| No match | No provisioned group has this name, so nobody receives the role. When a close name exists, the card asks Did you mean it, and Use this name fills it in for you. |
Below the mappings, Provisioned groups with no mapping lists every group your directory has sent that no mapping uses, with its member count; their members join as Member. Before the first sync, the card says that no groups have been provisioned yet, rather than marking every mapping as unmatched.
Not supported yet
To set expectations plainly, the following are not yet supported:
- Signed AuthnRequests
- Encrypted assertions
- Single Logout