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
- Authentication vs authorization
- Access variations
- Iterable roles vs SAML roles
- Next steps
- Further reading
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.
|What it means
|A data point contained in SAML metadata, such as first name, last name, and email address.
|Confirming a user's identity and granting access to a service provider such as Iterable.
|Granting permissions to a service provider.
|Identity Provider. A service that stores and verifies a user's identity.
Examples: Okta, OneLogin
|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.
|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).
|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.
|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).
|Security assertion markup language. A standardized set of XML definitions that pass authentication information between your identity provider and Iterable.
|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.
|Service provider. An entity that accepts authentication via SSO from a trusted identity provider. In this case, Iterable is your service provider.
|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.
|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.
|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).
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.
rolesSAML 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.
- If your IdP doesn't allow you to input JSON metadata for a SAML attribute,
then you may need to omit the
rolesattribute and use SSO for authentication only.
- Iterable doesn't support System for Cross-domain Identity Management (SCIM) provisioning
Iterable SSO offers flexibility with user access in several ways.
With strict SAML, members can only access Iterable by logging in with SSO.
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.
Previously, Iterable only supported a single domain for SP-initiated login. This is no longer the case. To learn more, read our release note, Enhancement to single sign-on (SSO) for users from multiple domains
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 SAML attribute doesn't directly correlate with roles in Iterable,
however they are related.
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.
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 depending on your
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.
Once you are ready to begin implementing SSO for Iterable, go to Setting up Single Sign-On (SSO) for instructions.
- 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