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

Azure configuration

Create an Azure account (if needed)

First, you’ll need an Azure Active Directory account and one of the following roles: Global Administrator, Cloud Application Administrator, or Application Administrator.

If you already have one, great! If not, you can register here and follow the instructions to open an account.

Once you have activated your users within the Mailgun application, you will need to add them to Azure, your identity provider (IdP).

Setting up SAML SSO

To set up SAML, you will need first to verify that you own your corporate domain (the domain being used in the SAML configuration to log in) on both platforms (Mailgun and Azure).

Verifying a domain on Azure Active Directory

Go to your 'Azure Active Directory' and select 'Custom domain names'.

Click on 'Add custom domain' and follow the procedure.

Once the domain has been added, it will be shown on your 'Custom domain names' page. The status of the domain should be 'Verified' for the SSO to work.

Verifying a domain in Mailgun

Follow the procedure described here. 

Once your domain is verified on both sides, let's start setting up SSO authentication between Azure and Mailgun.

SSO configuration on Azure

Enter your Azure account and navigate to 'Azure Active Directory'.

Once there, click on 'Enterprise applications'.

Select 'New application' on top of the screen.

Then click on 'Create your own application' and follow the configuration steps.

Once you have created your application, click on it...

...and select the second option ‘Set up a single sign on”.

Choose 'SAML' method for the SSO configuration.

On the next page, you will find the relevant Identity Provider details and the forms you will need to complete.

On the first step 'Basic SAML Configuration', you will need to take the relevant Service Provider details from Mailgun, and fill out the marked sections below.

Provide Mailgun information to Azure

Go to 'SAML Configuration' and select 'Sign SAML response and assertion' from the dropdown menu under 'Signing option'. The 'Signing Algorithm' field should be left as it is (SHA-256).

Don't forget to download the Base64 certificate as you will need it later for the Mailgun configuration.

When you have completed steps 1 and 3, you will need to do the same on the Mailgun side.

To access the SAML configuration on Mailgun, click on Account Settings --> SAML Auth (SSO) on the Account Information page.

Azure Groups & Group Claims

Note: See also Microsoft's documentation if needed.

1. Click on “+ Add a Group Claim”

2. Group Claims Assertion Configuration

1. For “Which groups associated with the user should be returned in the claim?”, select “Security Group”,
2. next set “Source Attribute” to “Group ID”,
3. expand “Advanced Options” and check “Customize the name of the group claim”,
4. set “Name” to “UserGroup”
5. Save.

3. Click on “+ Add new claim”

1. Set “Name” to “FirstAndLastName”
2. Set “Source” to “Attribute”
3. Set “Source Attribute” to “user.displayname”
4. Save

4. In the “Additional Claims” section, delete “user.givenname” and “user.surname”

1. To delete, click the “…” and select “delete”
   

5. Create the appropriate groups your organization will be using. These can be named anything but you will need to be sure the users will later be appropriately mapped to Mailgun’s roles.

1. Navigate to Users and Groups → + Add user/group
   

2. Select a group (Note the Object ID, this will be used during role mapping later)
   

3. Assign appropriate users to the group
   

Provide Azure Information To Mailgun

Mailgun

Azure

Comment

USERS MANAGEMENT

Open your Azure account, go to Azure Active Directory --> Users and click on 'New user'.

Follow all the steps and add the new user, which will be displayed on the 'Users' page.

Now you need to assign the newly created user to the Mailgun application.

Go to the application and select 'Assign users and groups'. 

Then click on 'add user/group'...

...and select the user you want to give SSO access to from the list.

Once selected and assigned, the user will be displayed under the 'Users and groups' page. All users displayed on this page will have SSO access to your application.

Rolemapping

Only map the Roles that will be assigned to the Groups accessing the application.

1. Click the cog wheel icon to edit each role mapping section.
   
2. IdP Attribute name will be UserGroup
3. Set the IdP Attributes Value to the Object ID of the Azure AD Group
   
   
4. Submit, the role mapping should look similar as below.
   

If all the steps mentioned above have been followed correctly, users with access to your Mailgun application should have no problem logging in via SSO.

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!