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 easy or complex depending on the size of your organization and your security needs. Make sure to consult your Iterable customer success manager if you need help!
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:
- Skip steps 2 and 3 below.
- Have your IT administratoradd an Iterable app to your IdP, omitting the
roles
attribute, and copy the SAML metadata from your IdP. - Enable SSO in Iterable.
At any time, Iterable admins can create member roles in Iterable.
Provisioning
To provision members, an Iterable org admin:
- Creates Iterable project(s)
- Creates roles for each user group
- 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:
-
Define your organization's user groups and
create member roles in Iterable - Use Iterable's SAML JSON builder to prepare JSON documents for each user group.
- Your IT administrator can then add an Iterable app to your IdP,
including the
roles
attribute, and copy the SAML metadata from your IdP. - 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
IMPORTANT
If your IdP does't allow you to input JSON metadata for a SAML attribute,
then you may need to omit the roles
attribute and use SSO for authentication
only.
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.
User group | Iterable projects & roles | Org permissions | Roles attribute value (when used) |
---|---|---|---|
Administrator | All | All |
orgadmin or similar |
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:
- 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.
- 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).
roles
attribute (optional)
Step 3: Define the 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.
NOTE
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 Tips for Common Providers (Azure AD, Google Workspace, Okta)
For other IdPs, and for more help, contact your Iterable customer success manager.
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:
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. 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.
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.
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:
- 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> |
Name ID or Application username | The email address field for your IdP. |
Name ID Format | Email address. The value entered here depends on your IdP. |
NOTE
To find your organization's ID, log in to Iterable as a member with the Project Configuration > Manage Project Settings permission. Go to Settings > Project Members. Your org ID will be directly under the page title.
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. |
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.
NOTE
Need more help? Check out this article for some IdP-specific tips! SSO Tips for Common Providers (Azure AD, Google Workspace, Okta)
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.
IMPORTANT
Make sure 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.
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.
-
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
andexampleB.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 withexampleA.com
may log in from Iterable's login page (SP-initiated login). However, any member with another domain such asexampleB.com
can only log in through your IdP's interface (IdP-initiated login).
Enter SAML Metadata. Required. As provided by your IdP.
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:
Comments
0 comments
Article is closed for comments.