Articles in this section

Single Sign-On (SSO) Troubleshooting

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

General troubleshooting

When encountering challenges while setting up your SAML application and logging in to Iterable, try these steps:

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 email attribute, and/or incorrect attribute name.

    Make sure the attribute name is email and the value is set to the field that your IdP uses for email addresses (email, emailAddress, e-mail, etc). Fields are case-sensitive, and this attribute is required (even if you're using a Name ID attribute as well).

  • Incorrect NameID attribute.

    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 (email, emailAddress, e-mail, etc.). Fields are case-sensitive.

    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 email attribute, which is required.

  • Invalid string for the roles attribute.

    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 orgadmin value for roles, it is case-sensitive, and casing varies depending on your IdP.

    • For Okta, use orgadmin.

    • For Azure AD and Google, use OrgAdmin.

Once you've determined the cause of the error, you should:

  1. Make the necessary changes to correct the SAML app settings in your IdP.

  2. Generate new SAML metadata.

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

Possible Cause Solution
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.

Use example.com, not https://www.example.com.
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 roles attribute 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 roles attribute.

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 roles attribute JSON value for the user or user group in your IdP (wherever you've assigned it).

Read Define the roles attribute to learn more.

Further reading

Related articles