EMS SSO Support

 

Description

 

The SSO Integration is about having an Identity Provider (Idp) do user authentication. It will be another password policy (like winauth is), except we don't have to have any outside services running to do the authentication.

When a user hits our login page, we'll recognize the user's email and redirect to the Idp authentication page (i.e. NOT our login page). The user logs in on the Idp site and then gets directed back to the EMS user home page. If the user is already logged in, then the user gets directed straight to the EMS user home page.

A short SAML description: https://onelogin.zendesk.com/hc/en-us/articles/201175714-Introduction-to-OneLogin-s-SAML-Toolkits

 

Supported Identity Providers

 

 

While we are using the SAML 2.0 specification and should work against any SAML 2.0 supporting provider, we will be validating against the following providers:

 

Currently tested and supported:

OneLogin (http://www.onelogin.com)

Setting up a connector: https://onelogin.zendesk.com/hc/en-us/articles/202673944-How-to-Use-the-OneLogin-SAML-Test-Connector

 

Should be supported, just needs testing, will ship with 6.25:

AzureAD

 

To be supported in the near future/needs further investigation: We need to check with SonicWall and add their 'default' SAML provider if they have one Look at the Dell Identity Broker

 

WFE UI Updates

 

The main login screen for WFE and mobile browser WFE has been updated to:

• Only show the email field at first
• After email is entered, a 'next' button (or enter) is selected that will then either show the password field (EMS or Winauth users) or redirect to SAML login page if SSO enabled.
• If SSO enabled, the redirect will either prompt the user for credentials AT THE IDENTITY PROVIDER site OR automatically log the user in if the browser session is already authenticated at the Idp.
• Additionally, a remember-me field has been added to the main page.

Screenshots:

 

 

..then with a password field if the email is NOT saml enabled. Note: This includes ALL users of customer who are WinAuth or EMS Auth AND all special accounts of customers that are SAML auth (i.e. emsroot and custom mailboxes).

 

 

...and if the email is SAML enabled, the browser is redirected to the identity provider, for EXAMPLE, it might look like this (it depends on the Idp):

 

 

 

 

EMS Clients

EMS Client support is not yet supported. If a customer is using SAML, then client software must be installed using the credentials of an EMS authenticated user (source='special' or a custom mailbox user).

Outlook Extension

Outlook extension clients will not work for SAML enabled customers until a new outlook extension is provided. Unknown which release of Outlook Extension will support SAML.

Mobile clients (iphone/android)

Mobile clients will also not work until they have been updated. Unknown which release of the mobile apps will support

SAML Library

M1-EMS's core-services/saml-services is our library for SAML. It is lightly based off of the OneLogin sample program.

Web Request to Determine SAML Redirect

This request can be used by clients to figure out if an email requires SAML authentication or not. URL request to backend is the following:

1. Make request to the service discovery api to find the location (see ServiceDiscovery) of the AuthTypeApi (id=4). For the purposes of this example, the returned location will be http://backend/wfe/authtype.

2. Perform an HTTPS POST request to the service with the JSON body of:

  

{

  "AuthTypeRequest" : {

    "user" : "hello@world.com"

  }

}

3. The response will always be an HTTP OK 200 with different json content. Use the redirect attribute of the result to indicate that the use should be redirected to the URL in the location attribute for authentication. The identity provider then redirects back to the correct location in the WFE.

Additionally, a WWW-Authenticate header is returned which contains the information needed to determine what type of authentication should be used. Ideally, clients will pay attention to this value. See EMS Service for Outlook Extension for more details on the WWW-Authenticate header.

{

    "AuthTypeResult" : {

        redirect : true or false,

        location : null or url for redirection

    }

}

Sample URL returned:

https://app.onelogin.com/trust/saml2/http-post/sso/410005?email=stanley.horton@samlloginit.com&SAMLRequest=nVJNb9pAEP0r1t79iQPJClMR0qpISWOB20Mv1bIewyr2rrszLiS%2FPmsDFYeGQ08rzbx9896bmaJo6pbPO9rpFfzuAMk7NLVGPjQy1lnNjUCFXIsGkJPk6%2FnTI0%2BCiLfWkJGmZt7yIWO%2FxokYJ3JT%2BTIpwU%2FTzcS%2FG6WVfzuSkzhKUxmNb5n3AywqozPmGNxHxA6WGklocqUovvGj2E%2FuijjlowmPbn4yLz%2BNuVe6VHp7XdPmCEL%2BtShyP39eF8ybI4IlN3RhNHYN2DXYP0rC99VjxnZELfIwbBTtrKoD47TIl6DcYi02gTRNuK8g7NOozdbooDSf6O25qhAoG40jNpv2PT4YsRfZXZcpzpLY7PPTehpecBwJW%2F7NfVo%2B5KZW8tX7Ymwj6GPOOIiHiir9aoByaISq52VpAdFF4NTvFxYEQcbIdsC88DzotHcohytwGREcyFuYphVWYb8qOAhJZ6eXqEXtjKyg%2Bh%2FfV2GSy57alXP37I0t%2BysA6VQWVmhsjaVTav%2FSMzv2PvD2t3t59rN3

The email=value parameter is only a hint to the Idp on what to populate the email field with on the Idp page. The Idp provider may or may not support this (i.e. the username field may be blank)

Outlook Extension (iOS?) Updates

In order to support the outlook extension and mobile apps, the client login servlet has been modified to accept different authentication methods. See EMS Service for Outlook Extension for more details.

Testing

Regression of anything requiring authentication

 

SSO Configuration in the Web Front End Note about Onboarding a new Customer

Charles brought it to our attention that to onboard a new customer, the following procedure must be taken:

1. Create the customer in EMS (include creating an ems root account)

2. Install the client in their exchange environment

3. Perform a directory sync

4. Once complete, THEN you may start configuring saml via the WFE (that is, continue this guide)

Why? The SAML check makes sure the username entered in belongs to a valid user and that the user's customer is enabled for SAML. If we don't have a list of users from the customer, then we are kinda screwed.

 

Capability addition  

 

 

 

Password policy configuration

 

 

 

On the password policy configuration settings page, two pieces of information are needed (see One Login and AzureAD sections below for details on this information):

• The login url for the identity provider
• The certificate for the identity provider (Do not include the BEGIN and END certificate lines.)

 

Configuring the Identity Providers for Use by EMS

 

For all identity providers, the following information is required when setting it up. These values are referred to during the setup steps below:

 

 

For each datacenter, the consumer URL and the recipient must have the correct datacenter FQDN.

 

OneLogin

 

This sets up a sample application that can communicate with EMS. When the application has been configured, the login URL and the certificate
must be updated in the sample app for this new OneLogin application.

1. Log into your OneLogin account. If you do not have one, create one.

2. Once logged in, select the 'Apps -> Add Apps' menu item:

 

 

 

3. On the Add Apps screen, search for the OneLogin SAML Test Application:

 

 

4. Go to the Company Apps Page from the Apps menu item.

 

 

 

5. Select the SAML test application and configure it to allow from our application.

 

 

 

5. Set the values per the table above:

i. Audience = https://ems.messageone.com (NOTE THIS CHANGED FOR 6.25.306+, which will be built on the evening of 2/26/2015)

ii. SAML Recipient = https://<<<REPLACE_ME>>>/wfe/samllogon.do

iii. SAML Consumer URL = https://<<<REPLACE_ME>>> You will replace the <<<REPLACE_ME>>> text above with whatever backend you are working on. example: silverems.qa.messageone.com

 

6. Select the SSO tab in order to find the certificate for the app.

 

 

Click on the 'View Details' link to view the certificate and copy its value. This is the certificate value to place in your application to validate communications with OneLogin. This certificate should be PRIVATE and not distributed.

 

7. That's it on the OneLogin side. Your application can now be configured to use OneLogin for authentication and SSO.

 

Next, you'll want to do this for each user you want to log in as. On the OneLogin website, log in as the administrator. Once there, click on the USERS tab at the top and select ALL USERS

 

 

 

Now, for each EMS user you want to be able to log in as:

• click the blue NEW USER button in the top right
• enter any first name, any last name, and the corresponding email the user will use in EMS in the email field, then click the SAVE USER button in the top right. example: ank2@lab601.m1dev.com (which exists as a user on lab601 on silver)

​

 

 

 

• hit the down arrow of the MORE ACTIONS button, select CHANGE PASSWORD

 

 

 

• in the popup dialog, enter the desired password. hit the UPDATE button. In this example, I used !mail... - the usual password
• next, click the Applications tab (below the MORE ACTIONS and SAVE USER button)

 

 

 

• The list should be empty. click the + sign in the top right side of the Applications table. There should only be one application, so you can just click the CONTINUE button in the popup dialog. in the next dialog, enter the user's email address. hit the SAVE button in the dialog.
• Finally, hit the SAVE USER button in the top right, next to the MORE ACTIONS button

 

Congratulations! now that user can log in to EMS using OneLogin. Repeat the above process for all of the users you want to log in as. Note: you can have users that exist in EMS but not in OneLogin, and you can have users that exist in OneLogin that don't exist in EMS. You can also have users that enter one email address in EMS and a different one in OneLogin and, as long as it's a known alias, will still work.