Iterable provides three ways to authenticate users:
- Username and password
- Google Sign-In
- SAML-based single sign-on (SSO), using an identity provider (IdP) such as Okta
This document describes these options and how to set them up.
Table of contents
Choosing an authentication scheme for your Iterable organization
To select an authentication scheme for your Iterable organization:
Log in to Iterable as a member that has the Manage Members org permission.
Navigate to to Settings > Authentication.
In the Authentication Policy section, click Edit Policy.
-
Select an authentication scheme:
-
Default (Email Address and Password)
This option requires members in your Iterable organization to log in using Iterable-specific usernames and passwords.
With this option enabled, eligible users can also log in to Iterable using Google Sign-In.
-
Require Google Sign-In
This option requires that users authenticate with Google Sign-In (which means that their email addresses must correspond to a Google account). With this option enabled, users cannot log in with username and password.
To log in with Google Sign-In, click Sign In with Google on Iterable's login screen:
-
SAML
This option authenticates users with SAML from a third-party identity provider, such as Okta, which can be used to provide single sign-on. To configure this option, you'll need to provide a SAML domain and SAML metadata. For detailed information about SAML, see the next section.
IMPORTANT
Once you select SAML and save changes, it is not possible to revert the selected option back to Default (Email Address and Password) or Require Google Sign-In.
There are two ways to use an identity provider to log in to Iterable:
-
On Iterable's login screen, click Log In Via Your Identity Provider:
Then, enter your email address, click Submit, and authenticate with your identity provider as necessary.
Alternatively, log in to Iterable directly through your identity provider.
-
-
Click Save Changes.
SAML
Iterable's SAML support allows a third-party identity provider to manage your organization's member accounts. With SAML:
Your identity provider authenticates and authorizes your Iterable users, who no longer need to remember Iterable-specific usernames and passwords.
When people leave your company, you can disable their accounts in your identity provider.
Iterable supports any SAML-compatible identity provider. For example:
To use SAML authentication, you'll need to:
- Understand the implications of enabling SAML authentication
- Configure your identity provider to work with Iterable
- Configure Iterable to work with your identity provider
Implications of enabling SAML authentication
After enabling SAML authentication for an Iterable organization:
You cannot revert that organization to username and password or Google Sign-In authorization.
Until a member logs in with SAML, they can stil log in with userame and password or Google Sign-In, as applicable.
After a member's first SAML-based login, they can no longer log in with username and password. However, they can continue to log in with Google Sign-In if their email address supports it.
When a member logs in to Iterable through a SAML-based identity provider, Iterable treats that SAML as the source of truth that specifies the member's projects and roles. Each SAML login updates Iterable's understanding of the user's projects and roles.
Changes to a member's projects and roles, made in the identity provider, are available to that member when they next log in with Iterable.
Two-factor authentication and SAML
Iterable supports two-factor authentication, which requires logging in members to enter a code from an authenticator app:
For members who have enabled two-factor authentication, Iterable asks for the code entry after the identity provider login process is complete.
Iterable's two-factor authentication is separate from the two-factor authentication which may or may not be enabled for your organization's identity provider.
Configuring your identity provider to work with Iterable
The following sections describe how to configure your identity provider to work with Iterable.
Iterable SAML settings
In your identity provider, use the following SAML settings for Iterable:
- Single sign-on URL:
https://app.iterable.com/authenticate/saml?orgId=<YOUR_ORG_ID>
. Replace<YOUR_ORG_ID>
with the your organization's ID (found by navigating to Settings > Project in Iterable). - Audience URI (SP entity ID):
https://app.iterable.com/authenticate/saml
- Name ID format:
EmailAddress
- Application username:
Email
Attribute statements
Configure your identity provider to include the following attribute statements for Iterable members:
-
firstName
: the member's first name -
lastName
: the member's last name -
email
: the member's email address -
roles
: for details, see Roles
Roles
The roles
property designates the Iterable projects to which a member belongs
and their role on each. It can have one of two formats:
OrgAdmin
: Use this value for org admins, (members who have all permissions on all projects).-
A SAML snippet generated by Iterable's SAML JSON Builder, found on the Settings > Authentication screen.
To use this tool to specify a member's permissions:
Select the org permissions the member should have. For most members, org permissions are not necessary (since they provide access to sensitive capabilities).
For each project to which the member should belong, select a role. The drop-down menu contains the custom roles defined for your Iterable organization. When using this tool, you must select a role for at least one project.
-
To copy the SAML, click Copy to Clipboard. For example, the copied SAML might look similar to the following:
{ "orgPermissions": [ "Manage billing", "Manage members" ], "projectRoles": [ { "projectId": 5, "role": "Contributor" }, { "projectId": 14, "role": "Account manager" } ] }
To avoid errors, don't select and copy the JSON. Instead, use the Copy to Clipboard button.
Use the copied SAML as the user's
roles
attribute in your identity provider.
IMPORTANT
If you change the name of a role, you must make SAML updates for any users who have that role. Until you do so, those user will not be able to log in to Iterable.
Old roles format
Before the introduction of Custom Roles,
Iterable used a different roles
SAML format: a comma-separated mapping of
project IDs to roles. This format only supported a pre-defined set of roles:
Reader
, Contributor
, Publisher
, AccountManager
and Admin
. For example:
42:Contributor, 93:Publisher
When migrating to custom roles,
Iterable created new, custom roles to mimic the original, pre-defined roles—and
assigned these new custom roles to members in a sensible way based on their
original roles. If you're still using an SSO roles
SAML snippet defined before
the existence of custom roles, the role names in that snippet now refer to the
new, custom roles created during the migration (rather than the original roles of
the same name).
For backwards compatibility, Iterable still supports the old roles
SAML format,
but only for organizations that have not changed the names of the default custom
roles created when migrating to custom roles.
IMPORTANT
If you're using the old SAML format, you must update to the new format if:
- You modify the names of the default custom roles.
- Your SAML must reference any newly created custom roles.
The old
roles
format works only for the original, unmodified role names.
Okta example
In Okta, an Iterable configuration should look similar to the following:
Okta groups
Rather than using a static value for the roles
property, Okta allows
administrators to define this property for groups. This enables them to define
different roles for different groups of users in their organizations.
-
From the Okta admin console, navigate to Directory > Profile Editor and click the Profile button next to the Iterable app.
-
Click Add Attribute and fill it in as necessary. Make sure to set the following values:
-
Variable Name:
roles
- Attribute Required: Yes
-
Variable Name:
-
Return to the Assignments tab in the Iterable application. Assign a group, then click the Edit button.
-
Set the roles property as desired for this group. For example:
-
On the General tab, click SAML Settings > Edit. Click Next to get to the Configure SAML step.
-
Set the value of the
roles
user attribute toappuser.roles
Configuring Iterable to work with your identity provider
To configure Iterable to use a third-party identity provider to authenticate your members, follow these steps:
-
Locate your identity provider's SAML metadata for Iterable.
SAML metadata is a block of XML that contains certificate and application information from your identity provider. It should look similar to the following:
<?xml version="1.0" encoding="UTF-8"?> <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="http://www.okta.com/blahblah"> <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> <md:KeyDescriptor use="signing"> <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:X509Data> <ds:X509Certificate> SEqwY8cFuVvOjUuZJ/bhzIAW8W/oZZJkL3qD96uJzlhf1dZN3MnttFhMahKAahlNU2Kd9/Qznz2+ kdljGHs/x7AEfFbe4mEpKi52aZAFD8gcZv4s3wnCMgzndTqEn7dx+4kVtGEh6NAzJfMVgLk50ybb l6otY3x6m72Jk6zhTKYZHMM9k99sWWs+T3ewq6mbVGMNNk54JdmUtzf42MxT/b9bIvLhVYDqzswy CFVP7oNN8VmjaI+c6BC89WYthX8gflknlC2PFQa+G4LddERIPLxTDEfQWVONoKHJhxotRvb1HLp2 Jzlhf1dZN3MnttFhMahKAahlNU2Kd9/Qznz2+SEqwY8cFuVvOjUuZJ/bhzIAW8W/oZZJkL3qD96u CMgzndTqEn7dx+4kVtGEh6NAzJfMVgLk50ybbkdljGHs/x7AEfFbe4mEpKi52aZAFD8gcZv4s3wn bVGMNNk54JdmUtzf42MxT/b9bIvLhVYDqzswyl6otY3x6m72Jk6zhTKYZHMM9k99sWWs+T3ewq6m UuZJ/bhzIAW8W/oZZJkL3qD96uJzlhf1dSEqwY8cFuVvOjZN3MnttFhMahKAahlNU2Kd9/Qznz2+ Fbe4mEpKi52aZAFD8gcZv4s3wnCMgzndTkdljGHs/x7AEfqEn7dx+4kVtGEh6NAzJfMVgLk50ybb 6zhTKYZHMM9k99sWWs+T3ewq6mbVGMNNkl6otY3x6m72Jk54JdmUtzf42MxT/b9bIvLhVYDqzswy I+c6BC89WYthX8gflknlC2PFQa+G4LddECFVP7oNN8VmjaRIPLxTDEfQWVONoKHJhxotRvb1HLp2 tFhMahKAahlNU2Kd9/Qznz2+SEqwY8cFuJzlhf1dZN3MntVvOjUuZJ/bhzIAW8W/oZZJkL3qD96u +4kVtGEh6NAzJfMVgLk50ybbkdljGHs/xCMgzndTqEn7dx7AEfFbe4mEpKi52aZAFD8gcZv4s3wn tzf42MxT/b9bIvLhVYDqzswyl6otY3x6mbVGMNNk54JdmU72Jk6zhTKYZHMM9k99sWWs+T3ewq6m +G4LddERIPLxTDEfQWVONoKHJhxotRvb1HLp2CFVP7oNN8VmjaI+c6BC89WYthX8gflknlC2PFQa hDsLV9h/c5As5qx7/zSOLmoG3W+LoABOHiXo== </ds:X509Certificate> </ds:X509Data> </ds:KeyInfo> </md:KeyDescriptor> <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat> <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://some.url/sso/samle"/> <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://some.url/sso/samle"/> </md:IDPSSODescriptor> </md:EntityDescriptor>
You must provide this information to Iterable. To find it, look in your identity provider.
For example, in Okta, click Identity Provider Metadata on the Sign On tab of your application's configuration page:
-
Determine your organization's SAML domain.
For example, if your members have email addresses such as
user@example.com
, the SAML domain isexample.com
. Log in to Iterable with an account that has the Manage Members org permisson.
Navigate to Settings > Authentication.
In the Authentication Policy section, click Edit Policy.
-
For Authentication Policy, select SAML.
WARNING
After configuring your organization to use SAML, you cannot revert to username and password. Before making this change, be sure that you're ready to do so.
Enter the SAML Domain and SAML Metadata you found above.
Click Save Changes.
Further reading
Iterable documentation:
Other resources:
Comments
0 comments
Article is closed for comments.