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

# Prepare user groups

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

• Team members who 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've clearly defined your user groups, you can move on to setting up permissions.

Iterable defines user access permissions by roles. Roles must be set up as part of enabling single sign-on and assigning user access. When you need to do this varies:

• Authentication only: Create roles in Iterable at any time.
• Authentication and authorization: Create Iterable roles before creating a SAML app in your IdP. Create a JSON document to define permissions for each user group, and provide these documents to your IT administrator.

To create roles in Iterable, go to Settings > Roles. See Creating and Updating Custom Roles.

# Example

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

To accomplish this:

1. Your Iterable org admin creates:
   • Three roles in Iterable: Reader, Contributor, and Publisher. Each of these roles have necessary permissions to accomplish different tasks in each project.
   • JSON documents for four user groups: Director, Team Lead, US Marketer, and EMEA Marketer.
2. Your IT administrator creates:
   • Four user groups in your IdP, each using its own JSON document.
   • A fifth user group for org admins (this user group is defined without a JSON document).

# Define the roles attribute (optional)

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

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:

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

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

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

Because org admins have predefined access, you don't need to create a JSON document to apply their permissions.

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 and Google, 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. When formatted for display, 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.

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

# Name ID or application username

While Iterable doesn't require a Name ID attribute (application username, or user identifier), your identity provider might. In this case, add it either in SAML settings or as an attribute statement (depending on your IdP's requirement).

The value for the Name ID is always your IdP's field for email address, matching the value you enter for the email attribute above. However, it doesn't replace the email attribute, which is required for Iterable. Enter both in your IdP.

# Org ID

To find your organization's ID:

1. Log in to Iterable as a member with the Manage Settings permission.
2. Go to Settings > Project Members.
3. Your org ID displays directly under the page title. Use this value while entering SAML settings.

Example where the organization's ID is 00000:

• urn:auth0:iterable:saml-org-00000

• https://auth.iterable.com/login/callback?connection=saml-org-00000 (for USDC-based Iterable organizations), or https://auth.eu.iterable.com/login/callback?connection=saml-org-<YOUR_ORG_ID> (for EDC-based Iterable organizations)

# SAML metadata

SAML metadata is a block of XML that contains a security certificate and application information from your identity provider.

Sometimes your IdP may provide this as an .xml file, in which case you should open it with a text editor and copy/paste the XML into Iterable—there's no way to upload an XML file directly.

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>

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

To enable SSO:

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. For strict SAML, don't select any other login methods.

5. (Optional) Enter one or more SAML Domain, the domain for your company's email. To learn more about using this field, read SAML Domain.

6. (Required) Enter SAML Metadata. As provided by your IdP. See SAML Metadata above for an example.

7. Click Save.

# SAML Domain

The SAML Domain field is a setting that directs users from Iterable's login page to your IdP for SP-initiated authentication.

This field is optional. Leaving the SAML Domain field blank prevents SP-initiated login from Iterable's website, forcing users to use your IdP to log in.

When entering this field, you can:

• Enter a single domain or subdomain, like example.com or subdomain.example.com.
• Add more than one domain or subdomain, using a comma between them, like: example.com,domain.example,subdomain.example.net.

Don't use wildcards, like *.example.net, here.

# Manage users and permissions

This section reviews how to add, remove, and change user access whether you're using SSO for authentication alone, or with authorization.

# Authentication only

When you use SSO for authentication only, Iterable administrators manage users and their permissions, and IT administrators manage app access.

Provisioning

To provision members:

1. An Iterable org admin adds new members to Iterable and assigns them org permissions, project assignment, and role for each project.
2. Your IT administrator assigns app access in your IdP to each user or user group.

To de-provision members and remove access: IT administrators can remove privileges from your IdP. Iterable org admins may also revoke access from Iterable, for due diligence.

Changes

Iterable org admins make the following changes in Iterable with no impact to SSO:

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

# Authentication and authorization

With this setup, user management is primarily completed by IT administrators in your IdP.

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 administrators can remove privileges from your IdP. Iterable org admins may also revoke access from Iterable, for due diligence.

Changes

Iterable administrators can change Iterable role permissions at any time.

Changes that require SAML updates to roles attribute in your IdP:

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

# Further reading

Iterable documentation:

• Single Sign-On (SSO) Overview
• Single Sign-On Troubleshooting
• SSO Setup for Common Providers (Azure, Google, Okta)
• Permissions for Using Iterable
• Creating and Updating Custom Roles

Other resources:

• Wikipedia: Security Assertion Markup Language (SAML)