Configuring Single Sign-On for Administration Console Using a 3rd Party Identity Provider

Document created by user.oxriBaJeN4 Employee on Jun 3, 2016Last modified by user.oxriBaJeN4 Employee on Mar 27, 2017
Version 18Show Document
  • View in full screen mode

This guide explains how to configure Single Sign-On for Administration Console using a 3rd party Identity Provider.

Once your Identity Provider is configured, Mimecast SAML Authentication settings are applied to a group of users using an Authentication Profile. SAML Authentication is an enforced method for all users subject to the settings defined in the Authentication Profile, for the relevant application. When you first enable SAML Authentication, particularly for the Administration Console, consider applying it to a test user before enabling it for all Administrators. This prevents you locking yourself out of the Administration Console in the case of a configuration issue.

Working With Your Identity Provider

 

Before you can configure the Mimecast Single Sign-On settings, you must work with your Identity Provider to add support for Mimecast. Some providers (e.g.

OneLogin, Okta, or Centrify) may have Mimecast apps in their application catalogs, but Mimecast is not able to provide support for these as their implementation is out of Mimecast's control. Consult directly with your Identity Provider if you need any assistance.

 

Providing Information to Your Identity Provider

 

The following information may be useful for your Identity Provider:

 

FieldDescription
SAML VersionMimecast only supports SAML 2.0. Your Identity Provider must also support this.
Service Provider Initiated Request: Binding TypeService Provider Initiated SAML requests from Mimecast use a POST binding.
Service Provider Initiated Request: Issuer

The <saml:Issuer> value in a Service Provider Initiated SAML request from Mimecast will be different depending on the Mimecast grid that your organization's Mimecast account is hosted. Below are the expected values for each grid:

 

RegionValue
Europeeu-api.mimecast.com.ACCOUNTCODE
United Statesus-api.mimecast.com.ACCOUNTCODE
South Africaza-api.mimecast.com.ACCOUNTCODE
Australiaau-api.mimecast.com.ACCOUNTCODE
Offshore

jer-api.mimecast.com.ACCOUNTCODE

Where ACCOUNTCODE is your unique Mimecast account code as specified in the Administration | Account | Account Settings page of the Administration Console.

Due to a limitation with AD FS, if you've configured Relying Party Trusts for Mimecast Personal Portal v3 or our End User Applications, ensure the entered value is unique. In most cases you can accomplish this by having the ACCOUNTCODE portion all upper case on one and lower case on another.

Service Provider Initiated Request: AssertionConsumerUrl

The AssertionConsumerServiceURL value in a Service Provider Initiated SAML request from Mimecast will be different depending on the Mimecast grid that your organization's Mimecast account is hosted. Below are the expected values for each grid:

 

RegionValues
Europehttps://eu-api.mimecast.com/login/saml
United Stateshttps://us-api.mimecast.com/login/saml
South Africahttps://za-api.mimecast.com/login/saml
Australiahttps://au-api.mimecast.com/login/saml
Offshorehttps://jer-api.mimecast.com/login/saml
Service Provider Initiated Request: RequestedAuthnContext

Mimecast supports the RequestedAuthnContext features in a Service Provider Initiated SAML request. Depending on your Mimecast configuration these values can be empty or:

 

<samlp:RequestedAuthnContext xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"

                         Comparison="exact"

                         >

    <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport

    </saml:AuthnContextClassRef>

    <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">urn:federation:authentication:windows</saml:AuthnContextClassRef>

</samlp:RequestedAuthnContext>

It is also possible for the request to only include one <saml:AuthnContextClassRef>.

SAML Response: Destination

Mimecast maintains different URL's for Service Provider Initiated and Identity Provider Initiated SAML authentication.

SAML Response: IssuerThe issuer element must be present and contain the value provided by your Identity Provider. This value is also set in the Mimecast configuration in a later step and the value found in the SAML response must match the value stored in your Mimecast settings.
SAML Response: Audience

The SAML response must contain an AudienceRestriction element with a child element called Audience. The value of this element must be set based on the region where your Mimecast account is hosted. Please see the table below for the expected values for each grid:

 

