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

OneLogin SAML Setup Guide

Table Of Contents
Quick Overview
General Configuration
    Verify The SAML Domain
    Enabling SAML SSO
    Disabling SAML SSO
OneLogin Configuration
    Setting Up SAML SSO Using OneLogin
    Configuring Attributes In OneLogin & Rolemapping
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

OneLogin Configuration

Setting Up SAML SSO Using OneLogin

Login to your OneLogin Administration page; on the navbar head over to "Applications"
mceclip0.png

In Applications, create your own application by selecting "Add App"

mceclip2.png

You'll be presented with categories on the subsequent page. Head to the search bar and search for "SAML". From the results select "SAML Custom Connector (Advanced)"

mceclip5.png

Give the connector app some details such as a display name, and a description for other admins in your organization to see such as configuration recommendations or processes. You can also choose if you would like to make the app visible to users' OneLogin dashboards/profiles. You can customize the logo using our assets over on our GitHub Repo

mceclip7.png

When you save, you'll land on a similar page with additional options to select from, as seen below.

mceclip0.png

For the next section load your Mailgun SAML details from your dashboard if you haven't had them in another tab/window already. You'll be copying over the Mailgun Service Provider details, note the copy buttons to make sure there are no character format issues or leading/trailing spaces.
mceclip9.png

Copy these over to OneLogin by going to "Configuration"

  • Entity ID will go into the Audience (EntityID) field.
  • Assertion Consumer Service URL (ACS URL) will go into the ACS (Consumer) URL Validator field and the ACS (Consumer) URL field.
  • Single Logout Service will go into the Single Logout URL field
  • NOTE: Mailgun requires BOTH the assertion and response to be signed. You need to change SAML signature element to BOTH.
 

mceclip12.png

Now you will need to provide information from OneLogin to Mailgun. Head over to to "SSO" section. Note the copy buttons to make things easier. mceclip13.png

To copy the X.509 Certificate you will need to click "View Details" and be taken to this page, again note the copy button. Change nothing else, DO NOT HIT DELETE simply navigate back to your app configuration.

mceclip14.png

  • Issuer URL will go in the IdP Entity ID field
  • SAML 2.0 Endpoint (HTTP) will go in the Single Sign-On URL field
  • SLO Endpoint (HTTP) will go in the Single Logout Service URL field
  • X.509 certificate will go into the X.509 certificate field

mceclip15.png

Hit "Update" you should receive toast notifications informing you each field has been updated successfully.

^ Top Of Page

Configuring Attributes In OneLogin & Rolemapping

From here you'll need to configure parameters for either platform to be able to target values so roles are assigned as you desire. You'll need to configure an Attribute Name for each role you would like to set up, depending on how your organization handles their Identity Access Management (IAM) these can be the same or different. For more about how to best implement your IAM for your organization connect with your OneLogin support team or engineer.

For the below example we will be configuring against a OneLogin users "Title" as the identifier in OneLogin, you may find your organization utilizes groups, departments, teams, etc.

To start we created "MG.Role" as the Attribute Name and the targeted Value for each to correspond to either.

mceclip16.png

In OneLogin go to "Parameters" you will be creating a custom parameter connector field that matches the Attribute Name over in Mailgun that you chose. For this example, "MG.Role", and ensure "Include SAML Assertion" is toggled on.

mceclip18.png

The page will update and you will be allowed to choose your target OneLogin Value to apply against.

mceclip20.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 role mapping 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. 

Save All your changes. 


Finally, you will need to ensure your desired users are assigned the application you just finished creating. In this example, as I only have a single user, I did so directly in the user details section. You may find your organization's IAM setup with OneLogin may utilize Groups, Departments, Roles, for Role-Based Access Control (RBAC) assignment to apply applications at scale. To configure and assist with ensuring users are assigned appropriately work with OneLogin support. 

mceclip21.png

 

To test things out, it's recommended you create a test user in OneLogin, setup as desired there, and head over to our Login Page IN A NEW INCOGNITO WINDOW. When you sign in as the new user you should be redirected to authenticate the user with OneLogin.
mceclip22.png

To confirm back in your cached browser session (Aka the non-incognito session) navigate to your account security page. Here, if completed successfully, you will see your new user automatically created with a "SAML Auth" flag.

mceclip23.png

Done!

^ 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