We're experiencing difficulty. Our engineers are on it. Please check status.mailgun.com for real-time updates.

Okta SAML Setup Guide

Table Of Contents
Quick Overview
General Configuration
    Verify The SAML Domain
    Enabling SAML SSO
    Disabling SAML SSO
Okta Configuration
    Create An Okta Account (If Needed)
    Create A New Okta App
    Configure The SAML Integration In Okta
    Configure The Attributes In Okta
    Rolemapping Mailgun Roles In Okta
Got Questions

Quick Overview

Note: SAML SSO is available on Scale and higher plans (i.e. Contract and Enterprise). See our plan comparison here.

Using the SAML 2.0 protocol, Mailgun allows you to integrate with your Identity Provider to authenticate users via single sign-on, also known as SSO. Theoretically, as long as your current Identity Provider supports the SAML 2.0 protocol (Okta, Auth0, Onelogin, Azure AD, etc), then you should be able to use your provider with Mailgun. 

Mailgun supports just-in-time (JiT) provisioning, so that when a user logs into Mailgun using our SSO integration, that user automatically becomes a user under your Mailgun account.

In short, this setup process requires the exchange of information between the two systems:

  • Provide Mailgun With The Information Below From Your Identity Provider
    • IdP Entity ID (also known as Identity Provider Issuer)
    • Single Sign-on URL
    • X509 Certificate
  • Provide Your Identity Provider With The Information Below From Mailgun
    • Entity ID
    • Assertion Consumer Service URL
    • Single Logout Service URL

^ Top Of Page

General Configuration

Verify The SAML Domain

In order to set up SAML, you will need to verify that you own your corporate domain (the domain to be configured with SAML login). There are two methods for verifying your domain on the Mailgun platform:

  • Verified sending domain - If the domain you wish to configure with SAML is already a verified sending domain on your account, no further action is required for this bullet point. Otherwise, you will need to add the domain and configure the SPF and DKIM records to verify the domain. This domain must match the FQDN in the corporate email addresses that will be used to authenticate using SAML.
  • TXT record - Mailgun can generate a unique TXT record for you to add to your domain’s DNS that will allow us to verify you own this domain. In order to use this method:
    • Navigate to the SAML Configuration settings page (see the "Enabling SAML SSO" section below)
    • Enter your domain in the Domain Name field under the Domain TXT Record Generation section
    • Click the Generate button
    • Finally, copy the TXT record from the modal, and add it to your DNS hosting provider for your domain.

Screen Shot 2022-11-08 at 3.45.12 PM.png          Screen Shot 2022-11-08 at 3.45.36 PM.png

Enabling SAML SSO

Note: Only Admin users have access to enable/disable SAML on an account.

As for enabling SAML SSO, we'll show you how to do this below:

  1. First, log in to the Mailgun Control Panel (if you have not already done so).
  2. Then, at the top-right corner of the page, click the Profile drop-down menu to expand its list of options.
  3. Next, click the Account option. Alternatively, you can use this direct link
  4. On the resulting page and in the Authentication section, click the Setup button for the SAML Auth setting.

Screen Shot 2022-11-08 at 3.46.23 PM.png

Once there, you will find the relevant SAML Provider (SP) Details [i.e. Mailgun details that you provide to your Identity Provider], as well as the Identity Provider (IdP) Details [i.e. Identity Provider details that you provide to Mailgun]. This article goes over the specific information and additional steps needed in the relevant Identity Provider sections (i.e. Okta, Azure, OneLogin, etc.). You will also have the option to Manage Custom Configuration , which allows you to set your User Name Attribute Settings. 

Screen Shot 2022-11-08 at 3.23.12 PM.png Screen

Disabling SAML SSO

Note: Only Admin users have access to enable/disable SAML on an account.

As for disabling SAML SSO, we'll show you how to do this below:

  1. First, log in to the Mailgun Control Panel (if you have not already done so).
  2. Then, at the top-right corner of the page, click the Profile drop-down menu to expand its list of options.
  3. Next, click the Account option. Alternatively, you can use this direct link
  4. On the resulting page and in the Authentication section, and by the SAML Auth setting, click the Disable button.

Screen Shot 2022-11-08 at 3.45.59 PM.png

