Skip to main content

Setting up Single Sign-On (SSO) with Okta and other SAML 2.0 providers

Everything your IT team needs to connect Okta, Microsoft Entra ID, Google Workspace or any SAML 2.0 provider to Turtl

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

  1. In your IdP, create a new SAML 2.0 app for Turtl.

  2. Enter Turtl's details from the table below.

  3. Assign the people or groups who should sign in to Turtl or read your internal Docs.

  4. Send your IdP's details to Customer Support, using the form we send you.

  5. 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: https://your-team.turtl.co/user/login/callback/default

Audience URI (also called SP Entity ID or Identifier)

https://your-team.turtl.co, with no trailing slash. It must match the value we enter exactly.

Name ID format

Email address

Name ID value

The user's email address

Email attribute

Also send the email as an attribute named email

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.

  1. Go to "Applications" (in newer consoles, "Applications and Resources", then "Applications") and click "Create App Integration". If Okta asks, choose "Classic experience".

  2. Select "SAML 2.0" as the sign-in method and click "Next".

  3. On "General Settings", set "App name" to Turtl and click "Next".

  4. On "Configure SAML", fill in the "General" section using the table below.

  5. Under "Attribute Statements", add email = user.email. If you want to send more user details, you can also add firstName = user.firstName, lastName = user.lastName, title = user.title and department = user.department. Make a note of the names you use.

  6. Click "Show Advanced Settings". Set "Response" or "Assertion Signature" (or both) to "Signed", "Signature Algorithm" to "RSA-SHA256" and "Assertion Encryption" to "Unencrypted".

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

  8. On the "Assignments" tab, assign the people or groups who should be able to sign in.

  9. 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: https://your-team.turtl.co/user/login/callback/default

Use this for Recipient URL and Destination URL

Checked

Audience URI (SP Entity ID)

https://your-team.turtl.co

Default RelayState

Leave empty

Name ID format

EmailAddress

Application username format

Email

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


Test the integration

  1. In Turtl, create a test Doc and set its access control to "Anyone at my company".

  2. Open the link to the Doc in a private browser window. If you have a custom domain, use it in the link.

  3. Sign in as someone who's assigned to the Turtl app in your IdP but isn't a Turtl user. The Doc should open.

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

Did this answer your question?