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

General configuration

Note: if your users are Sinch ID enabled, you will need to follow this guide instead.

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

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 Manage Account option. Alternatively, you can use this direct link. 
4. On the resulting page and in the Mailgun settings section, click the Setup button for the SAML Auth setting.

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. 

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 Manage Account option. Alternatively, you can use this direct link. 
4. On the resulting page and in the Mailgun settings section, and by the SAML Auth setting, click the Disable button.

Of Special Note: 

• Any users that were created prior to activating SAML will be able to log in at https://login.mailgun.com/ with their prior username and password combination for their Mailgun account. 
• Any users that were created using JiT via SAML will need to initiate a password reset at https://login.mailgun.com/recovery/new

SAML SSO setup guides

Once SAML SSO has been enabled within the Mailgun Control Panel (as detailed in the above section), you may begin the process of connecting your Identity Provider to Mailgun. For reference, please use one of the available setup guides linked below:

• Azure SAML SSO Setup Guide
• Okta SAML SSO Setup Guide
• OneLogin SAML SSO Setup Guide

Need Support?

Our Support Team here at Sinch Mailgun is happy to help! Reach out to us in the Support page of your Mailgun Control Panel, and we'll be with you shortly!