Setup Office 365 Federation & Provisioning (Cloud Users)

Purpose

Federating Microsoft 365 with Practice Protect delivers a seamless and secure single sign-on (SSO) experience. Once federation is configured, authentication and access to Microsoft 365 are managed through Practice Protect. Users must sign in via Practice Protect, and all sign-in policies (such as multi-factor authentication, geolocation restrictions) are enforced there.

This setup is similar to pass-through authentication: login attempts are validated against your Practice Protect policies. Modern authentication is used for outlook and other local Microsoft applications while browser access is redirected to Practice Protect. This also enables the use of SmartLinks, allowing users to access Microsoft 365 apps like SharePoint without re-entering credentials.

Important! Federation is a domain-wide change. Every user must have an account in Practice Protect to sign in to Microsoft 365. When accessing shared mailboxes, it’s recommended to use delegated access.

Provisioning and Deprovisioning Notes

While authentication is handled by Practice Protect, provisioning in Microsoft 365 is only partial:

• Deleting a user in Practice Protect does not automatically remove the user in Microsoft 365.

• Adding a new user in Practice Protect does not automatically assign licenses, roles, or group memberships. These must still be managed manually by IT in Microsoft 365.

In short, Practice Protect is the source of truth for authentication and access policies, but IT retains responsibility for licenses, roles, groups, and other account management tasks.

Devices Joined to Entra

If a device is Entra-joined, users will need to log in using their Practice Protect credentials. In this scenario, MFA will not be prompted, as authentication is handled automatically through the device trust.

Prerequisites

• Administrator access to your Microsoft 365 Tenant. You can create a service account for Practice Protect by following this guide: Create Practice Protect Service Account.

• Register Microsoft Entra ID application (Token-Authentication) 

• Microsoft accounts must be cloud-only (not synced from on-premises Active Directory).
• Users must have an active Practice Protect account.
• The Practice Protect login must match the user’s Microsoft 365 User Principal Name (UPN).

Instructions

1. Sign in to Practice Protect and switch to Admin Portal
2. Under Core Services > Roles > Click Add Role > Type Microsoft 365 Email Integration Users in the Name field.
3. Click Save
4. Go to the role you created, then click Members > Add.
5. Find and select all users who will be part of the email integration. Click Add and  Save.
6. Log in to the Microsoft Admin Center with your admin account.  If you have not set up the Service Account follow this guide.
7. In the Microsoft 365 Admin Center, go to Setup > Domains > Select the domain ending in .onmicrosoft.com > Click Set as default
8. Return to the  Practice Protect Admin Portal, go to Apps & Widgets > Web Apps > Click Add Web Apps, search for Office 365, select Office 365 (WS-Fed + Provisioning), and click Add.
9. On the Add Web App page, click Yes. 
10. In Application Settings, select Token-Based Authentication. Then, enter the Directory ID, Client ID, and Client Secret.
    Note: If you do not have these details, refer this guide on how to register an application in Microsoft Entra ID to obtain them.
11. Click Verify. Ensure the domain you want to federate appears in the domain list. Note: it will not appear if the default domain in Microsoft 365 is not set to .onmicrosoft.com.
12. In the Description, change the app name to Microsoft 365 and click Save.
13. Under the Advanced settings, paste the script below after line 76. Then Save.

    setCustomAttribute('authnmethodsreferences','http://schemas.microsoft.com/claims','http://schemas.microsoft.com/claims/multipleauthn');
    
    var UserMail = LoginUser.Get('userprincipalname');
    var URN = UserMail.split("@")[1];
    setAttribute('IssuerName', 'URN:' + URN);
    

    This configuration sets the following :
    1. Issuer URI/URN for the SAML token response and identifies the domain that the token is associated with.
    2. A custom attribute passes an MFA claim from the Practice Protect platform to Entra ID.