RegionValue
Europeeu-api.mimecast.com.ACCOUNTCODE
United Statesus-api.mimecast.com.ACCOUNTCODE
South Africaza-api.mimecast.com.ACCOUNTCODE
Australiaau-api.mimecast.com.ACCOUNTCODE
Offshore

jer-api.mimecast.com.ACCOUNTCODE

Where ACCOUNTCODE is your unique Mimecast account code as specified in the Administration | Account | Account Settings page of the Administration Console.

Due to a limitation with AD FS, if you've configured Relying Party Trusts for Mimecast Personal Portal v3 or our End User Applications, ensure the entered value is unique. In most cases you can accomplish this by having the ACCOUNTCODE portion all upper case on one and lower case on another.

SAML Response: NameIDThe SAML response must contain the NameID element as a child of the Subject element. The value of this element must be the requesting user's primary email address.
SAML Response: NotBefore / NotAfterThe SAML response must contain the NotBefore and NotAfter attributes in a Conditions element. The values of these attributes must be within a 1 minute margin of error to the current time otherwise the request will be rejected for security reasons.
SAML Response: Token Signing CertificateThe SAML response must contain the metadata of your Identity Provider's certificate. This value is also set in the Mimecast configuration in a later step and the value found in the SAML response must match the value stored in your Mimecast settings.

 

Example Service Provider (Mimecast) Initiated Request

 

ex1.png

Where ACCOUNTCODE is your unique Mimecast account code as specified in the Administration | Account | Account Settings page of the Administration Console.

 

Example SAML Response

 

ex2.png

 

Collecting Information From Your Identity Provider

 

Before configuring any Mimecast settings you must gather the following information from your Identity Provider:

 

Field / OptionDescription
SAML VersionMimecast only supports SAML 2.0. Your Identity Provider must also support this.
Federation Metadata URLMimecast can import the SAML Issuer, Login URL and Token Signing Certificate from a URL if your Identity Provider publishes this information in the standard XML format.
SAML IssuerA unique URL that identifies your Identity Provider. SAML responses sent to Mimecast must match this value exactly in the <saml:Issuer> attribute of the SAML response.
Login URLThe URL where Mimecast should redirect the user to in order to start the authentication attempt.
Logout URLThe URL where Mimecast should redirect the user to to when they logout. Mimecast only supports basic redirects here.
Supported Authentication Contexts

How users with authenticate against the Identity Provider and what Authentication classes the Identity Provider supports.

Mimecast supports the RequestedAuthnContext features in a Service Provider Initiated SAML request. Depending on your Mimecast configuration these values can be empty or:

<samlp:RequestedAuthnContext xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"

                         Comparison="exact"

                         >

    <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport

    </saml:AuthnContextClassRef>

    <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">urn:federation:authentication:windows</saml:AuthnContextClassRef>

</samlp:RequestedAuthnContext>

It is also possible for the request to only include one <saml:AuthnContextClassRef>.

Token Signing Certificate MetadataThe Metadata of the certificate issued by your identity provider.

 

Configuring Mimecast Settings

 

Once your Identity Provider is set up to support Mimecast SAML authentication requests and responses, you need to configure a Mimecast Authentication profile. This profile is applied to the users that you want to use Single Sign-On using the Applications Settings feature.

 

