Overview

This guide provides best practices for setting up and managing TPO Connect Third Party Originator (Broker/Seller) user authentication through SSO.

Prerequisites

• Send external user welcome emails/reset password emails through the IDP.
• Disable both “Welcome” and "Reset Password” email notifications through TPOC.
  • “Welcome” and “Reset Password” email notifications should be sent from the SSO IdP. This ensures users clearly understand that their credentials are managed centrally through SSO and prevents confusion or the mistaken assumption that they need to set or reset a separate application password.
  • Details on how to enable/disable a template can be found here : Encompass TPO Connect Administration Guide starting on page 161.
• Configure your IdP application with ICE Mortgage Technology settings and collect the metadata file from the configuration. For additional instructions, review the Setting Up Single Sign-On for Encompass Products Guide.
  • If required, configure SSO policy rules to enforce MFA for TPO Connect login for initial user activation, and any subsequent logins as appropriate.
• Onboard SSO connection for TPOC via Encompass Developer Connect.
• Subscribe to the ExternalUsers webhook events to be notified when the external user is created, updated or deleted in TPOC to trigger user creation and profile synch in IDP.

Existing TPO External User Management Flow

If an external user was created in TPO Connect before SSO was enabled, the user should be forced to reset their password through the IDP. This ensures they only manage a single set of credentials. See the instructions below for more details.

1. Retrieve the list of existing external users using the V3 Get All External Users API GET/encompass/v3/externalUsers.
2. Parse the API response to retrieve the external user details including the emailForLogin. Add the external users in IDP, assign to TPO Connect application and set the profile to force password reset upon the next login in TPO Connect.
   1. Note: SAML subject must be mapped to the TPO WebCenter Login Email assigned.
3. Upon next login, user receives email from IDP to reset password, once the password has been reset, the user is redirected to TPO Connect for SSO login.

New TPO External User Provisioning Flow

1. Pre-provision the TPOC Account Manager with persona rights to be able to create additional external users.
2. The TPOC Account Manager logs into TPO Connect and adds new TPO contacts/external users via the TPOC Admin UI.
   1. For instructions on how to add external users via UI see the Encompass TPO Connect Website User Guide starting on page 10.
3. By subscribing to the ExternalUsers Create webhook event, you will receive a webhook notification when the external user is added in TPO Connect.
   1. The extra payload for the ExternalUsers webhook event includes the userId which can be used to retrieve user profile details using API.
4. Upon receiving the webhook notification, use the V3 Get an External User API GET/encompass/v3/externalUsers/{userId} to retrieve the external user details to create a profile in IDP.
5. Add the external user in IDP, assign to TPO Connect application and send user activation/welcome email to set password.
   1. Note: SAML subject must be mapped to the TPO WebCenter Login Email assigned.
6. User receives welcome email from IDP, creates password, and is redirected to TPO Connect for SSO login.