14. Click on Provisioning. Then, tick the box on the side of Enable provisioning for this application.
15. On the Warning page tick the box Do not show again then click Close. 
16. Leave Live Mode selected and tick Enable Hybrid Exchange Support. This means that any changes (on the user details) will be reflected in Microsoft 365.
17. Scroll down and go to Sync Options: select the radio button Sync (overwrite) users to target application when existing users are found with the same principal name. Leave the option Do not de-provision (deactivate or delete) users in the target application when the users are removed from the mapped role.
18. Under Deprovisioning Rules, Click Add Rule and make sure to add and set the following rules (Event & Deprovisioning Action)
    1. User Disabled in Active Directory – Leave User Unmodified
    2. User Deleted in Active Directory – Leave User Unmodified
    3. User Removed from Role or Provisioning – Leave User Unmodified NOTE: It is important to set the above rules as any user deleted from Practice Protect will be de-licensed to the user in Microsoft 365.
19. Scroll down and go to Role Mappings, Select the radio button User is assigned licenses mapped to each role they are a member of (role order has no effect). Click Add. 
20. On the License and Attributes page, Select Microsoft 365 Email Integration Users for the Role created in Step 2. Please do not tick any boxes or do not assign any licenses and click Done.
21. Click Save.
22. Scroll down to Provisioning Script and expand. Replace the existing script with the below Script:

    
    if (isPerson()) {
        // Important! Change country based location e.g. "US" or "AU"
        destination.UsageLocation = "AU";
        destination.Mail = source.CanonicalizeName;
    
        trace("UserName : " + source.CanonicalizeName);
        trace("immutableID : " + source.Base64EncodedGuid);
    }
    

    
23. Then click Save to apply the script.
24. Run a manual synchronization. Under Settings go to Users > Outbound Provisioning > Provisioning Enabled Application > Select Office 365 or Microsoft 365 (depending on the name of the app added), then click on Start Sync.
25. View the real-time status of synchronization by clicking on View Synchronization Job Status and Reports. Once the Synchronization is successful and completed for all users, any changes in Practice Protect will be reflected in Microsoft 365.
26. Enable ADAL/Modern Authentication in Microsoft 365 through this page –  This is to apply the Practice Protect security mechanism in terms of signing in (Geolock, MFA, and other policies) as Basic Authentication doesn’t prompt for Multi-Factor Authentication
27. This completes the backend configuration of Microsoft 365 Federation with provisioning in Practice Protect.

Enabling Microsoft 365 Email Integration/Federation

1. Return to the Microsoft tile in the Admin Portal.
2.  On Permissions, Add the role that contains the user for email integration (i.e. Microsoft 365 Email Integration Users) and click Save to apply. This should display the app on their user portal and can be used once federated.
3. Return to the Application Settings and then on Microsoft 365 Domains section, tick the box beside the Domain(s) Name (i.e. youremaildomain.com) –> Click Actions –> Select Download Powershell Script and save the downloaded file as it will be used in the following steps to federate.
4. Right-click the file downloaded in Step 3 and select Run with PowerShell. Log in with your Microsoft 365 Admin account when prompted.
5. After signing in to Microsoft 365 and completing MFA, you will be prompted to grant the necessary permissions to federate.
6.  With the prompt “What Action Would You Like To Do?” press F. The script will run and federate your domain.
7. Once the script is completed, Go back to Microsoft 365 web app settings in Practice Protect. On the Office 365 Domains section check the Type of the domain (i.e. cbpaccountant.com), It should now be Federated. (Optional) Refresh the page to show the latest state and type.
8. (Optional) Repeat steps 3 to 6 to complete the federation for the other active domains.
9. Test federation if it is working by signing in to a user account in Microsoft 365 Once you type the user name/email address the page will redirect to Practice Protect.
10. To authenticate and access, log in using active Practice Protect account credentials.
11. If you have your Microsoft 365 Email configured on Outlook Desktop or Mobile, you will be prompted to log in with your Practice Protect Account. Most likely it is not synced.
12. Post Federation, Practice Protect recommends disabling legacy protocols/basic authentication (i.e. POP. IMAP,  AUTH SMTP) in Microsoft 365. Please see the following guide.