Setting up Single Sign-On (SSO)

Once you've learned how SSO works for Iterable and you've planned your configuration, you can begin implementing it for your account.

# In this article

# Key considerations

Before you start, make sure your organization is aware of these caveats when enabling SAML authentication:

• Iterable uses email address as the username field. This means that Iterable members (users) must use the same email address associated with their IdP account to log in to Iterable.
• After a member's first SAML-based login, they can no longer log in with email and password. However, if Google Sign-In is enabled, they can continue to log in with Google if their email address supports it.
• Using SAML is completely independent of two-factor authentication in Iterable. These are managed separately. To learn more, read Two-Factor Authentication for Login.

Additional considerations will vary depending on your setup.

# Step 1: Plan your SSO implementation

Setup will vary depending on whether you plan to use your IdP for authentication only or authentication and authorization, as well as strict SAML.

# Authentication only

Setting up

To set up SSO for authentication only, skip step 3 below and leave the roles attribute out of your IdP configuration. You won't need to create JSON documents, either.

To set up authentication only with your identity provider:

1. Skip steps 2 and 3 below.
2. Have your IT administratoradd an Iterable app to your IdP, omitting the roles attribute, and copy the SAML metadata from your IdP.
3. Enable SSO in Iterable.

At any time, Iterable admins can create member roles in Iterable.

Provisioning

To provision members, an Iterable org admin:

1. Creates Iterable project(s)
2. Creates roles for each user group
3. Adds new members to Iterable, including org permissions, project assignment, and role for each project.

Then, IT administrators assign app access in your IdP so these users can sign in.

To de-provision members and remove access, IT admins can revoke access in your IdP.

Changes

Iterable org admins can make the following changes with no updates needed in your IdP:

• Project assignments
• Iterable role assignments
• Names of Iterable roles
• Iterable role permissions
• Org permissions for each member

# Authentication and authorization

To set up authentication and authorization with your identity provider:

1. Define your organization's user groups and
   create member roles in Iterable
2. Use Iterable's SAML JSON builder to prepare JSON documents for each user group.
3. Your IT administrator can then add an Iterable app to your IdP, including the roles attribute, and copy the SAML metadata from your IdP.
4. Enable SSO in Iterable.

Provisioning

To provision members, an IT administrator provides app access from your IdP. The member's first login creates their account in Iterable.

To de-provision members and remove access, IT admins can revoke privileges from your IdP.

Changes

Iterable administrators can change Iterable role permissions at any time.

All of the following changes require SAML updates to roles attribute in your IdP:

• Project assignments
• Iterable Role assignments
• Names of Iterable roles
• Org permissions

# Strict SAML

To enable strict SAML, manage your SSO configuration in Iterable:

• Select Single Sign-On (SSO) via SAML and no other methods when you set an authentication policy.
• Enter the domain that requires strict SAML in the SAML Domain field of Iterable's SSO settings. This redirects users with that domain to log in from your IdP (SP-initiated login).

# Step 2: Define user groups

Plan out the overall team roles and permissions for your organization. Make a list that includes:

• Team members who will use Iterable.
• What org permissions they should have—if any.
• Which projects they should have access to.
• Which Iterable role members should have for each project.
• Which permissions each Iterable role should have.

Once you have clearly defined your user groups, you'll want to create roles in Iterable. Iterable org admins create member roles by going to Settings > Roles.

For complete instructions, see Creating and Updating Custom Roles.

If you're enabling SSO for authentication only, you can create roles in Iterable at any time.

For authentication and authorization, complete this step before your IT administrator adds Iterable to your IdP, so you can provide the required JSON document for each user group.

# Example

In this chart, an organization has 5 different user groups with assignments based on their responsibilities.

To accomplish this:

1. Your Iterable org admin creates:

• 3 roles in Iterable: Reader, Contributor, and Publisher
• Each of these roles have necessary permissions to accomplish different tasks in each project.
• JSON documents for 4 user groups: Director, Team Lead, US Marketer, and EMEA Marketer.

2. Your IT administrator creates:
   • 4 user groups in your IdP using those JSON documents
   • A 5th user group for org admins (this user group is defined without a JSON document).

# Step 3: Define the roles attribute (optional)

Applying the roles SAML attribute will enable your IdP to create members and authorize them using just-in-time provisioning.

If you're enabling SSO for authentication only, you can skip this step.

For each member, the roles attribute defines:

• Org permissions
• Iterable projects
• Roles on each Iterable project

When you add the roles attribute to your IdP, the value that you enter varies depending on which user group you're authorizing and how your IdP works.

Some ways to assign roles to users in your IdP include:

• Enter the attribute directly for each user level
• Creating IdP groups and assigning users to a group

