SAML SSO Setup — Okta

Step-by-step guide for connecting Okta 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 Okta-specific procedure.

Prerequisites

Admin role in Okta with permission to create new application integrations. Standard Okta Admin or Super Admin roles both qualify.
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 Okta Admin, 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 Okta in step 3:

NaturalTTS field	What Okta calls it
SP Entity ID	Audience URI (SP Entity ID)
ACS URL	Single sign on URL
SP Metadata URL	(Reference URL — you can paste your full SP metadata into some Okta workflows, but the field-by-field approach below is reliable across Okta versions.)

The fingerprint shown next to the Certificate field (formatted as aabb:ccdd:eeff:0011) is empty at this point. You'll paste a certificate from Okta in step 6.

Step 2 — Create the SAML application in Okta

Sign in to Okta Admin at https://<your-org>-admin.okta.com.
Navigate to Applications → Applications.
Click Create App Integration.
Select SAML 2.0, then click Next.

On the General Settings page:

App name: NaturalTTS (or any label your team will recognize in Okta).
App logo: optional.
Click Next.

Step 3 — Configure SAML settings

This is the page where you paste the NaturalTTS values you copied in step 1.

Single sign on URL: paste the ACS URL from NaturalTTS.

Use this for Recipient URL and Destination URL: leave checked (default).

Audience URI (SP Entity ID): paste the SP Entity ID from NaturalTTS.

Default RelayState: leave blank.

Name ID format: select EmailAddress.

Application username: select Email.

Update application username on: Create and update (default).

Attribute Statements (required)

This section is critical. NaturalTTS reads these attributes from the SAML assertion to populate the user's profile when JIT provisioning creates an account.

Add four attribute statements:

Name	Name format	Value
`email`	Unspecified	`user.email`
`firstName`	Unspecified	`user.firstName`
`lastName`	Unspecified	`user.lastName`
`displayName`	Unspecified	`String.append(user.firstName, " ", user.lastName)`

If your Okta org has a populated user.displayName attribute, you can use that directly for the displayName value instead of the String.append(...) expression. Either works.

Group Attribute Statements: leave empty. NaturalTTS does not currently consume group claims (groups are managed inside NaturalTTS, not from the IdP).

Click Next.

Feedback page

Okta uses the feedback page for internal categorization. Pick the option that matches your use of NaturalTTS — typically "This is an internal app that we have created" or the equivalent option for a customer-supplied SAML integration. The choice here doesn't affect the SAML flow.

Click Finish.

Step 4 — Copy IdP information from Okta

After creating the app, Okta lands on the application's detail page. Open the Sign On tab.

Look for a section labelled SAML 2.0 or SAML Signing Certificates. Within that section, locate three pieces of information to copy:

Identity Provider Issuer — this becomes the IdP Entity ID (Issuer) in NaturalTTS.
Identity Provider Single Sign-On URL — this becomes the SSO URL in NaturalTTS.
X.509 Certificate — Okta typically offers a Download or View option. Either download the .cert file and open it in a plain-text editor, or click View to see the PEM contents directly.

The certificate must be in PEM format with the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines included. Okta's download is already in this format — paste the entire contents, headers included.

Step 5 — Assign users to the application

Back on the application detail page, open the Assignments tab.

Assign the app to the users or groups who should have NaturalTTS access. You can assign individually or by Okta group; group assignment is easier to manage long-term.

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

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 Okta in step 4:

Entity ID (Issuer): the Okta Identity Provider Issuer.
SSO URL (Login URL): the Okta Identity Provider Single Sign-On URL.
X.509 Certificate (PEM): the full certificate including the BEGIN/END lines.

In the SAML provisioning section of the same form:

Just-in-time user provisioning: leave enabled (recommended). Users assigned to the Okta 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 (e.g., aabb:ccdd:eeff:0011). Make a note of it — if a future Okta certificate rotation lands, you can verify the new fingerprint matches what Okta shows.

Step 7 — Test Connection

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

A new browser tab opens to Okta. Authenticate with your own Okta 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 are usually one of: ACS URL mismatch, certificate mismatch, or missing user assignment in Okta.

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 Okta.

Okta-specific notes

Certificate rotation. Okta rotates SAML signing certificates roughly every two years, but you can rotate manually at any time (Sign On tab → SAML Signing Certificates → Generate 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. Always Test Connection after a rotation.

Updating the SAML app in Okta later. Changes to the Okta-side configuration (attribute mappings, NameID format, etc.) take effect immediately. You don't need to re-save anything in NaturalTTS unless the IdP Entity ID, SSO URL, or certificate change.

Group-based user assignment. Assigning by Okta group rather than individual users scales better. New users added to the assigned group get NaturalTTS access automatically; removed users lose it on their next sign-in attempt (existing sessions remain active until they expire).

Multiple environments. If you have separate Okta orgs for production and staging, treat them as separate SAML configurations. Each needs its own NaturalTTS workspace with a distinct email domain.

What to do if something goes wrong

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