Of Special Note: 

^ Top Of Page

Okta Configuration

Create An Okta Account (If Needed)

First, you’ll need an Okta account. If you already have one, great! If not, you can register at https://developer.okta.com and follow the instructions to get a free developer account.

Screen Shot 2022-11-08 at 3.17.01 PM.png

^ Top Of Page

Create A New Okta App

Once you have an Okta account, navigate to Applications on the left-hand navigation pane. On the resulting page, click the Create App integration button.

Screen Shot 2022-11-08 at 3.17.33 PM.png

When the modal pops up, select SAML 2.0 as the sign-on method. The next modal provides the opportunity to give your app a descriptive name and a logo, if you wish, before continuing the process by clicking the Next button.

Screen Shot 2022-11-08 at 3.19.03 PM.png          Screen Shot 2022-11-08 at 3.20.23 PM.png

^ Top Of Page

Configure The SAML Integration In Okta

Next, you'll be presented with various fields. We'll explain what data you should assign to each field:

    • Single sign on URL (Assertion Consumer Service URL in your Mailgun Dashboard)
    • Audience URI (Entity ID in your Mailgun Dashboard)
    • Leave Default RelayState blank
    • Name ID format should be set to EmailAddress
    • Application username should be set to email
    • Update application username on should be set to Create and update

Screen Shot 2022-11-08 at 3.25.04 PM.png

^ Top Of Page

Configure The Attributes In Okta

Note: we ask you to provide Attribute Statements for FirstAndLastName since we will otherwise provide a generic name.

There are three attributes (one of which will be a group attribute) in total that will need to be added. We'll explain what data you should assign to each field:

  • Attribute Statement 1
    • Name: FirstAndLastName
    • Name format: leave as Unspecified
    • Value: user.firstName + " " + user.lastName
    • Note: the special characters and specific spacing in the value above are intentional
  • Attribute Statement 2
    • Name: email
    • Name format: leave as Unspecified
    • Value: user.email
  • Group Attribute Statement 1
    • Name: UserGroup
    • Name format: leave as Unspecified
    • Filter:
      • Drop-down: choose Matches regex in the dropdown
      • Textbox: .*

Screen Shot 2022-11-08 at 3.50.47 PM.png

^ Top Of Page

Rolemapping Mailgun Roles In Okta

Okta organizes users into groups. Typically these groups will organize users by the role they hold within the organization (e.g. Support, Billing, etc). These groups should be mapped to roles within Mailgun as well. The following is a simple example of configuring rolemapping in Mailgun. This configuration will pass the Okta group names in the SAML assertion inside the UserGroup attribute, ultimately allowing Mailgun's rolemapping to decide which role should be assigned to a given user. 

The below screenshot is from Mailgun on the SAML configuration page. In this example, whenever an Okta user has the IdP group attribute (UserGroup) assigned to "Developers", Mailgun in turn will assign the user a "developer" role. A similar example could be an Okta UserGroup of "Supervisors" mapping to the Mailgun role of "admin".

SAMLroleMapping.png

Important things to keep in mind:

  • A user must map to a particular role, or login will not be rejected with an appropriate error message displayed. 
  • Not every Mailgun role needs to have a mapping. For example, if there is no need for you to use the “Analyst” role in Mailgun, leave that mapping blank in the Mailgun Control Panel. 
  • Mailgun’s rolemapping feature only supports case-sensitive string matches. Regex’s are not supported at this time.
  • Account owners can never perform an SP-initiated login by entering their email address at login.mailgun.com. This is to prevent the account owner from locking themselves out. The account owner can perform an IdP-initiated login, however. 
  • It is entirely possible that a user can be in two groups in Okta or simply map to multiple roles in Mailgun. If this happens, Mailgun will observe the higher-priority role of that user. For example, if a user maps to both a “developer” and “admin”, they will be assigned “admin” in Mailgun since it holds higher priority. The roles are given the following priority in descending order:
    • admin
    • developer
    • support
    • billing
    • analyst

^ Top Of Page

Got Questions?

Sinch Mailgun has answers! If you have any concerns or questions, please send us a Support ticket using the Support page within your Mailgun Control Panel.  Our Support Team will be happy to assist!

^ Top Of Page