Security Assertion Markup Language (SAML 2.0) is a web security standard for logging users into applications. This enables single sign-on (SSO), which allows users to access multiple applications or websites via a single authentication source. This is perfect for large organizations with enhanced security or user provisioning requirements.

Org admins on our Enterprise plan can enable SAML 2.0 SSO for all managed domains in their organization. This article will explain how.

Please note that this article covers SAML SSO, which is only available to customers on our Enterprise plan. Only Enterprise org admins (typically members of your IT team) will be able to enable SSO. If you're interested in upgrading to an Enterprise plan, check out this page.

SSO basics

SSO (or single sign-on) is a way for members of your organization to access multiple applications, including Coda, via a single authentication source. SAML is a web security standard that enables SSO.

Common terms

Below are some common terms related to SSO. We’ve provided descriptions so you can better navigate the process of setting up SSO.

IdP or Identity Provider: The service or product that manages user accounts, credentials, and the login process. It will send "SAML Responses" to the SP (below) to authenticate users. Examples include Okta and Microsoft Entra ID.
SP or Service Provider: The service or product that the Identity Provider is sending a "SAML Response" to to log in an end user - that's Coda in this case!
JIT or Just-In-Time Provisioning: Creates new users or updates existing users on the fly. When a user first logs into Coda through SSO, Coda will set up a new account for that user. The account will be updated (including avatar, first name, last name, etc.) on subsequent logins to Coda.
Managed Provisioning: An optional form of provisioning using the SCIM protocol. This allows IT administrators via Identity Providers to create, update, import, deactivate, reactivate, and delete users. Most Identity Providers can use this protocol to automate system provisioning, updating, and deprovisioning for your users automatically.

Set up SAML SSO

📣 If you are configuring SSO with Okta, please refer to the Okta-specific instructions found here. If you are configuring SSO with Microsoft Entra ID (formerly Azure AD), please refer to the Azure-specific instructions found here.

If you are configuring SSO with a different provider, continue with the instructions below.

Part 1: Enable SSO in Coda

The first step to setting up SSO is to enable it for your org on Coda. If you’re an org admin, you can follow the steps below to do so:

Go to coda.io/docs
In the upper left corner, click on Admin settings.
Scroll to - or search for - the Authentication methods tab (within the Security section)
Scroll down to the Authenticate with SSO (SAML) option, and toggle this on.
Then click the Configure SAML button. This will open the SAML configuration page.
In the SAML provider dropdown at the top of the page, select Standard.
Note the SAML metadata field in the For SAML identity provider section (on the left). These parameters will be needed for step #2 in the section below.

Part 2: Create a new application in your IDP

The next step is to create a new application in your identity provider (IDP) for Coda. This will be done within your identity provider’s platform.

📣 The steps below and terminology can vary slightly between identity providers. Coda currently supports any identity provider supporting SAML 2.0. Please refer to your identity provider's documentation for more detail on how to accomplish these steps. If you are using Okta, you can find Okta-specific instructions here. If you’re using Microsoft Entra ID (formerly Azure AD), you can find specific instructions here.

Create a new application in your identity provider administration console for Coda, and enable SAML SSO.
Copy the SAML metadata (see steps above) from Coda into the appropriate location in your identity provider setup.
1. If your identity provider does not accept a metadata URL or file, click Show all configurable fields dropdown in Coda and copy/paste the appropriate values into your identity provider (i.e. Entity ID, SAML response URL).
Ensure your application passes user identity to Coda in "email" format; that is, your Identity provider is sending email-address-like user identities to Coda.
Update your application to pass each user's first name and last name into Coda using parameters named "FirstName" and "LastName".
1. See the Accepted SAML attributes section below to understand the order in which Coda reads attributes for SAML.
Save your application and copy the resulting identity provider Metadata URL. You will be pasting this into Coda's SAML setup in the subsequent steps.
1. If your identity provider does not provide a metadata URL, copy the Identity Provider login URL, Identity Provider Expected Issuer, and the Public certificate/X.509 Signing Certificate.
Depending on your identity provider, you may need to assign users or groups to this new application.

Accepted SAML attributes

Coda updates user names during the SSO login flow by reading from the following SAML attributes in order, from top to bottom. Be sure to pass in one of the following sets of attributes.

First name field:	Last name field:
FirstName	LastName
first	last
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
firstName	lastName
http://schemas.microsoft.com/identity/claims/displayname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
nameID

