How to Set Up MFA for Encompass

2

Copyright Statement © 2020 Ellie Mae, Inc. Ellie Mae®, Encompass®, AllRegs®, DataTrac®, Ellie Mae Network™, Mavent®, Millennial Tracker™, Mortgage Returns®, Prospect Manager®, Total Quality Loan®, True CRM®, TQL® and the Ellie Mae logo are trademarks of Ellie Mae, Inc. or its subsidiaries. All rights reserved. Other company and product names may be trademarks or copyrights of their respective owners.

How to Set Up MFA for Encompass Rev. 4/14/2020

3

Contents What is Bring Your Own Authentication (BYOA)........................................................................ 4

MFA and Encompass................................................................................................................ 4

Authentication..................................................................................................................... 4

Process Overview ................................................................................................................ 5

Okta Verify .............................................................................................................................. 5

To configure your Okta Verify account: ............................................................................. 5

Duo Mobile ............................................................................................................................11

To configure your Duo Mobile account: ...........................................................................11

Additional Configuration Settings ........................................................................................14

Global Policy ...................................................................................................................15

Apply Company Branding ................................................................................................15

Reset the Secret Key .......................................................................................................15

Enable MFA in Encompass ......................................................................................................16

To Enable MFA in Encompass: .........................................................................................16

Configure your MFA details in Encompass Developer Connect .................................................19

To add your MFA configuration to Encompass: ................................................................19

User Experience .....................................................................................................................24

4

What is Bring Your Own Authentication (BYOA) BYOA provides an additional layer of security to the traditional user name and password authentication method. BYOA is part of a multifactor authentication (MFA) framework where an employee authenticates to their corporate network first by providing a user name and password, then by providing a pin or code from their smartphone or device.

MFA and Encompass Encompass 20.1 (and later) supports multifactor authentication using Okta Verify or Duo Mobile identity providers. This guide describes the necessary steps to set up your multifactor authentication provider account to work with Encompass. Once configured, your Encompass users will be able to pair their mobile devices with Encompass, and start receiving push notifications to authenticate.

Authentication

Primary authentication is handled by Encompass with the user’s Encompass client ID, user ID, and password. If the user's primary credentials are correct, the user is prompted for secondary or second-factor authentication with the MFA provider. How the user authenticates during second-factor authentication depends on which authentication method is used by the MFA provider. It could be a push notification sent to the user’s smartphone, by answering a phone call, entering a one-time passcode generated by the MFA provider’s app, a compatible hardware token, or received via SMS. Note: For Okta Verify identity provider, only Okta Verify Push is supported. SMS and other options are not supported for Okta users at this time.

5

Process Overview

Setting up your MFA provider with Encompass is a straightforward process. The high-level steps are:

1. Configure your MFA provider. Encompass supports Okta Verify and Duo Mobile identity providers. Configuration steps for both Okta Verify and Duo Mobile are provided in this document.

2. Enable MFA in Encompass. This step is required for implementing MFA for Encompass. For instructions, see Enable MFA on Encompass.

3. Configure MFA application provider details in Encompass Developer Connect portal. In this step, you will add your MFA application provider details to the Lender MFA configuration page in the Encompass Developer Connect portal. For instructions, see Configure your MFA details in Encompass Developer Connect.

Okta Verify Configuring your organization’s Okta Verify account involves generating an API key for your Okta tenant, creating a new Encompass user name profile attribute, and then populating that attribute for each user with their Encompass user name. For more granular access control, you can create a user group of Encompass users and assign additional access permissions to that group. To complete these steps, an Okta Verify administrator account is required.

Azure Active Directory Users

If your company uses Active Directory, you may already have a custom attribute for Encompass. In this case, you can save time by synchronizing your Active Directory accounts with Okta, then updating your Okta account with the information in this document. For more information about synchronizing your Active Directory accounts with Okta, refer to your Active Directory documentation.

To configure your Okta Verify account:

1. Log in in to your Okta organization as an administrator.

6

2. Optional. For more granular access control, create a new user group and add all Encompass users to that group. You can assign additional restrictions to the group in a later step.

To create a new user group:

a. Open the Groups page:

If you use the Developer Console, select Groups from the Users menu.

If you use the administrator’s UI (Class UI), select Groups from the Directory menu.

b. Click Add Group.

c. Name your group and click Add Group.

d. Click Manage People.

e. Add the Encompass users to the new group.

3. Create a service account that Encompass will use. Creating a service account adds another level of access control. This step is an Okta security best practice.

To create a service account:

a. Open the Users page:

If you use the Developer Console, select People from the Users menu.

If you use the administrator’s UI (Classic UI), select People from the Directory menu.

b. Click Add Person.

c. Enter the first and last name, username, primary email and admin-supplied password, and then click Save.

