Configuring SSO with your identity provider

SSO (single sign-on) lets your team sign in to Thawly using your existing company identity provider — Microsoft Entra ID, Okta, Google Workspace, or any standards-compliant SAML 2.0 provider. Once activated, your reps open Thawly with the same credentials they use for every other tool. No separate Thawly password, and deprovisioning in your IdP immediately removes Thawly access.

This guide covers the customer-admin side: how to wire up your IdP after Thawly has activated your SAML connection. If you haven't purchased the SSO add-on yet, see Single sign-on (SSO) for pricing and the purchase flow. If you're Mitch running an activation, the operator-side runbook lives in docs/ops/clerk-sso-activation-runbook.md.

---

1. What is SSO on Thawly?#

Thawly's SSO add-on is a £49/month add-on available on every paid plan (Starter, Growth, Scale). It uses Clerk's SAML 2.0 integration, which Thawly configures per-customer so your IdP connection is isolated and not shared with any other organisation.

Once SSO is live, your team members see a "Sign in with SSO" button on the Thawly login page. They enter their company email, are redirected to your IdP for authentication, and land back in Thawly — no Thawly-specific password involved.

Users who sign in for the first time via SSO are auto-provisioned into your Thawly organisation (just-in-time provisioning). Removing a user from your IdP revokes their Thawly access on their next sign-in attempt. Seats are unlimited on every paid plan — there is no per-seat charge.

---

2. Before you start#

Complete this checklist before touching your IdP:

• Admin access to your identity provider. You need permission to create enterprise/SAML applications. In Entra ID this is "Application Administrator" or "Global Administrator"; in Okta it is the Okta admin console; in Google Workspace it is a "Super Admin" or "Services Admin" role.
• Admin access to your Thawly organisation. You must be an Org Admin in Thawly (Settings → Team) to view and manage the SSO card.
• SSO add-on purchased. Go to Billing in Thawly and confirm the SSO add-on is on your subscription. If it isn't, click "Add SSO — £49/mo" and complete Stripe checkout.
• Activation email received. After purchase, Thawly activates your SAML connection within 1 business day. You will receive an email when it is ready. The SSO card in Settings will change from "activation in progress" to showing the IdP configuration panel.

If you see "activation in progress" in Settings → Account → Single sign-on, your connection is being configured on the Thawly side. You can read ahead in this guide but you cannot enter IdP values yet — wait for the activation email.

---

3. Step-by-step: Microsoft Entra ID (Azure AD)#

What you will need from Thawly first

Open Settings → Account → Single sign-on in Thawly. Under the SAML configuration panel you will see two values — copy them before touching Entra:

Thawly may also offer a SP Metadata XML download link — if it does, use that instead of copying the two values manually (it pre-populates all fields automatically).

Creating the enterprise application in Entra ID

1. Sign in to the Microsoft Entra admin centre as an Application Administrator or Global Administrator.
2. In the left sidebar, navigate to Identity → Applications → Enterprise applications.
3. Click New application.
4. On the Browse Microsoft Entra Gallery screen, click Create your own application (top-right area of the gallery panel).
5. Name the application — for example, Thawly — and select "Integrate any other application you don't find in the gallery (Non-gallery)". Click Create.
6. You will land on the application's Overview page. In the left sidebar, click Single sign-on.
7. Select SAML as the sign-on method.
8. You are now on the SAML-based sign-on configuration page. Click the pencil icon on Basic SAML Configuration.
9. Fill in the two required fields:
   • Identifier (Entity ID): paste the Entity ID value from Thawly's SSO panel.
   • Reply URL (Assertion Consumer Service URL): paste the ACS URL value from Thawly's SSO panel.
   • Leave Sign-on URL blank (Thawly uses IdP-initiated SSO after setup; SP-initiated flows work too but the sign-on URL is optional for initial setup).
10. Click Save. Close the panel.

Configuring claims (attribute mapping)

In the Attributes & Claims section of the SAML configuration page:

1. Confirm that the following claims are present (they typically are by default in Entra):
   • emailaddress → user.mail (or user.userprincipalname if UPN equals email)
   • givenname → user.givenname
   • surname → user.surname
2. Entra-specific gotcha: Entra often sends the UPN as the email claim, which may be firstname.lastname@company.onmicrosoft.com rather than the user's actual email. If your UPN format differs from the real email, change the email claim source attribute from user.userprincipalname to user.mail.
3. Click Save if you made any changes.

