SAML SSO Setup — Microsoft Entra ID (Azure AD)

Step-by-step guide for connecting Microsoft Entra ID (formerly Azure Active Directory) 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 Entra ID-specific procedure.

Prerequisites

• Cloud Application Administrator or Global Administrator role in Microsoft Entra ID. Lower-privilege roles do not have permission to create or configure Enterprise 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 Entra admin center, one on NaturalTTS /settings/sso — for copy-pasting values between them.

Step 1 — Copy Service Provider details from NaturalTTS

Sign in to NaturalTTS and navigate to Settings → SSO (/settings/sso).

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

1. Select SAML 2.0 as the protocol.
2. Enter your Email domain (e.g., acme.edu).
3. Leave the IdP fields blank for now.
4. 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 Entra in step 3:

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

Step 2 — Create the Enterprise Application in Entra

1. Sign in to the Microsoft Entra admin center at https://entra.microsoft.com (or the Azure portal at https://portal.azure.com and search for Microsoft Entra ID).
2. Navigate to Identity → Applications → Enterprise applications.
3. Click New application.
4. Click Create your own application (top of the page).
5. Name: NaturalTTS (or any label your team will recognize).
6. Under What are you looking to do with your application?, select Integrate any other application you don't find in the gallery (Non-gallery).
7. Click Create.

Entra provisions the application and lands on its overview page.

Step 3 — Configure Single sign-on

In the left sidebar of the application page, select Single sign-on, then choose SAML as the sign-on method.

You'll see five numbered sections. Configure the first three; the others are for the values you'll copy back into NaturalTTS.

Section 1: Basic SAML Configuration

Click the Edit (pencil) icon and fill in:

• Identifier (Entity ID): paste the SP Entity ID from NaturalTTS. Click Add identifier.
• Reply URL (Assertion Consumer Service URL): paste the ACS URL from NaturalTTS. Click Add reply URL.
• Sign on URL: leave blank.
• Relay State: leave blank.
• Logout URL: leave blank.

Click Save, then close the edit panel.

Section 2: Attributes & Claims

Click the Edit icon. Entra populates several default claims using full XML schema URIs (e.g., http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress). NaturalTTS accepts both the short names (email, firstName, lastName, displayName) and these full URIs, so you can leave most of the defaults in place.

Confirm or add the following claims:

For the Unique User Identifier (Name ID) field at the top:

• Source attribute: user.mail (or user.userprincipalname if mail isn't reliably populated).
• Name identifier format: Email address.

This is the value NaturalTTS uses to match returning SAML users to existing accounts. It should be your users' canonical work email.

Section 3: SAML Signing Certificate

Locate the Certificate (Base64) entry and click Download. You'll get a .cer file.

Open the .cer file in a plain-text editor (Notepad, VS Code, etc.). Despite the file extension, the contents are PEM-encoded:

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

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

Step 4 — Copy IdP information from Entra

Scroll to Section 4: Set up [your app name] on the same Single sign-on page.

Copy these two values:

1. Login URL — this becomes the SSO URL in NaturalTTS.
2. Microsoft Entra Identifier — this becomes the IdP Entity ID (Issuer) in NaturalTTS.

You already have the certificate from step 3. That's the third piece.

Step 5 — Assign users to the application

In the application's left sidebar, select Users and groups.

Click Add user/group, select the users or groups who should have NaturalTTS access, choose a role (typically Default Access for application access only), and click Assign.

Only assigned users can sign in to NaturalTTS via SAML. A user with a matching email domain but no Entra assignment hits an Entra error before reaching NaturalTTS.

By default, Entra restricts the application to assigned users. If your tenant requires all users to be allowed (e.g., because you manage access via Conditional Access policies instead), open the application's Properties page and toggle Assignment required? to No. Most customers should leave it at Yes.

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 Entra in steps 3 and 4:

• Entity ID (Issuer): the Microsoft Entra Identifier.
• SSO URL (Login URL): the Login URL.
• X.509 Certificate (PEM): paste the full contents of the .cer 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). Users assigned to the Entra 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 — Entra rotates SAML signing certificates periodically, and the fingerprint lets you confirm which cert is active.

Step 7 — Test Connection

Below the configuration form, click Open IdP test login in the Test Connection card.

A new browser tab opens to Entra. Authenticate with your own Entra 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 Entra are usually one of: missing user assignment, the Name ID claim returning userprincipalname when mail was expected (or vice versa), or a certificate mismatch.

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 8 — 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. 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 Entra.

Entra-specific notes

Schema URI vs short attribute names. Entra emits attribute claims with full XML schema URIs by default (e.g., http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress). NaturalTTS accepts both these URIs and the short names (email, firstName, etc.), so you don't have to rename Entra's default claims. If you simplify the claim names in Entra, the SAML flow continues to work.

user.mail vs user.userprincipalname. Entra distinguishes between the User Principal Name (often the user's sign-in identifier) and the Mail attribute (the user's actual email address). Most organizations have these set to the same value, but they can differ — and the difference matters for SAML. If your users' user.mail isn't reliably populated, use user.userprincipalname for the Name ID instead. Whichever you choose must match the email domain configured in NaturalTTS.

Certificate rotation. Entra-generated SAML signing certificates expire after three years by default, but you can rotate manually at any time (SAML Signing Certificate section → New Certificate). When you rotate, the new certificate must be pasted into NaturalTTS via the Replace button on the Certificate field. The old certificate stops being accepted as soon as you save. Entra can email an alert before automatic expiration — configure the notification email in the SAML Signing Certificate section.

Conditional Access. If your tenant uses Entra Conditional Access policies (require MFA, restrict by location, require compliant device, etc.), those policies apply to NaturalTTS SAML sign-ins automatically. No NaturalTTS-side configuration is needed; Entra enforces the policy before issuing the SAML assertion.

Microsoft Authenticator and MFA. If MFA is enforced via Entra, users are prompted for their second factor during the SAML round-trip. They won't see a separate prompt in NaturalTTS — the entire authentication step happens at Entra.

Naming: Azure AD vs Entra ID. Microsoft renamed Azure Active Directory to Microsoft Entra ID in 2023. The product is the same; documentation and UI labels vary depending on when they were written. If your admin portal still says "Azure Active Directory" instead of "Microsoft Entra ID", everything in this guide still applies — the menus and field names are unchanged.

What to do if something goes wrong

The SAML troubleshooting reference covers issues common across all IdPs, including Entra-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 (Microsoft Entra ID), and any error message text or screenshot you have. Do not send your Entra certificate or any SAML response XML — both contain sensitive material.