d. Open the Administrators page, which is only available in the administrator’s UI (Classic UI), by selecting Administrators from the Security menu.

e. Click Add Administrator.

7

f. Enter the username of the service account, and then select Help Desk Administrator. Optionally, select Can administrator users in specific group (optional) and enter the Encompass user group.

g. Click Add Administrator.

4. Create an API token for your organization’s Okta tenant.

a. Open the API page:

If you use the Developer Console, select Tokens from the API menu.

If you use the administrator's UI (Classic UI), select API from the Security menu, and then select Tokens.

b. Click Create Token.

c. Name your token and click Create Token.

d. Make note of your API token. It is only displayed once. You will provide this token later to Ellie Mae using the Encompass Developer Connect portal.

5. Create an Encompass user name attribute on the desired Okta user profile. a. For the Okta User group or App group, click Add Attribute.

8

b. Enter details for the Encompass user name attribute.

For this field… Provide…

Data type String

Display name The display name of the attribute. For example, Encompass User Name.

Variable name encompassUserName. Take note of the variable name. It will be used to call the API and it will be referenced in mappings.

Description Optional. Provide a short description of the attribute.

Attribute required

Make this attribute required if users are in individual groups. It should not be required if all users are in a single group.

For example:

c. Click Save.

9

The new attribute is displayed it the user profile.

6. Update the Okta profile for each user. In this step you will define the Encompass user name attribute for each user. The attribute is a combination of the user’s Encompass user ID and Encompass instance.

Azure Active Directory Users You can synchronize your Active Directory accounts with Okta instead of having to manually define the Encompass user name attribute for each user. If you choose to synchronize your Active Directory accounts, continue with Step 7 once synchronization is complete.

a. On the Directory menu, click Profile Editor.

b. Click the Okta filter.

c. For an Okta User, click Profile in the Actions column.

d. Go to the Encompass user name attribute you created and enter the user’s Encompass user ID and Encompass instance. Use the following format:

<Encompass user ID>@encompass:<Encompass instance ID>

For example, jreese@encompass:DEBE11100000

10

e. Click Save.

f. Repeat steps d and e until all your users are configured.

7. Configure your MFA details in Encompass Developer Connect.

11

Duo Mobile Configuring your organization’s Duo Mobile account involves protecting the Auth API, collecting the application details, and then enrolling your users. To perform these tasks, a Duo Mobile administrator account is required.

To configure your Duo Mobile account:

1. Login in to the Duo Admin Panel as an administrator and navigate to Applications.

2. Click the Protect an Application button on the top right corner.

3. Search for and locate the Auth API or Partner Auth API.

4. Click Protect this Application next to Auth API or Partner Auth API in your search results.

12

5. On the Auth API or Partner Auth API page, capture the information displayed in the Details area of the screen. You will provide the Integration Key, Secret Key, and API hostname values later to Ellie Mae through the Developer Connect portal. Treat your secret key like a password The security of your Duo application is tied to the security of your secret key. Secure it as you would any sensitive credential. Don't share it with unauthorized individuals or email it to anyone under any circumstances.

13

6. Add the users who will access the Duo application using two-factor authentication. To do so, follow these steps:

a. Click the Users tab in the left navigation menu.

b. Click Add User.

c. Add a user’s information in the provided fields. For Username or any Username Alias, use the following format:

Username = <Encompass User Name>

For example, jreese

Username Alias = <Encompass user name>@encompass:<Encompass instance ID>

For example, jreese@encompass:BD12356265

14

7. Configure any additional settings as needed. See Additional Configuration Settings for

information about setting a Global Policy, applying company branding, and more.

8. Click Save Changes, and then complete the enrollment process if needed.

9. Add Your MFA Configuration to Encompass.

Additional Configuration Settings

There are other configuration settings you might want to consider using in your Duo application. These settings can be used to control how users will authenticate, apply company branding to your application, and reset the secret key. These settings are entirely optional and at the administrator’s discretion.

15

Global Policy

The Global Policy allows you to control how your users authenticate. By default, users are prompted to register for two-factor authentication during login. If you want to change this behavior, you can do so on the Policies page by clicking the Edit Global Policy button, then selecting one of the following user policies:

1. Require enrollment. The default policy. If this option is selected, unenrolled users will be prompted to register for two-factor authentication during login.

2. Allow access without 2FA. If this option is selected, unenrolled users will be not be prompted for the second-factor authentication.

3. Deny access. If this option is selected, and the user is not enrolled for two-factor authentication, the user will not be able to login.

Apply Company Branding

You may want to add your company name and logo to the application. Your users will see the company name and logo during enrollment and authentication via browser, as well as in the Duo Mobile app. You can add the company name and logo from the Settings page, under General. Detailed instructions are available in the Duo online help.

Reset the Secret Key

