Microsoft Exchange - ECP - MFA

This document explains how to implement Monosign with Microsoft Exchange - ECP.

📑 Instructions

This documentation contains 4 main steps for integration.

1. Creating an Application on Monosign

2. Configuration Single Sign-On for Microsoft Exchange - ECP

3. Assign a user to the Microsoft Exchange - ECP app

4. Sign In Test

1- Creating an Application on Monosign

Create your application on Monosign and configure your access policy. Once you create, click “Keys” and add a new Access Key for Rest API Key for access.

We will need this information while configuring the Microsoft Exchange - ECP app.

Your application needs to have access to groups. If you have configured it yet, you can Edit your application, go to the “Source, Provider and Profile” tab, and configure User Group Access Type “Assigned Users and Defined Sources”. It means this application can access users’ groups when they sign in.

2- Configure your ECP App on IIS

2.1- Install IIS Module Files

Monosign MFA for Exchange ECP is working with IIS customization. Before continue please download below zip file.

⬇️ Download the latest IIS Module.

Zip file is contains below files.

2.2- Configure ECP

Connect your ECP server and open IIS (Run inetmgr.exe).

Expand your Computer Name and click Sites then double-click “Default Web Site” right-click “ecp” and click “Explore”. You will be redirected to the Explorer window that contains ECP configuration files.

Copy the IIS Module “dll” files under your application bin folder. For ECP use below path.

Please create bin directory if does not exist.

Back up your web.config file just in case.

Right-click on web.config and Open with Notepad (or with any Text Editor).

Edit and put your settings between the appSettings section.

<add key="MONOSIGN_API_URL" value="https://your-api-url/"/>
<add key="MONOSIGN_API_KEY" value="your-api-key"/>
<add key="MONOSIGN_API_SECRET" value="your-api-secret"/>
<add key="MONOSIGN_DEBUG_MODE" value="true"/>
<add key="MONOSIGN_LOG_PATH" value="log-directory"/>
<add key="MONOSIGN_USER_EXCEPTIONS" value="if-you-have-type-email@address"/>

For example;

Add the following line to the end of the system.webServer/modules section.

<add name="MonoSignExchange" type="MonoSign.IISModule.MSExchange, MonoSign.IISModule"/>

For example;

Save the file. It will take a couple of minutes to restart the app.

Multiple User Sources on Monosign (Optional)

What if I use multiple User Sources in Monosign and I want to specify my User Source for my Exchange?

For that, add a line to appSettings.

<add key="MONOSIGN_USER_SOURCE" value="MONOFOR"/>

This setting refers to your Active Directory User Source or Domain Name on Monosign.

Like the following

Or you can use the following Domain Name

3- Sign In Test

Now try logging in. Navigate to the Microsoft Exchange - ECP app. Click Monosign on the UI.

Troubleshooting

If you cannot sign in to ECP, the following reasons may cause this.

1. The user needs to be assigned to the application

2. The user needs to configure MFA properly

You can check the log files if you cannot see the error properly.

4- Troubleshooting

If you get any issues while trying to log ECP please take a look log files which are under the log directory that you defined in appSettings section.

Issue 1 - Monosign API Access

Log

[MONOFOR\john.smith] By-username result is 0 
[] https://mail.monofor.com/owa/auth/errorFE.aspx?httpCode=500

By-username result is 0 means Exchange servers needs to be access monosign-api services. Please check your firewall to allow this communication.

Issue 2 - Invalid Key or Secret

Log

[MONOFOR\john.smith] By-username result is OK {"InternalMessage":"Invalid Application Key","Code":12,"Success":false}
[] https://mail.monofor.com/owa/auth/errorFE.aspx?httpCode=500
[] White listed: /owa/auth/errorFE.aspx?httpCode=500

{"InternalMessage":"Invalid Application Key","Code":12,"Success":false} means your application key or secret is invalid. Please check your application settings than verify configurations values in web.config on your Exchange.

Issue 3 - Permission Denied

Log

[MONOFOR\john.smith] Mfa result is Forbidden {"Message":"Permission Denied","InternalMessage":"This user not assigned to this application.","Code":22,"Success":false}
[] https://mail.monofor.com/owa/auth/errorFE.aspx?httpCode=500
[] White listed: /owa/auth/errorFE.aspx?httpCode=500

Mfa result is Forbidden {"Message":"Permission Denied","InternalMessage":"This user not assigned to this application.","Code":22,"Success":false} means your user has not assign to ECP application in the Monosign. Please assign this user than retry.