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

SAML SSO

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 provisioning, so that when a user logs into Mailgun using our SSO integration, that user automatically becomes a user under your Mailgun account.

Note: SAML SSO is only available on Scale and above plans. See our plan comparison here.

 

Requirements to enable SAML SSO on Mailgun:

Verified Sending domain

In order to setup SAML, you will need to verify that you own your corporate domain (the domain being used in the SAML configuration to login). There are two methods for verifying your corporate domain on the Mailgun platform:

  • Verified sending domain - if you plan on or are using your corporate domain for sending on Mailgun, you can use our current method of adding SPF and DKIM records to verify the domain as a sending domain on Mailgun. This domain must match the FQDN in your corporate email address used to authenticate. If the domain is already a verified sending domain on your account, no further action is required.
  • TXT record - Mailgun can generate a unique TXT record for you to add to your corporate domain’s DNS that will allow us to verify you own this domain. In order to use this method, head to the SAML Setup page ( Settings > Details in the left hand nav and then scroll down to the Authentication section and in the SAML Auth sub-section, click on Setup SAML SSO) enter your corporate domain in the Domain Name field under Domain TXT Record Generation, and hit Generate. Copy the TXT record from the modal and add that to your DNS records for your domain.

You’ll need to provide the following to Mailgun from your Identity Provider:

  • IdP Entity ID (Also known as Identity Provider Issuer)
  • Single Sign-on URL
  • X509 Certificate

You’ll need to provide the following SAML Provider details to your Identity Provider from Mailgun:

  • Entity ID
  • Assertion Consumer Service URL
  • Single Logout Service URL

 

Accessing and enabling SAML SSO on Mailgun

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

In order to access the SAML configuration on Mailgun, click on Settings > Details in the left hand nav and then scroll down to the Authentication section and in the SAML Auth sub-section, click on Setup SAML SSO:

Settings.PNG

Once there, you will find the relevant SAML Provider details, as well as the information you’ll need to provide Mailgun:

Setup.png

Disabling SAML SSO

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

In order to disable SAML SSO on your account, click on Settings > Details in the left hand nav and then scroll down to the Authentication section and in the SAML Auth sub-section, Deactivate.

Any users that were created prior to activating SAML will be able to login at https://login.mailgun.com/ with their prior username and password combo 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.

 

Okta

Setting up SAML SSO using Okta

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.

The following instructions and screenshots will assume you are using Okta’s Classic UI, which can be accessed by a dropdown in the upper left hand corner.

classic_UI.png

Once you have an Okta account, navigate to Applications and click on Add Application and then Create New App. When the modal pops up, select the Web Platform and SAML 2.0 as the Sign on method.

SAML_create_app.png

Give your app a descriptive name, and a logo, if you wish, and then click on Next.

Enter your:

    • Single sign on URL (this is referred to as “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`.


SAML_Settings.png


Configuring Attributes in Okta

UserAttributes.png

You’ll need to provide Attribute Statements for FirstAndLastName (otherwise we’ll provide a generic name)

Okta organizes users into groups. Typically those groups will organize users by the role they hold within the organization. Those groups should be mapped to roles within Mailgun as well. The following is a simple example for configuring role mapping in Mailgun. This configuration will simply pass the group names from Okta in the SAML assertion in the “UserGroup” attribute and allow Mailgun rolemapping to decide which role should be assigned to the user. 

In Mailgun, this is saying that IdP attribute “UserGroup” (which we configured above to pass the Okta Group name in) that has the name “Developers” should be assigned to the “Developer” role.

SAMLroleMapping.png

Notes:

  • A user must map to a particular role or login will not be allowed and an appropriate error message will be displayed. 
  • Not every Mailgun role needs to have a mapping. For example, if there is no need to have an “Analyst” role log in to Mailgun, just leave that mapping blank in the Mailgun UI. 
  • 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 flow 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 for that user. The roles are given the following priority in descending order.

  • admin
  • developer
  • support
  • billing
  • Analyst

 

So, for example, if a user maps to a “developer” and “admin”, they will be “admin” in Mailgun since it holds higher priority. 

Powered by Zendesk