Assigning users

1. In the left sidebar, click Users and groups.
2. Click Add user/group.
3. Add the Entra users or groups who should have access to Thawly.
4. Click Assign.

Only assigned users will be able to authenticate via SAML. Unassigned users will receive an error from Entra when they try to sign in.

Getting the federation metadata to paste into Thawly

1. Back on the SAML-based sign-on configuration page, find the SAML Certificates section.
2. Copy the App Federation Metadata Url — it is a URL ending in /federationmetadata/2007-06/federationmetadata.xml (with a query parameter appended by Entra).
3. Open Settings → Account → Single sign-on in Thawly. In the IdP configuration panel, paste the Metadata URL into the IdP Metadata URL field.
4. Click Save (or Verify connection if that button is shown).

Thawly will fetch the metadata URL and complete the connection. Proceed to Section 7 — Verifying it works.

---

4. Step-by-step: Okta#

What you will need from Thawly first

Open Settings → Account → Single sign-on in Thawly. Copy the ACS URL and Entity ID from the SAML configuration panel before creating the Okta app.

Creating the SAML 2.0 app in Okta

1. Sign in to your Okta admin console (https://yourcompany-admin.okta.com).
2. In the left sidebar, navigate to Applications → Applications.
3. Click Create App Integration.
4. Select SAML 2.0 as the sign-in method. Click Next.
5. Give the app a name — for example, Thawly. Upload a logo if you like. Click Next.
6. On the Configure SAML step:
   • Single sign-on URL: paste the ACS URL from Thawly's SSO panel.
   • Audience URI (SP Entity ID): paste the Entity ID from Thawly's SSO panel.
   • Name ID format: choose EmailAddress.
   • Application username: choose Okta username (or Email if your Okta usernames are not email addresses).
7. Under Attribute Statements, add the following three:

1. Click Next. On the Feedback step, select "I'm an Okta customer adding an internal app" and click Finish.

Assigning users in Okta

1. On the app's Assignments tab, click Assign → Assign to People (or Assign to Groups if you want to use group-based access).
2. Search for and assign the users or groups who should have Thawly access. Click Done.

Getting the IdP metadata to paste into Thawly

1. On the app's Sign On tab, click View SAML setup instructions or find the Identity Provider metadata link.
2. Copy the Metadata URL shown on that page.
3. Open Settings → Account → Single sign-on in Thawly. Paste the Metadata URL into the IdP Metadata URL field in the configuration panel.
4. Click Save.

Proceed to Section 7 — Verifying it works.

---

5. Step-by-step: Google Workspace#

What you will need from Thawly first

Open Settings → Account → Single sign-on in Thawly. Copy the ACS URL and Entity ID from the SAML configuration panel. Google Workspace requires these entered as fields (it does not accept a metadata URL from the SP).

Creating a custom SAML app in Google Workspace

1. Sign in to the Google Admin console as a Super Admin or Services Admin.
2. Navigate to Apps → Web and mobile apps.
3. Click Add app → Add custom SAML app.
4. Give the app a name — for example, Thawly. Click Continue.
5. On the Google Identity Provider details screen:
   • Download the IdP metadata XML file — you will upload this to Thawly shortly.
   • Or copy the SSO URL, Entity ID, and Certificate individually if you prefer manual entry.
   • Click Continue.
6. On the Service provider details screen:
   • ACS URL: paste the ACS URL from Thawly's SSO panel.
   • Entity ID: paste the Entity ID from Thawly's SSO panel.
   • Name ID format: choose EMAIL.
   • Name ID: choose Basic Information → Primary email.
   • Click Continue.
7. On the Attribute mapping screen, add the following mappings:

1. Click Finish.

Turning the app on for users

1. Still in the Admin console, open the app you just created.
2. Click User access.
3. Set the app to ON for everyone (or select specific Organizational Units if you want to restrict access).
4. Click Save.

Uploading the metadata to Thawly

1. Open Settings → Account → Single sign-on in Thawly.
2. In the IdP configuration panel, choose Upload XML and upload the metadata XML file you downloaded from Google in step 5 above.
3. Click Save.

Proceed to Section 7 — Verifying it works.

---

6. Step-by-step: Other SAML 2.0 providers#

This section covers any SAML 2.0-compliant identity provider not listed above — OneLogin, JumpCloud, Auth0, Duo Security, Ping Identity, and similar.

The exchange is identical across all SAML 2.0 providers. Thawly gives you an ACS URL and an Entity ID; your IdP gives you a metadata URL or metadata XML. Field labels vary by IdP but the values are standard.

Step 1 — Collect values from Thawly

Open Settings → Account → Single sign-on in Thawly. Note down:

• ACS URL (also called: Reply URL, Single Sign-On URL, Callback URL, SAML Consumer Service URL)
• Entity ID (also called: Audience URI, SP Entity ID, Relying Party Identifier)

Step 2 — Create a SAML app in your IdP

In your IdP's admin console, create a new SAML 2.0 application (or "Service Provider"). Enter the ACS URL and Entity ID in the fields your IdP uses. If your IdP accepts an SP metadata XML or URL, use that instead — it auto-populates all fields.

Configure claim / attribute mappings so that your IdP sends:

Assign the relevant users or groups.

Step 3 — Give Thawly your IdP metadata

Get the SAML Metadata URL or Metadata XML from your IdP. Open Settings → Account → Single sign-on in Thawly and paste the URL or upload the XML into the IdP configuration panel. Click Save.

---

7. Verifying it works#

Once you have saved the IdP metadata in Thawly's SSO panel, test the connection before rolling it out to your team.

1. Sign out of Thawly using the account menu in the top-right corner.
2. On the Thawly sign-in page, click "Sign in with SSO" (or "Continue with SSO").
3. Enter your company email address and click Continue.
4. You will be redirected to your IdP's login page. Sign in with your usual company credentials.
5. After successful authentication you will be redirected back to Thawly and land on the dashboard (/dashboard or the page you were trying to access).
6. Check that your name and email appear correctly in the account menu — this confirms Thawly received the claims from your IdP.

If the test works cleanly, let your team know they can now sign in using the SSO button.

---

8. Troubleshooting#

"Invalid ACS URL" or "Incorrect Assertion Consumer Service URL"

The URL in your IdP does not match what Thawly generated. Common causes:

• A trailing slash was added or removed by the IdP admin UI when pasting.
• The wrong field was used (e.g. the Single Logout URL field was filled instead of the ACS URL field).

Fix: copy the ACS URL from Thawly's SSO panel again and paste it freshly — do not retype it by hand.

"Audience URI mismatch" or "Issuer mismatch"

The Entity ID your IdP is sending does not match what Thawly expects.

Fix: open your IdP's application settings and confirm the Audience URI / SP Entity ID is set to exactly the Entity ID shown in Thawly's SSO panel.

"SAML certificate expired" or signature validation failures

IdP certificates rotate. Entra ID auto-rotates certificates every 1–3 years; Okta does not rotate by default.

Fix: download the updated IdP metadata XML from your IdP and re-upload it in Thawly's SSO panel. For Entra, refreshing via the Metadata URL is simplest — Thawly will re-fetch the current certificate automatically when you click Save.

"Claim mapping error" or users created without names

Thawly received the SAML assertion but could not map the email, first name, or last name.

Fix: check the attribute mapping section in your IdP's SAML application. Ensure the three attributes (email, firstName/given_name, lastName/family_name) are explicitly mapped. For Entra, confirm the email claim is sourcing from user.mail (not user.userprincipalname) if your UPN differs from email.

SSO button does not appear on the Thawly sign-in page

The SAML connection has not been fully activated yet on Thawly's side, or activation was completed but the connection is in Draft state rather than Active.

Fix: check whether you received the activation email. If not, email hello@thawly.co.uk and quote your organisation name. We will confirm the activation status.

Users get "Access denied" from the IdP

The user is not assigned to the Thawly SAML application in your IdP.

Fix: In Entra, add the user under Enterprise applications → Thawly → Users and groups. In Okta, assign the user or their group on the app's Assignments tab. In Google Workspace, check the app's User access settings.

---

9. Pricing#

The SSO add-on is billed alongside your existing Thawly subscription on the same invoice. You can cancel the add-on at any time from Billing → Manage subscription in Stripe. Your team falls back to email and password sign-in at the end of the current billing period. No Thawly data is lost when the add-on is cancelled.

If you have questions not covered here, email hello@thawly.co.uk with your IdP name and a description of what you're seeing.