Once you've learned how SSO works for Iterable and you've planned your configuration, you can begin implementing it for your account.
NOTE
Setting up SSO can be straightforward or complex depending on the size of your organization and your security needs. Make sure to contact technical support if you need help!
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.
IMPORTANT
If your IdP doesn't accept JSON metadata for a SAML attribute, then you may need to omit the
roles
attribute and use SSO for authentication only.Configuration for more than one user group varies depending on your IdP. For Okta, Azure, and Google, we have more information in this article: SSO Setup for Common Providers (Azure AD, Google Workspace, Okta)
For more help, contact technical support.
Example
In this chart, an organization has five user groups with assignments based on their responsibilities.
User group | Iterable projects & roles | Org permissions | Roles attribute value (when used) |
---|---|---|---|
Administrator | All | All | orgadmin |
Director | Reader for Project A, Project B, Project C, Project D | Manage Billing, Manage Members, Manage Roles | JSON document |
Team Lead | Publisher for Project A, Project B, Project C, Project D | Manage Members, Create Projects, Manage Roles | JSON document |
U.S. Marketer | Publisher for Project A, Project B, Project D Reader for Project C | N/A | JSON document |
EMEA Marketer | Publisher for Project C Contributor for Project A, Project B, Project D | N/A | JSON document |
To accomplish this:
- 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.
- 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).
roles
attribute (optional)
Define the 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
NOTE
If you're enabling SSO for authentication only, you can skip this step. Proceed to add Iterable to your IdP.
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:
Log in to Iterable as an org admin and go to Settings > Authentication.
Select the org permissions for the given user group. (For most members, org permissions aren't necessary as they provide access to sensitive capabilities.)
-
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.
-
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.
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.
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.
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:
- Create a new SAML app for Iterable.
- Add Iterable's SAML settings.
- Add SAML attributes.
- Set up IdP user groups (recommended).
- Include the
roles
attribute for authorization only (optional).
- 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.
Setting | Value |
---|---|
Audience URI or Entity ID | urn:auth0:iterable:saml-org-<YOUR_ORG_ID> |
Single sign-on URL or Assertion Consumer Service (ACS) URL |
https://auth.iterable.com/login/callback?connection=saml-org-<YOUR_ORG_ID> (USDC-based projects) or https://auth.eu.iterable.com/login/callback?connection=saml-org-<YOUR_ORG_ID> (EDC-based projects) |
Name ID or Application username | The email address field for your IdP. This may or may not be required by your IdP and is optional for Iterable. Learn more below. The process for adding NameId varies with different IdPs. An alternative way to enter this field is to add it as an attribute of NameID . |
Name ID Format | The format of the name ID field. Use email address. This may or may not be required by your IdP and is optional for Iterable. |
Attribute statements
The values for each SAML attribute can vary depending on your IdP.
Attribute | Required | Description |
---|---|---|
email | Required | Your IdP's field for the member's email address |
firstName | Required | Your IdP's field for the member's first name |
lastName | Required | Your IdP's field for the member's last name |
roles | Optional | Used for authorization. See our instructions above for details. |
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:
- Log in to Iterable as a member with the Manage Settings permission.
- Go to Settings > Project Members.
- 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), orhttps://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.
IMPORTANT
Remember to test your SAML solution before turning off other authentication methods. De-selected methods are immediately disabled, so members may lose access if your SAML app isn't ready.
After a member's first SAML-based login, they can no longer log in with email and password.
To enable SSO:
Log in to Iterable with an account that has the Manage Members org permission.
Go to Settings > Authentication.
In the Authentication Policy section, click Edit Policy.
For Authentication Policy, select Single Sign-On (SSO) via SAML. For strict SAML, don't select any other login methods.
(Optional) Enter one or more SAML Domain, the domain for your company's email. To learn more about using this field, read SAML Domain.
(Required) Enter SAML Metadata. As provided by your IdP. See SAML Metadata above for an example.
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
orsubdomain.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.
NOTE
Previously, Iterable only supported a single domain for SP-initiated login. This is no longer the case. To learn more, read our release note, Enhancement to single sign-on (SSO) for users from multiple domains
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:
- An Iterable org admin adds new members to Iterable and assigns them org permissions, project assignment, and role for each project.
- 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: