SAML SSO Setup — Google Workspace

Step-by-step guide for connecting Google Workspace as the identity provider for your NaturalTTS workspace.

Estimated time: 20–30 minutes.

If you haven't already, read the general SAML setup overview for what SAML SSO does, when to use it, and what your users will experience after it's enabled. This guide assumes you've made the decision to enable SAML and now need the Google Workspace-specific procedure.

Prerequisites

Super Admin role in Google Workspace. Standard admin roles cannot create or enable custom SAML applications.
Workspace Owner or Admin role in NaturalTTS.
A SAML email domain you control (e.g., acme.edu). This domain must be unique to your NaturalTTS workspace.
Two browser tabs open side by side — one on the Google Admin console (admin.google.com), one on NaturalTTS /settings/sso — for copy-pasting values between them.

Step 1 — Copy Service Provider details from NaturalTTS

If you don't yet have an SSO connection saved, create a draft now:

Select SAML 2.0 as the protocol.
Enter your Email domain (e.g., acme.edu).
Leave the IdP fields blank for now.
Click Add connection. NaturalTTS saves a draft (not yet enabled) and surfaces the Service Provider details panel.

Copy these three values — you'll paste them into Google in step 4:

NaturalTTS field	What Google calls it
SP Entity ID	Entity ID (under Service Provider Details)
ACS URL	ACS URL (under Service Provider Details)
SP Metadata URL	(Reference URL — Google doesn't accept SP metadata upload for custom SAML apps; the field-by-field approach below is required.)

The fingerprint shown next to the Certificate field is empty at this point. You'll paste a certificate from Google in step 3.

Step 2 — Create the custom SAML app in Google Workspace

Sign in to the Google Admin console at https://admin.google.com.
Navigate to Apps → Web and mobile apps.
Click Add app → Add custom SAML app.
App details:
- App name: NaturalTTS (or any label your team will recognize).
- Description: optional.
- App icon: optional.
Click Continue.

Step 3 — Copy IdP information from Google

Google now shows a Google Identity Provider details page. This is where you collect the IdP-side values to paste into NaturalTTS later.

Two options:

Recommended: Download IdP metadata. Click Download metadata. This downloads an XML file containing all the IdP values. You can either reference it directly or extract individual fields below.
Manual: copy each field. Note the following three values:
- SSO URL — becomes the SSO URL in NaturalTTS.
- Entity ID — becomes the IdP Entity ID (Issuer) in NaturalTTS. (Yes, "Entity ID" appears on both the IdP and SP sides — Google uses the same term for both, which is confusing. The one here, on the Google IdP info page, is the IdP's identifier.)
- Certificate — click Download certificate. You'll get a .pem file containing the X.509 certificate in PEM format.

Open the .pem file in a plain-text editor (Notepad, VS Code, etc.). The contents look like:

-----BEGIN CERTIFICATE-----
MIIDdDCCAlygAwIBAgIJAKZgJdKdCdL6MA0GCSqGSIb3DQEBCwUA...
-----END CERTIFICATE-----

Keep this file open — you'll copy its contents in step 6.

Click Continue to advance to the Service Provider details page.

Step 4 — Configure Service Provider details

Fill in the Service Provider Details page using the values you copied from NaturalTTS in step 1:

ACS URL: paste the ACS URL from NaturalTTS.
Entity ID: paste the SP Entity ID from NaturalTTS. (This is the SP-side Entity ID — different value from the IdP Entity ID you copied in step 3.)
Start URL: leave blank.
Signed response: check this box (recommended; ensures Google signs the SAML response wrapper in addition to the assertion).
Name ID format: select EMAIL.
Name ID: select Basic Information → Primary email.

Click Continue.

Step 5 — Configure attribute mapping

Google's attribute mapping page lets you map Google Workspace user attributes to SAML attribute names. NaturalTTS uses these attributes to populate the user's profile when JIT provisioning creates an account.

Click Add mapping and configure four mappings:

Google Directory attribute	App attribute
Basic Information → Primary email	`email`
Basic Information → First name	`firstName`
Basic Information → Last name	`lastName`
Basic Information → First name	(covered above; see displayName note below)

On displayName: Google Workspace does not have a built-in single-field "display name" attribute. Two options:

Skip it. If you don't map displayName, NaturalTTS composes it from firstName + lastName automatically.
Map a custom attribute. If your Google Workspace tenant has a custom user schema attribute that holds a preferred display name, map that to displayName.

The skip approach is recommended unless you have a specific reason to override.

Click Finish.

Step 6 — Paste IdP information into NaturalTTS

Return to NaturalTTS /settings/sso. The draft SAML connection from step 1 is still there.

Fill in the SAML fields with the values copied from Google in step 3:

Entity ID (Issuer): the Google IdP Entity ID.
SSO URL (Login URL): the Google SSO URL.
X.509 Certificate (PEM): paste the full contents of the .pem file from step 3, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.

In the SAML provisioning section of the same form:

Just-in-time user provisioning: leave enabled (recommended). Google Workspace users assigned to the SAML app are auto-created in NaturalTTS on first sign-in.
Default role for new users: select Member (recommended), or another role per your organization's policy. Owner is not selectable by design — see the general setup guide for the security rationale.

Click Update connection.

After saving, the Service Provider details panel shows the certificate fingerprint (formatted as aabb:ccdd:eeff:0011). Make a note of it — if Google rotates its SAML signing certificate, you can verify the new fingerprint matches what Google shows in the admin console.

Step 7 — Turn the app on for your users

Back in Google Admin (admin.google.com → Apps → Web and mobile apps → NaturalTTS), open the User access section.

Choose who can use the app:

ON for everyone: all users in your Google Workspace tenant.
OFF, with exceptions: specific organizational units (OUs) or groups can use it; everyone else cannot.

Click Save.

Only users for whom the app is turned ON can sign in to NaturalTTS via SAML. A user with a matching email domain but no Google app access hits a Google error before reaching NaturalTTS.

Google can take up to 24 hours to propagate app access settings across all servers, though in practice it's usually within a few minutes.

Step 8 — Test Connection

Return to NaturalTTS /settings/sso. Below the configuration form, click Open IdP test login in the Test Connection card.

A new browser tab opens to Google. Authenticate with your own Google Workspace credentials. After authentication, you should be redirected back to NaturalTTS and land on the dashboard.

If the round-trip works, the SAML connection is functioning. If it doesn't, see the troubleshooting reference — Test Connection failures with Google are usually one of: the app hasn't propagated yet (wait 5-10 minutes and retry), missing user access in the User access section, or a mismatch between the Entity ID fields (it's easy to swap the IdP and SP Entity IDs given Google uses the same term for both).

Do not click Enable yet. Test Connection only validates the technical round-trip. Confirm you understand the impact of enabling SAML before flipping the switch.

Step 9 — Enable SAML

Once Test Connection succeeds and you've reviewed the impact on your existing users, the final step is to enable the connection.

Scroll to the Enable SSO for this workspace card in NaturalTTS. Read the warning carefully. The full enablement guidance is in the general setup guide — at minimum, confirm that a teammate has Owner or Admin access from an email outside your SAML domain before you proceed, so they can disable SAML if anything goes wrong.

Check the confirmation box, then click Enable SSO.

The Recent SSO Activity log on the same page now shows a saml.enabled entry. From this point forward, any user signing in with an email at your configured domain is routed through Google Workspace.

Google Workspace-specific notes

Propagation delay. Google takes up to 24 hours to propagate SAML app configuration changes across all its servers. If a change you make in the admin console isn't reflected when you Test Connection, wait 5–10 minutes and retry before troubleshooting deeper. In practice, most changes take effect within a few minutes; the 24-hour figure is Google's worst-case guarantee.

Entity ID terminology. Google calls both the IdP-side and SP-side identifiers "Entity ID", which is the single most common source of setup mistakes. The IdP Entity ID is what Google generates (you copy it from Google's IdP details page into NaturalTTS). The SP Entity ID is what NaturalTTS generates (you copy it from NaturalTTS into Google's Service Provider Details page). Don't swap them.

Certificate rotation. Google rotates SAML signing certificates periodically. If signature verification starts failing after a Google-side change, the cert is the first thing to check. Download the new certificate from Google's IdP details page, paste it into NaturalTTS via the Replace button, and Test Connection. The old certificate stops being accepted as soon as you save.

Organizational unit (OU) scoping. If you turn the app on for specific OUs rather than the whole tenant, only users in those OUs can sign in to NaturalTTS. A user moved out of an enabled OU loses access on their next sign-in attempt; existing sessions stay active until they expire.

Google Workspace vs personal Google accounts. SAML SSO via Google Workspace only works for users on your managed Workspace domain. Users signing in with personal @gmail.com accounts (or another Workspace tenant) are not routed through your SAML config, regardless of the email domain matching — because Google's SAML IdP only authenticates users within your tenant.

No built-in displayName. Unlike Okta and Entra, Google Workspace doesn't expose a user.displayName attribute by default. NaturalTTS composes it from firstName + lastName if displayName isn't supplied, which works correctly for most users. If you want a different display format, configure a custom Workspace user attribute and map it to displayName.

What to do if something goes wrong

The SAML troubleshooting reference covers issues common across all IdPs, including Google-specific symptoms. Read that first.

If the troubleshooting guide doesn't resolve your issue, contact NaturalTTS support with: your workspace name, your email domain, the IdP (Google Workspace), and any error message text or screenshot you have. Do not send your Google certificate or any SAML response XML — both contain sensitive material.