This article is for IT and security teams who want to connect their identity provider (IdP) to Turtl. It explains how SSO works in Turtl, which values to enter in your IdP, what to send to us and how to test the integration. If you use Okta, follow the Okta steps for the exact settings.
Notes:
SSO is available on our Grow AI and Scale AI plans. Please contact Customer Support if you want to upgrade your plan.
Before you start, contact Customer Support and tell us which IdP you use. We'll send you your exact ACS URL and a form for your IdP's details.
How SSO works with Turtl
Once SSO is connected, your IdP decides who can sign in to Turtl. Turtl then gives each person access based on their Turtl account.
One set of credentials: Your team signs in to Turtl with their company account, so there's no extra password to remember.
SSO for everyone, or just some: You can require SSO for your whole team, or turn it on for individual users.
Internal Docs stay internal: Docs set to "Anyone at my company" can only be read by people your IdP signs in.
There are two things to know before you start:
Turtl matches people by email address: The email your IdP sends must match the email on the person's Turtl account. Case doesn't matter.
Sign-in starts from Turtl: People open Turtl or a link to a Doc, and we send them to your IdP. Launching Turtl from an IdP dashboard tile isn't supported.
Before you start
Make sure you have:
Admin access to your IdP, so you can create a SAML app.
Your Turtl domain. This is
your-team.turtl.co, or your custom domain (for example,content.example.com) if your team signs in through one.A conversation with Customer Support, where you've told us which IdP you use.
Set up SSO with any SAML 2.0 provider
In your IdP, create a new SAML 2.0 app for Turtl.
Enter Turtl's details from the table below.
Assign the people or groups who should sign in to Turtl or read your internal Docs.
Send your IdP's details to Customer Support, using the form we send you.
When we confirm the integration is live, test it.
Turtl's details
Setting | Value |
Assertion Consumer Service (ACS) URL (also called Reply URL or Single sign-on URL) | Always use the exact URL Customer Support sends you, as a different ending won't match. It looks similar to this example: |
Audience URI (also called SP Entity ID or Identifier) |
|
Name ID format | Email address |
Name ID value | The user's email address |
Email attribute | Also send the email as an attribute named |
Signing | Sign the SAML response, the assertion, or both |
Encryption | Leave the assertion unencrypted |
Note: If you use a custom domain, Customer Support will confirm which domain goes into your ACS URL and Audience URI. Use the domain your team actually signs in on.
What to send us
The easiest way is to send us your IdP's metadata XML, as it contains everything we need. Otherwise, send us:
Identity Provider Single Sign-On URL: Your IdP's SAML sign-on endpoint.
X.509 signing certificate: Your IdP's SAML signing certificate, as PEM text.
Attribute names: Only needed if you add the optional attributes below.
Once we receive your details, we aim to finish the setup on our side within one business day.
Optional: send more user details
If you want Turtl to receive more than an email address for the people who sign in, you can send these attributes too. You can name them however you like, as long as you tell us the names.
Turtl field | Typical source in your IdP |
First name | Given name |
Last name | Surname |
Job title | Title |
Department | Department |
Phone number | Mobile or work phone |
Set up SSO with Okta
These steps are for the Okta Admin Console. Okta's labels are in quotes.
Go to "Applications" (in newer consoles, "Applications and Resources", then "Applications") and click "Create App Integration". If Okta asks, choose "Classic experience".
Select "SAML 2.0" as the sign-in method and click "Next".
On "General Settings", set "App name" to Turtl and click "Next".
On "Configure SAML", fill in the "General" section using the table below.
Under "Attribute Statements", add
email=user.email. If you want to send more user details, you can also addfirstName=user.firstName,lastName=user.lastName,title=user.titleanddepartment=user.department. Make a note of the names you use.Click "Show Advanced Settings". Set "Response" or "Assertion Signature" (or both) to "Signed", "Signature Algorithm" to "RSA-SHA256" and "Assertion Encryption" to "Unencrypted".
Click "Next". On the feedback step, select "I'm an Okta customer adding an internal app" and click "Finish".
On the "Assignments" tab, assign the people or groups who should be able to sign in.
On the "Sign On" tab, open "View SAML setup instructions" or copy the "Metadata URL". Send Customer Support the "Identity Provider Single Sign-On URL" and "X.509 Certificate", plus any attribute names from step 5.
Okta field | Value |
Single sign-on URL | Always use the exact URL Customer Support sends you, as a different ending won't match. It looks similar to this example: |
Use this for Recipient URL and Destination URL | Checked |
Audience URI (SP Entity ID) |
|
Default RelayState | Leave empty |
Name ID format | EmailAddress |
Application username format | |
Update application username on | Create and update |
Note: Make sure "Name ID format" is set to "EmailAddress". Okta's default, "Unspecified", won't work.
Okta tips
Always send the email: If someone's Okta username isn't their email address, keep "Application username format" set to "Email". This way, Turtl always receives an address it can match.
Hide the tile: Sign-in starts from Turtl, so you can go to "General", then "App Settings", and check "Do not display application icon to users".
Rotating a certificate: Send the new signing certificate to Customer Support before you activate it in Okta. SSO sign-ins fail until we update it on our side.
More than one Okta org: Turtl can connect several IdPs to one login page, and people choose theirs when they sign in.
Who gets access
SSO decides who can sign in. Roles, licenses and Workspace access are still managed in Turtl.
Who signs in through your IdP | What they get |
A user on your Turtl team, with the same email | Their own Turtl account, with their usual role |
Someone who isn't a Turtl user | Read access to Docs set to "Anyone at my company". No access to the Editor or analytics. |
SSO doesn't create Turtl user accounts. To add editors, invite them from "Users" in Turtl, or ask Customer Support about automatic provisioning with SCIM.
Make SSO the only way to sign in
For everyone: Ask Customer Support to turn on Force SSO. This switches off email and password login for your whole team.
For selected users: Go to "Users", click "Edit" next to a user and check "Require to login with SSO".
To learn more, see Applying Single Sign-On (SSO) settings to users and Turtl content.
Test the integration
In Turtl, create a test Doc and set its access control to "Anyone at my company".
Open the link to the Doc in a private browser window. If you have a custom domain, use it in the link.
Sign in as someone who's assigned to the Turtl app in your IdP but isn't a Turtl user. The Doc should open.
Go to your Turtl login page and sign in with SSO as an existing Turtl user. You should land in your Turtl account.
Troubleshooting
Your IdP says the user isn't assigned to the app: Assign the user, or their group, to the Turtl app in your IdP.
Turtl shows "SSO authentication failed": The certificate, ACS URL or Audience URI doesn't match. Check them against the tables above, or send Customer Support a new metadata file.
A Turtl user gets read access only, with no access to the Editor: The email your IdP sends doesn't match the email on their Turtl account. Make sure both are the same.
SSO stopped working for everyone: Your IdP's signing certificate has probably changed. Send the new certificate to Customer Support.
If you're still stuck, send Customer Support the user's email address and the time of the failed sign-in. We can turn on SSO debug logging to see exactly what your IdP sends us. For more error messages, see SSO troubleshooting.