SAML Settings

 

  1. Login to the Administration Console.
  2. Navigate to the Administration | Services | Applications menu.
  3. Select the Authentication Profiles button.
    Authentication_Profiles_Button.png
  4. Select an existing Authentication Profile to update or select the New Authentication Profile button to create a new one.
  5. Enter a Description for the new profile.
  6. Select Enforce SAML Authentication for Administration Console.

  7. The screen expands to reveal the SAML Settings:

  8. Select your Identity Provider from the Provider drop down list to see help text specific to that provider. If your provider is not listed choose Other.
  9. If your Identity Provider supports it, enter the Federation Metadata URL of your Identity Provider and select Import to automatically populate all of the required settings.
    • If Mimecast cannot reach this URL, or if your Identity Provider does not support this function, you can enter the Issuer, Login URL and Identity Provider Certificate Metdata values manually.
    • When populating the Identity Provider Certificate you must trim the Begin and End tags from the certificate metadata.
  10. Optionally select Monitor Metadata URL. This option requires a valid Metadata URL and will check that your Authentication Profile contains the current Identity Provider certificate and settings. The feature is designed to prevent unexpected issues when these settings change at the Identity Provider.

    Checks are made a maximum of once per day and are initiated when a user logs in. If a user with this Authentication Profile applied does not login on a given day the metadata will not be checked.

  11. Optionally specify the Logout URL. Mimecast only supports basic URL redirect logout methods.
  12. Optionally define which Authentication Context to use. By default both password protected and integrated contexts are used.

    These settings define the AuthnContextClass that is used in the SAML request provided by Mimecast and sent to your Identity Provider. Mimecast supports the Password Protected Transport and Windows Integrated contexts, a combination of both, or no context.

  13. Choose to Allow Single Sign On. This setting enables / disables Identity Provider Initiated Sign On.

 

Optionally Define Permitted IP Ranges

 

To add an additional layer of security Mimecast provides optional Permitted IP Range settings for the Administration Console, End User Applications, and Gateway authentication attempts.

 

To configure Permitted IP ranges for the Administration Console:

  1. Login to the Administration Console.
  2. Navigate to the Administration | Account | Account Settings menu.
  3. Open the User Access and Permissions section.
  4. In the Admin IP Ranges text box, enter the public IP address ranges you want to restrict access to in CIDR format, one range per line.

 

To configure Permitted IP Ranges for End User Applications:

  1. Select the check box to enable Permitted Application Login IP Ranges.
  2. In the Permitted Application Login IP Ranges text box enter the public IP address ranges you want to restrict access to in CIDR format, one range per line.
  3. Select Save and Exit to apply the new settings.

 

To configure Permitted IP Ranges for Gateway authentication using SMTP or POP:

  1. Select the check box to enable Permitted Gateway Login IP Ranges.
  2. In the Permitted Gateway Login IP Ranges text box enter the public IP address ranges you want to restrict access to in CIDR format, one range per line.
  3. Select Save and Exit to apply the new settings.

 

Other Options

 

An Authentication Profile is applied to a group of users and a user can only have one effective profile at a given time. Consequently you may want to add additional authentication options to your Authentication Profile. See the Authentication Options space for information on other authentication methods.

SAML Authenticaton is an enforced authentication method, consequently other Authentication Options will only apply to applications that do not support SAML.

Apply the Authentication Profile to an Application Setting

 

Once your Authentication Profile is complete, you need to reference it in an Application Setting in order for it to be applied. To do this:

 

  1. Login to the Administration Console.
  2. Navigate to the Administration | Services | Applications menu
  3. Select the Application Setting that you want to use.
  4. Use the Lookup button to find the Authentication Profile you want to reference and click the Select link on the lookup page.
    Application_Settings_select_Authentication_Profile.png
  5. Select Save and Exit to apply the change.

 

Next Steps

When using Service Provider Initiated SAML Authentication your administrators must access the Administration Console using the regional URL. Due to the differences between each Identity Provider's implementation of SAML, Mimecast does not support this authentication type when using the https://login.mimecast.com global URL.

To test your configuration and verify that your Authentication Profile has been configured correctly,

    1. Open a web browser and navigate to the Mimecast Administration Console v4 login page.
    2. Enter your primary email address.
    3. You should be redirected to your Identity Provider login URL specified in the Authentication Profile.
    4. If required, login to your Identity Provider.
    5. You should then be redirected to Administration Console v4 and granted access.

 

To test Identity Provider Initiated Sign On

    1. Navigate to your Identity Provider login page and login.
    2. From the published applications page select the Mimecast Administration Console v4 application you have created.
    3. You should be redirected to Administration Console v4 and granted access.

Attachments

    Outcomes