Additionally, Iterable can only read a single roles attribute at a time, so you should only enter one statement in your IdP per user or group.

# Org Admins

Itetable org admins have access to all projects and all permissions.

Because org admins are predefined with universal access, you don't need to create a JSON document to apply permissions for org admins.

When entering roles for these users, use OrgAdmin as the value.

Note that different capitalizations of OrgAdmin work for different providers:

• For Okta, use orgadmin.
• For Azure AD, use OrgAdmin.

# Non-administrators

When you enter the roles attribute in your IdP, enter the JSON output generated by Iterable's SAML JSON Builder, located on the Settings > Authentication screen.

To build the JSON document:

1. Log in to Iterable as an org admin and go to Settings > Authentication.

2. Select the org permissions for the given user group. (For most members, org permissions aren't necessary as they provide access to sensitive capabilities.)

3. For each project the member(s) should belong to, 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.

4. To copy the JSON document, scroll to the bottom of the page to find JSON Output and click Copy to Clipboard. For example, the copied JSON might look similar to this:

   {
     "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.

5. Use the copied JSON document as the member's or group's roles attribute in your identity 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.

# Step 4: Add Iterable to your IdP

When you're ready to add Iterable to your IdP, have your IT administrator log in to your IdP and do the following:

1. Create a new SAML app for Iterable
2. Add Iterable's SAML settings
3. Add SAML attributes
   • Set up IdP user groups (recommended)
   • Include the roles attribute for authorization only (optional)
4. Find and copy the SAML Metadata for your new app, and provide this to your Iterable org admin.

# SAML settings

In your IdP, use the following SAML settings for Iterable. Replace <YOUR_ORG_ID> with your organization's ID.

# Attribute statements

The values for each SAML attribute can vary depending on your IdP.

Your IdP may require another field for a user identifier. This will be the same value as email in the above chart, and does not replace the email attribute.

# SAML Metadata

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.exampleIdP.com/some-url">
<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>
SSBsaWtlIHRvIGNyZWVwIGFyb3VuZCBteSBob21lIGFuZCBhY3QgbGlrZSBhIGdvYmxpbgoKSSBkb27igJl0IGtub3cgd2h5IGJ1dCBJIGp1c3QgZW5qb3kgZG9pbmcgdGhpcy4gTWF5YmUgaXTigJlzIG15IHdheSBvZiBkZWFsaW5nIHdpdGggc3RyZXNzIG9yIHNvbWV0aGluZyBidXQgSSBqdXN0IGRvIGl0IGFib3V0IG9uY2UgZXZlcnkgd2Vlay4gR2VuZXJhbGx5IEnigJlsbCBjYXJyeSBhcm91bmQgYSBzYWNrIGFuZCBjcmVlcCBhcm91bmQgaW4gYSBzb3J0IG9mIGNyb3VjaC13YWxraW5nIHBvc2l0aW9uIG1ha2luZyBnb2JsaW4gbm9pc2VzLCB0aGVuIEnigJlsbCB3YWxrIGFyb3VuZCBteSBob3VzZSBhbmQgcGljayB1cCB2YXJpb3VzIGRpZmZlcmVudCDigJx0cmlua2V0c
</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>

# Step 5: Enable SSO in Iterable

Once your IdP's SAML app is ready and your IT administrator has provided the associated SAML metadata, enable SSO in Iterable.

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

2. Go to Settings > Authentication.

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

4. For Authentication Policy, select Single Sign-on (SSO) via SAML.

5. Enter a SAML Domain. Optional. The base URL for your company's email domain, such as example.com. Adding your company's email domain allows SP-initiated logins from Iterable's login page.

   • This field is necessary for strict SAML.
   • Leaving the domain blank prevents SP-initiated login.
   • Only one domain is permitted in this field.

   NOTE

   If you need to provide SSO for members with more than one email domain (such as exampleA.com and exampleB.com), you can either:

   • Leave the SAML Domain field blank. If you do this, however, all members can only log in through your IdP's interface (IdP-initiated login).
   • Enter your primary domain in the SAML Domain field (exampleA.com). Members with exampleA.com may log in from Iterable's login page (SP-initiated login). However, any member with another domain such as exampleB.com can only log in through your IdP's interface (IdP-initiated login).

6. Enter SAML Metadata. Required. As provided by your IdP.

7. Click Save Changes.

# Further reading

Iterable documentation:

• Single Sign-on (SSO) Overview
• SSO Tips for Common Providers (Azure AD, Google Workspace, Okta)
• Roles and Permissions
• Creating and Updating Custom Roles

Other resources:

• Wikipedia: Security Assertion Markup Language (SAML)