Part 3: Configure SAML SSO in Coda

Lastly, you’ll take the information you gathered in Part 2 and finish configuring SAML in Coda.

Return to Coda's SAML configuration page (you should have landed here after the steps in Part 1). You will be editing the From SAML identity provider section, on the right half of your screen.
If you copied the Metadata URL in step 5 above: paste the URL into the Identity provider metadata URL field. Click the Import button.
1. Identity provider login URL, Identity provider expected issuer, and Identity provider public certificate will auto-fill. Make any manual edits if needed.
If you did NOT copy the Metadata URL in step 5 above: click the Show all configurable fields dropdown in Coda and fill out the following fields:
1. Identity provider login URL
2. Identity provider expected issuer
3. identity provider public certificate
Click Save.

That’s it - SAML SSO is now enabled for all Coda workspaces in your organization! You can test it out by logging into Coda via SSO, or asking one of your org members to do so.

Manage SSO for multiple workspaces

If you have multiple Coda workspaces within your Enterprise org and want to use SSO, you may be wondering how the right users are assigned to the right workspace. That’s where SAML assertions comes in.

To get started with SAML assertions for multiple workspaces, you’ll first need to contact your account team (or reach out to us via this form) to enable the feature.

Once SAML assertions has been enabled, you will need map users to the correct Coda workspaces within your SAML SSO provider. For specific instructions on how to do so in Okta, check out this link. For Microsoft Entra ID, check out this link. If you use a different identity provider, the format for mapping should generally be as follows:

"attributes": {      
      ...   
      "http://schemas.microsoft.com/ws/2008/06/identity/claims/role": [
         "ws-Abcd1234",
         "ws-Abcd5678"      
      ],
...      
      "coda/workspaces": [    
         "ws-Abcd1234",      
         "ws-Abcd5678"     
      ]

Finally, you can complete the setup in your Coda admin settings, within the Workspace assignment tab. Scroll to the Workspace membership assignment setting, and select the Manage via SAML assertions option.

FAQs

What preparation steps should I go through prior to enabling SSO?

To ensure your users' continued access to Coda, ensure everyone in your workspace(s) are all logging into Coda via their company email address. Only accounts under the organization's list of managed domains will be able log in via SSO.

What happens to existing users when SSO is enabled?

Any user currently logging into Coda via an email address in a domain now managed by your Organization will be able to log in via SSO. They will continue to have access to existing workspaces, folders, and docs regardless of the mechanism they log in with.

Note that users will not be logged out of Coda automatically.

Who can enable and set up SAML SSO for my org?

Only Enterprise org admins can enable and set up SAML SSO. Learn more about org admins here.

Can I sign in with Google instead of SAML SSO?

Yes - if your organization uses Google Workspace identities to log in to Coda, then you can use Google’s built-in sign-in functionality as a login mechanism for Coda. This login method is available to customers on all subscription plans - Free, Pro, Team, and Enterprise. Org members can simply look for the “sign in with Google” option when logging into their Coda account.

Learn about other available sign-in methods here.

Can I have multiple forms of authentication enabled?

Yes, this is particularly useful during a transition from non-SSO to SSO-based authentication for testing or onboarding your company. Learn more about managing authentication options for your org here.

What happens when I deactivate or delete a user?

Deactivation of a user will log that user out (if they're currently logged in), prevent that user from logging back into Coda, and will stop accruing costs for that user (if they are a paid Doc Maker). Their docs will become read-only but could be migrated to new owners by org admins. For info on deactivating users and transferring doc ownership, check out this article.

How can I change ownership of a deactivated user's docs?

If you are an org admin, and one of your user's accounts has been deactivated via SCIM, you can transfer all their owned docs to another user in your organization. Learn more here.

How do I change a user’s first name/last name/email address?

You will need to update this information in your identity provider’s system. The updated information will be synced into Coda when the user next logs in.

A user’s first name/last name/email address is not properly displayed. How can I fix this?

Double check that you’ve properly mapped these attributes in your identity provider (i.e. “First name” in Google maps to FirstName). Coda displays the information sent from your identity provider, so the fix will need to be on the identity provider’s end.

Any general troubleshooting tips?

If you encounter errors when setting up SAML SSO, check to make sure your IDP's metadata, SAML requests and responses are valid XML against the SAML XSD schemas. You can do so using this online tool:

https://www.samltool.com/validate_xml.php

We also recommend testing the setup process with a test account before enforcing it for users.