Authentication Options: Username and Password, Google Sign-In and SAML SSO

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:

1. Log in to Iterable as a member that has the Manage Members org permission.

2. Navigate to to Settings > Authentication.

3. In the Authentication Policy section, click Edit Policy.

4. 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 Continue 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 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.

5. 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:

• Okta
• ADFS
• OneLogin

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 still log in with username 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 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 that OrgAdmin may need different casing such as orgadmin, etc., depending on the provider.

• 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:

  1. Select the org permissions the member should have. For most members, org permissions are not necessary (since they provide access to sensitive capabilities).

  2. 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.

  3. 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.

  4. 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 in OrgAdmin or some version of it depending on the provider.)

# 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.

# 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.

1. From the Okta admin console, navigate to Directory > Profile Editor and click the Profile button next to the Iterable app.

   

2. Click Add Attribute and fill it in as necessary. Make sure to set the following values:

   • Variable Name: roles
   • Attribute Required: Yes

   

3. Return to the Assignments tab in the Iterable application. Assign a group, then click the Edit button.

   

4. Set the roles property as desired for this group. For example:

   

5. On the General tab, click SAML Settings > Edit. Click Next to get to the Configure SAML step.

   

6. Set the value of the roles user attribute to appuser.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:

1. 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:

   

2. Determine your organization's SAML domain.

   For example, if your members have email addresses such as user@example.com, the SAML domain is example.com.

3. Log in to Iterable with an account that has the Manage Members org permission.

4. Navigate to Settings > Authentication.

5. In the Authentication Policy section, click Edit Policy.

6. 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.

   

7. Enter the SAML Domain and SAML Metadata you found above.

8. Click Save Changes.

# Further reading

Iterable documentation:

• Account Roles and Permissions
• Creating and Updating Custom Roles
• Two-Factor Authentication

Other resources:

• Okta
• ADFS
• OneLogin
• Wikipedia: Security Assertion Markup Language (SAML)