Iterable provides three ways to authenticate users:
- Username and password
- Google Sign-In
- Single Sign-on (SSO) via SAML, 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 at least one authentication method:
-
Username and Password
When this is selected, users can log in to Iterable with their email address and a password that they have chosen.
This setting is enabled by default in new organizations.
-
Google Sign-In
This method allows users to authenticate with Google Sign-In (which means that their email addresses must correspond to a Google account).
NOTE
This authentication method doesn't restrict users by domain.
To log in with Google Sign-In, click Continue with Google on Iterable's login screen:
-
Single Sign-on (SSO) via SAML
This method 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.
To enable strict SAML, select this option and no others.
For detailed information about SAML, see the Single Sign-On via SAML, below.
IMPORTANT
Previously, when you selected SAML as an authentication method, you were then unable to disable SAML to use another method. This is no longer the case.
If you enable SAML and later need to turn it off, you can do this by de-selecting the authentication method on this page and choosing another.
There are two ways to use an identity provider to log in to Iterable:
-
On Iterable's login screen, click Log in with SSO:
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.
Single Sign-on (SSO) via 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:
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.
After a member's first SAML-based login, they can no longer log in with username and password. However, if Google Sign-In is enabled, they can continue to log in with Google if their email address supports it.
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 members 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 instead of a JSON object for org admins, (members who have all permissions on all projects). Note thatOrgAdmin
may need different casing such asorgadmin
, etc., depending on the provider.
NOTE
Different capitalizations of OrgAdmin
work for different providers. Use orgadmin
with Okta, OrgAdmin
with Microsoft.
-
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 (unless you're granting org-admin permisions, in which case just paste inOrgAdmin
or some version of it depending on the 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 permission.
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.