Single Sign-On (SSO) Overview

Iterable supports Security Assertion Markup Language (SAML)-based single sign-on (SSO). If you use choose to use this feature:

• You can use a third-party identity provider (IdP) to manage the member (user) account in your Iterable organization.
• Your users can use SSO to log in to Iterable.

As a SAML service provider, Iterable offers flexible configuration options and common use cases, such as strict SAML, just-in-time provisioning, and more.

# In this article

# Terms to know

There are quite a few technical terms and acronyms related to single sign-on. Here are some of the most common terms that you should know.

Term	What it means
Attribute	A data point contained in SAML metadata, such as first name, last name, and email address.
Authentication	Confirming a user's identity and granting access to a service provider such as Iterable.
Authorization	Granting permissions to a service provider.
IdP	Identity Provider. A service that stores and verifies a user's identity. Examples: Okta, OneLogin
IdP-initiated login	When a SSO-registered user accesses Iterable from their identity provider. The identity provider then forwards the user to Iterable for access.
Iterable org admin	A universal administrator in Iterable that automatically has all org permissions and all role permissions for all projects. Org admins are defined differently than other user groups when using the roles attribute. See Setting up Single Sign-On (SSO) for full details.
Iterable roles	Permission sets in Iterable that define what a user can do within a project. These are defined and managed by an Iterable org admin in Iterable. Not to be confused with the roles SAML attribute (read more on this below).
JIT provisioning	Just-in-time provisioning. A SAML protocol that creates users and updates their permissions whenever a user logs in to Iterable. This applies when you use SSO for authorization, which is optional.
JSON document	A set of key-value pairs used to define objects. Iterable uses JSON documents to define the roles attribute for non-administrative users.
roles SAML attribute	A defined set of permissions for an Iterable user or group of users. Not to be confused with Iterable roles (read more on this below).
SAML	Security assertion markup language. A standardized set of XML definitions that pass authentication information between your identity provider and Iterable.
SAML metadata	A specific dataset that includes identifying information and security keys for your identity provider. Your IdP provides this metadata, which you enter in Iterable during SSO setup.
SP	Service provider. An entity that accepts authentication via SSO from a trusted identity provider. In this case, Iterable is your service provider.
SP-initiated login	When a SSO-registered user accesses Iterable from the app login page, https://app.iterable.com or https://app.eu.iterable.com. Iterable detects that the user needs SSO authentication based on their email domain, and forwards data to your IdP. Then your IdP forwards the user to Iterable for access.
SSO	Single sign-on. A solution provided by an identity provider which allows a user to access multiple service providers while using a single email and password.
Strict SAML	A way to set up your single sign-on experience that requires members to access Iterable by logging in with SSO. All other login methods are disabled.

# Authentication vs authorization

Work with your team and decide whether to use your IdP for authentication (login only), or for authentication and authorization (login and role management).

# Authentication only

When you set up your identity provider to authenticate users, they can log in using SSO. IT admins manage access to Iterable, while Iterable org admins manage project assignments, roles, and permissions.

When using your IdP for authentication only:

• Iterable org admins create new members and manage their roles and permissions directly in Iterable. To learn more about member management in Iterable, read Creating and Updating Member Roles.

• IT admins provision app access for each member in your IdP so they can log in with SSO.

# Authentication and authorization with just-in-time provisioning

When you use your IdP for authorization and authentication:

• IT admins add and manage members in your IdP.

  • The roles SAML attribute determines org permissions, project assignments, and Iterable roles.
  • When your IT admin assigns Iterable to a new member in your IdP, an automated process creates the member's account on their first login.
  • After a member's first SAML-based login, they can no longer log in with their email and password.
  • IdP-based changes to a member's assigned projects and roles take effect the next time the log in to Iterable.

• Iterable org admins add and manage Iterable roles.

  • Changes made to the name of a role in Iterable must be made in SAML, too. Otherwise, members who are assigned the role may not be able to access their projects.

• To change the set of permissions included in a given role, use Iterable. Such changes have no impact on your SAML configuration. In other words, SAML maps users to Iterable roles — but Iterable maps roles to specific permissions.

• If you modify a user's role directly in Iterable, those changes become overridden the next time that users logs in with SSO. In other words, your IdP is the source of truth for users and roles, even if you make changes in Iterable.

# Access variations

Iterable SSO offers flexibility with user access in several ways.

# Strict SAML

With strict SAML, members can only access Iterable by logging in with SSO.

# Multiple domains

Iterable supports SSO for users from multiple domains. To do this, simply enter a comma-delimited list of domains or subdomains in the SAML Domain field.

# Combined login and security methods

With combined access, you can choose to authenticate and authorize users from two or more sources.

SSO and Google Sign-In

When this is set up, members enrolled in SSO may also sign in using Google Sign-In, (if they use a Google-based email address).

SSO and Username & Password

When you use these two methods, Iterable org admins can add and manage non-SSO members directly in Iterable. This is useful if you have a division with an email domain different from your main organization, for example.

Managing Iterable members:

• IT admins manage members and assign roles, projects, and permissions for those who log in with SSO.
• Iterable org admins can add and manage members and their permissions for any members who use a different email domain and/or don't use SSO for some reason.

Logging in to Iterable:

• Members who are enrolled for SSO via your IdP can log in two ways:
  • Directly from your IdP, such as an Okta tile (IdP-initiated login).
  • From Iterable's login page, which redirects to your IdP for authorization (SP-initiated login).

SSO and two-factor authentication

Using SSO is independent of using Iterable's two-factor authentication (2FA). These are managed separately.

To learn more about Iterable 2FA, read Two-Factor Authentication for Login.

# Iterable roles vs SAML roles

The roles SAML attribute doesn't directly correlate with roles in Iterable, however they are related.

# Iterable roles

An Iterable role contains permissions that apply to a single project. An Iterable member may have a different role for each assigned project.

To learn more about Iterable roles and their associated permissions, read Roles and Permissions.

# SAML roles attribute

IT admins enter the SAML roles attribute in Iterable's SAML app in your IdP. Iterable uses the information contained in this attribute to determine a member's entire set of permissions. Only use this attribute if you are setting up SSO for authorization and just-in-time provisioning.

For org admins, the value is usually orgadmin or OrgAdmin depending on your IdP.

For users that aren't org admins, the value of this attribute is a JSON document that you create during the setup process. The JSON document contains:

• Member org permissions.
• Project assignments.
• The Iterable role assigned for each project.

# Next steps

Once you are ready to begin implementing SSO for Iterable, go to Setting up Single Sign-On (SSO) for instructions.

# Further reading

Iterable documentation:

• Setting up Single Sign-On (SSO)
• Single Sign-On Troubleshooting
• SSO Setup for Common Providers (Azure, Google, Okta)
• Roles and Permissions
• Creating and Updating Custom Roles

Other resources:

• Wikipedia: Security Assertion Markup Language (SAML)