Set up single sign-on
This guide sets up single sign-on for a workspace from start to finish. The settings are described in Single sign-on.
You need
Section titled “You need”- The admin role in the workspace. Any plan.
- An administrator of the client’s Okta org or Entra ID directory.
- Someone who can add a TXT record to the DNS of the client’s email domain.
- The client’s own email domain. Public domains such as gmail.com are refused.
1. Choose the provider and copy the callback URL
Section titled “1. Choose the provider and copy the callback URL”- Open Single sign-on under Workspace.
- Choose Okta or Microsoft Entra ID.
- Copy Callback / redirect URI (configure in your IdP) with the copy button.
2. Create the application in the identity provider
Section titled “2. Create the application in the identity provider”Follow the numbered steps shown on the page for the provider you chose.
- Okta: create an OIDC web application, set the sign-in redirect URI to the callback URL, assign the users or groups, and copy the client ID and client secret.
- Microsoft Entra ID: create an app registration, set the web redirect URI to the callback URL, create a client secret, and copy the application (client) ID and the secret value.
3. Create the connection
Section titled “3. Create the connection”- Enter the Issuer URL.
- Okta: the org URL, for example
https://your-org.okta.com, or a custom authorisation server URL. - Entra ID:
https://login.microsoftonline.com/<tenant-id>/v2.0.
- Okta: the org URL, for example
- Enter the Client ID and the Client secret.
- Enter the Email domain as a bare domain, for example
client.com. - Choose Create connection.
You see SSO connection created. Now verify your domain. The badge reads Awaiting domain verification.
4. Verify the domain
Section titled “4. Verify the domain”- In Verify domain ownership, copy Name. It is
_idnguard-verify.followed by the domain. - Copy Value.
- At the DNS host, create a TXT record with that name and that value.
- Choose Verify domain.
You see Domain verified. SSO is live. and the badge changes to Live.
If a TXT record not found message appears, wait a few minutes and choose Verify domain again. DNS changes take time.
5. Test it
Section titled “5. Test it”- Sign out, or open a private browser window.
- On the sign-in page, choose Continue with single sign-on.
- Enter a work email address at the domain and choose Continue.
- Sign in at the identity provider. The workspace dashboard opens.
Test with a second person before you tell the whole team.
6. Set the roles
Section titled “6. Set the roles”People who join through single sign-on arrive as members.
- Open Members.
- Choose the right role in the Role field on each person’s row.
7. Optional: block email invitations
Section titled “7. Optional: block email invitations”On the Single sign-on page, choose the button beside Restrict membership to SSO so that it reads On. You see Membership is now restricted to SSO. Email invitations are blocked.
From now on, the identity provider alone decides who can join.
Invite an outside guest
Section titled “Invite an outside guest”With Restrict membership to SSO on, you cannot invite an address outside the domain. To invite a guest:
- Open Single sign-on. Beside Restrict membership to SSO, choose On so that it reads Off.
- Open Members, enter the guest’s address and role, and choose Send Invite.
- After the guest has joined, set Restrict membership to SSO back to On.
Remove single sign-on
Section titled “Remove single sign-on”- Open Single sign-on and choose Remove connection.
- Confirm the browser question.
People keep their accounts and memberships. Each person at the domain then sets up a passkey from Create account / set up a passkey on the sign-in page.
If it does not work
Section titled “If it does not work”| What you see | What to do |
|---|---|
| Bad Request: issuer does not look like a valid … issuer | Use the issuer format shown in step 3 for your provider. |
| Bad Request: Enter a bare domain like client.com (no scheme or path). | Remove https:// and anything after the domain. |
| Bad Request: Public email provider domains cannot be used for SSO routing. | Use the organisation’s own domain. |
| The domain … is already verified by another workspace. | Another workspace has claimed the domain. That workspace removes its connection, or contact support. |
| Could not read the identity provider’s OpenID configuration | Check the Issuer URL for typing mistakes. |
| TXT record not found … | Check the record name and value at the DNS host. Wait a few minutes. Try again. |
| No single sign-on for this domain. at sign-in | The domain is not verified yet. Finish step 4. |
| Verify the domain first. SSO-only membership requires a live connection. | Verify the domain before you restrict membership. |
| A person signs in but gets You do not have access to this workspace. | Check that the person is assigned to the application in the identity provider. |
Every message is explained in Single sign-on and Signing in.