At some point you may need to reset the secret key for your application. Generate a new secret key by clicking the Reset Secret Key button on your Auth API or Partner Auth API Applications page.

Note: If the secret key is reset, the value must be updated within Ellie Mae for multi-factor authentication to continue working.

16

Detailed instructions are available in the Duo online help.

Enable MFA in Encompass This step is required when enabling MFA on Encompass. There is a setting in Encompass Admin Tools that controls whether MFA is to be used for logging in Encompass users. To enable this Multi-Factor Login Flow option, an Encompass Super Admin account is required. (The administrator who logs into Encompass using the admin user ID can also perform this task.)

To Enable MFA in Encompass:

1. On your Windows task bar, click the Start menu or Start icon, navigate to the Ellie Mae Encompass program folder, and then click Admin Tools.

2. Double-click Settings Manager.

If you are prompted to log in to the server, enter the User ID, Password, and Server that you use to log in to Encompass as the Admin user.

3. Select Password from the Category list, then click Enable MFA Login.

17

4. Select the check box for Encompass.

18

5. Click OK, then click OK again to close Encompass Admin Tools.

19

Configure your MFA details in Encompass Developer Connect Encompass requires certain pieces of information about your MFA provider application. You can provide this information on the Encompass Developer Connect portal. This is a one-time process; however, if any of your MFA provider application details change, then you’ll need to update the information in the Encompass Developer Connect portal for multi-factor authentication to continue to work.

Testing and Validation For testing and validation, Ellie Mae recommends applying your MFA configuration to your Encompass test environment prior to applying it to your production system.

To add your MFA configuration to Encompass:

If you have already set up an Encompass Developer Connect account and you have access to Developer Connect, you can log in and proceed with the MFA configuration as described in the steps below. If you do not have access to Developer Connect yet, direct access to it is provided within Encompass Settings in Encompass Banker Edition.

If you are using Encompass Broker Edition, you must set up a Developer Connect account and use your credentials to log into Developer Connect. See the Getting Access to Developer Connect guide for instructions.

With these options in mind, follow the applicable steps below.

If You Are Using Your Existing Developer Connect Credentials:

1. Log into the Developer Connect portal using your Developer Connect account credentials.

Getting Access to Developer Connect If you do not have a Developer Connect account and would like to set one up, see the Getting Access to Developer Connect guide for instructions.

2. On the Developer Connect portal, click My Account, then select Lender MFA.

20

3. On the Lender MFA Sign In page, click Sign in, then sign in using your Encompass Super Admin (or admin user ID) credentials.

Continue to step 4 below. If You Do Not Have Developer Connect Credentials:

1. On the menu bar in Encompass, click Encompass, and then click Settings.

2. On the left panel, click Company/User Setup, and then click Company Information.

3. On the Company Information tab, click the Configure MFA button.

The Configure SSO button is used to visit the Lender SSO Setup page in

Encompass Developer Connect, where you can set up or change your

company's SSO provider or credentials. For more information about setting up

SSO for Encompass, refer to the Setting Up SSO for Encompass guide.

21

Continue to step 4 below.

Follow the remaining steps below regardless of how you have accessed Developer

Connect.

4. On the Configure multi-factor authentication (MFA) page, click Change Provider.

5. On the Lender MFA page, Selection tab, select your MFA provider: Okta Verify, or Duo

Mobile.

22

6. Click Next.

7. Enter your provider details.

Okta Verify

For Okta Verify, provide the following details:

For this field… Provide…

API token The token generated when you configured your Okta Verify account.

Org URL Your organization’s URL as configured on the Okta developer site.

Profile custom property profile.encompassUserName

For example:

23

Duo Mobile For Duo Mobile, provide the following details:

For this field… Provide…

API host name The API hostname configured in DUO Mobile. Use the following format: https://api-XXXXXXXX.duosecurity.com.

Integration key The integration key specified in your DUO Mobile configuration.

Secret key The secret key from your DUO Mobile configuration.

Simple username matching

Optional. This option controls how Encompass queries Duo Mobile. Select this option to use only the user ID (for example, jreese) instead of the fully qualified username (for example, jreese@encompass:DEBE11100000).

For example:

8. Click Done.

Developer Connect validates the MFA configuration by establishing a connection to the identity provider using the information you provided. If the connection is successful, the settings are saved and the changes take effect immediately. Currently logged in users will be asked to log in using MFA the next time they log in. If there are any issues with the connection, your identity provider will return an error message.

24

User Experience When logging into Encompass, your users are prompted to install your provider’s app from the Apple App Store or the Google Play store. Once a user pairs a device with the provider’s app, Encompass will authenticate their device automatically.

The next time the user logs in and primary authentication is successful, the user will be prompted for the second-factor authentication. For example, with Duo Mobile, the following screen might appear: