SSO Setup for Common Providers (Azure, Google Workspace, Okta)

This guide provides general instructions to add an Iterable SAML application to some of the most common identity providers: Azure Active Directory, Google Workspace, and Okta.

Adding a SAML app is one step towards creating a single sign-on integration with Iterable. For complete instructions, read Setting up Single Sign-On (SSO).

If you need more help, check out Single Sign-On Troubleshooting, or contact Iterable Support. See Working with Iterable Support.

# In this article

# Azure Active Directory

To add an Iterable application in Azure AD:

1. Create a new Enterprise application. Choose to create your own application and select the option for a non-gallery app.

2. Manage Single Sign-on for the app and choose SAML as the sign-on method.

3. For Basic SAML Configuration, add the necessary SAML settings.

4. For Attributes & Claims, add the necessary claims and values.

5. When ready, download the Federation Metadata XML and provide this to your Iterable org admin, who finishes by enabling SSO in Iterable.

For additional reference, see also Microsoft Azure Application management documentation.

# SAML settings for Azure AD

Setting	Value
Identifier (Entity ID)	urn:auth0:iterable:saml-org-<YOUR_ORG_ID>
Reply URL (Assertion Consumer Service 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)

# Attributes and claims

Claim Name	Value
Unique User Identifier (Name ID)	user.mail
email	user.mail
firstName	Your Azure field for first name, such as user.givenname
lastName	user.surname
roles	Optional. Omit for authentication only. For authorization, see Azure AD users and groups for details.

# Azure AD users and groups

Ask your Iterable org admin for a SAML JSON document for each user group they created in Iterable. (There is no JSON document for administrators.)

To add or edit a user group in Azure AD:

1. From Azure AD, find your Iterable application's Users and Groups area.

2. Add a new group to represent each role, including Iterable administrator. You can add members to the group now or later.

3. Go back to your app's single sign-on settings and edit attributes and claims.

4. Add a new claim with a Name of roles.

5. Under Claim Conditions, select "Members" as the User Type, and for Source select "Attribute".

6. For Scoped Groups, select the role you are providing access for.

7. In the Value field, add the JSON document associated with the role. Use OrgAdmin as the value for your Iterable org administrators.

Repeat steps 5-7 for each user group you're creating.

# Google Workspace

To add a new app for Iterable in Google Workspace:

1. Add a custom SAML app.

2. Enter App Details, including App Name of Iterable and a Description.

3. For Settings, add the necessary SAML settings.

4. For Attribute Mappings, enter the necessary directory and app attributes.

   To set user roles in Google Workspace, add a custom user attribute, then add the roles attribute to the SAML app mapping.

5. When ready, download the IdP Metadata and provide this to your Iterable org admin, who finishes by enabling SSO in Iterable.

For additional reference, see Set Up Your Own Custom SAML Application (Google help).

# SAML settings for Google Workspace

Setting	Value
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)
Entity ID	urn:auth0:iterable:saml-org-<YOUR_ORG_ID>
Name ID Format	EMAIL
Name ID	Basic Information > Primary Email

# Attribute mapping

Google Directory attribute	App attribute
Primary email	email
First Name	firstName
Last Name	lastName
Iterable Role	roles

To add the Iterable Role Directory attribute, first create it as a custom user attribute, then go back to the custom SAML app attribute mappings and enter the App attribute value (roles).

# Google custom user attributes

Ask your Iterable org admin to provide the SAML JSON document that they created in Iterable for each user group.

Next, add custom user attributes for each Iterable member.

1. In Google Admin, add a new custom attribute.

   • Category: SAML Attributes (or any name you assign)

   • Custom Fields:

     • Name: Iterable Role
     • Info type: Text
     • Visibility: Visible to organization
     • Number of Values: Single value

2. Go back to the Iterable SAML app that you created, and add the Iterable Role attribute mapping (see attribute chart).

3. Next, provide permissions to each user by adding a value to the Iterable Role attribute. Enter either:

   • The JSON document associated with the user's appropriate user group.
   • OrgAdmin, for your Iterable org administrators.

4. Save and repeat for each user.

# Okta

To add an Iterable integration to Okta:

1. Create a new SAML app integration.

2. For General settings, add the necessary SAML settings.

   When entering the Single Sign-on URL, check the box for Use this for Recipient URL and Destination URL

3. For Attribute Statements, add the necessary attribute names and values.

4. After you're done creating the integration, go to the Sign-On tab to find the View SAML Setup Instructions button and click on it. Scroll to the bottom and copy the IdP metadata that starts with <?xml version=1.0" encoding="UTF-8"?>. Provide this text to your Iterable org admin, who uses this to enable SSO in Iterable.

When setting up Okta, remember that field names are case-sensitive.

For additional reference, see Create SAML App Integrations (Okta Help Center).

# SAML settings for Okta

Setting	Value
Single Sign-on 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)
Audience URI (SP Entity ID)	urn:auth0:iterable:saml-org-<YOUR_ORG_ID>
Name ID Format	EmailAddress
Application Username	Email

# Attribute statements

Name	Value
email	user.email
firstName	user.firstName
lastName	user.lastName
roles	Optional. Omit for authentication only. For authorization, see Okta groups for details.

# Okta groups

Okta allows administrators to define the roles attribute for groups. To do this:

1. From the Okta admin console, navigate to Directory > Profile Editor and click the Profile button next to the Iterable app.

2. Click Add Attribute and fill it in as necessary. Make sure to set the following values:

   • Variable Name: roles
   • Attribute Required: Yes

3. Return to the Assignments tab in the Iterable application. Assign a group, then click the Edit button.

4. Set the roles property as desired for this group. Either:

   • Use orgadmin as the value for your Iterable org administrators.
   • Add the JSON document associated with a non-administrator user group.

5. Repeat for each user group you need.

6. On the General tab, click SAML Settings > Edit. Click Next to get to the Configure SAML step.

7. Set the value of the roles member attribute to appuser.roles.

# Further reading

• Single Sign-on (SSO) Overview
• Setting up Single Sign-On (SSO)
• Single Sign-On Troubleshooting
• Permissions for Using Iterable
• Creating and Updating Custom Roles

Other resources:

• Wikipedia: Security Assertion Markup Language (SAML)