This guide describes some common errors, their solutions, and additional steps to troubleshoot problems when setting up and/or logging in to Iterable with single sign-on (SSO).
Like with SSO setup, these steps need both an Iterable org administrator and the IT administrator who manages your identity provider (IdP).
If you're unable to resolve your issue, contact technical support. See Working with Iterable Support.
In this article
When encountering challenges while setting up your SAML application and logging in to Iterable, try these steps:
In your IdP:
Error message: Value is invalid
This error relates to the SAML attributes entered in your IdP. The message reflects the SAML attribute name and value that's causing the issue.
Common mistakes include:
Incorrect or missing
Make sure the attribute name is
Your IdP may have a
username-type field, however for Iterable this value should always be set to your IdP's field for user email addresses (
This field is optional for Iterable, so if your IdP doesn't require it, you can omit it from your SAML setup. It does not replace the
Invalid string for the
When you use the SAML JSON Builder to define each role, Iterable provides a JSON document as output. Make sure to use the Copy to Clipboard button.
When you use the
roles, it is case-sensitive, and casing varies depending on your IdP.
For Okta, use
For Azure AD and Google, use
Once you've determined the cause of the error, you should:
Make the necessary changes to correct the SAML app settings in your IdP.
Generate new SAML metadata.
Replace the SAML metadata in Iterable. Instructions here.
Iterable asks for your password instead of directing to your identity provider
When you enter your email address to log in at https://app.iterable.com or https://app.eu.iterable.com, you're typically re-directed to your identity provider and then directed back to Iterable once you're authenticated.
If you're not redirected to single sign-on when you expect to be, and you are instead being prompted for a password, this experience may relate to the SAML Domain field in Iterable.
|The SAML Domain field is empty.||Ask your Iterable administrator to enter your domain in the Settings > Authentication page and try again.|
|The SAML Domain field is incorrectly formatted or spelled.||Ask your Iterable administrator to enter your domain in the SAML Domain field.
|The user's email address has a different domain than the SAML Domain set in Iterable, and the account is only set up for one domain.||Don't try to create or reset a password—nothing happens when you do this. Instead, ask your Iterable administrator to review your SAML Domain setting to make sure your email domain is listed.
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
To learn more about how the SAML Domain field works, read Setting up Single Sign On (SSO).
A user doesn't have the correct permissions when they log in to Iterable
Either a user is logging in and unable to see a new project, or they're missing permissions that an Iterable admin recently granted.
This can happen when:
An Iterable administrator made changes to a user's permissions in Iterable, while user permissions are granted by the
rolesattribute set with your identity provider.
The user has an incorrect group in your IdP.
The user group in your IdP has an incorrect or invalid JSON document in its
If your organization has included the
roles attribute with SAML app setup to
use your IdP for user authorization,
then user permissions must be updated by changing the JSON in your IdP's SAML
app, not in Iterable.
To make changes, create a new JSON document in Iterable and replace the
attribute JSON value for the user or user group in your IdP (wherever you've
Read Define the roles attribute to learn more.