Microsoft Entra ID - Domain Federation

Created by Chris Canfield, Modified on Tue, 29 Oct at 10:23 AM by Chris Canfield

Overview

TraitWare can be used to protect the log in to Microsoft services, adding strong, low-friction, highly-secure passwordless MFA.

This guide demonstrates how to federate a Microsoft tenant domain to use TraitWare Passwordless MFA as the primary login for Microsoft services.

Use cases where TraitWare can be used to protect services on federated domains:

Microsoft web applications
Microsoft desktop applications
Microsoft mobile applications
Windows 10/11 Entra-joined sign-in (requires TraitWare credential provider)
Windows 10/11 Entra-registered (workplace joined) sign-in
Windows 11 domain-joined IdP sign-In (requires additional configurations)

Two options are provided to federate a tenant domain:

Federate using the TraitWare Admin Console
Federate using Powershell commands

Prerequisites

The Microsoft Graph API User Sync must be configured and working.
Ensure that the Graph API permission for IdentityProvider.ReadWrite.All is enabled.

**Note: Microsoft federation is domain level. Non-disruptive user testing requires a secondary domain.

TABLE OF CONTENTS

Verify Domains in Azure
Add/Assign Global Administrator
Create Application in TraitWare Console
- Create Signing Key
- Create Application
Federate the Domain
Remove Federation
- Remove Federation Using TraitWare Console
- Remove Federation Using Powershell
Rotate/Change the Signing Key

Verify Domains in Azure

Make sure the account has more than one verified domain. Federation requires that one domain remains unfederated (Primary Managed domain). TraitWare recommends selecting the .onmicrosoft.com domain as the primary.
Tenant domains are found by navigating to Entra ID>Custom domain names in the Azure console.

Add/Assign Global Administrator

Ensure there is a global administrator on the account.

Add a Global Administrator. This user will not use TraitWare to sign in. This account does not require licenses from Microsoft.
Navigate to Entra ID → Users → + New User
Fill in the appropriate information for the Name and User name (email)

Select Assignments, Add role and change to Global Administrator then select Ok.
Select Review + Create

If the account already has an existing user that is preferred as the global administrator, navigate to Entra ID → Roles and administrators → Global Administrator

Select + Add member and search for the appropriate user to add as a member

**Note: It is highly recommended to use security best practices when creating a password

Create Application in TraitWare Console

Create Signing Key

Navigate to the Signing Keys in the applications menu of the TraitWare console.
Click the plus sign to add a new signing key.

Enter display name, select desired Lifetime in Years. Click Generate Key.

Create Application

Navigate to the Application menu and click on the + to add a new application

Choose the SAML application type

Enter the Application Name for the application
Select Use a Template

Search for ‘Microsoft’, select Microsoft Cloud Logins, and click Submit

Select the newly-created application

Click on Signing Key under the Configuration tab to expand that section. Click Edit Signing Key

Select the previously-created signing key

Federate the Domain

Federate Using TraitWare Console

In the TraitWare console, navigate to the User Sync menu and the Federate Domains tab.

Click the edit icon for the domain to federate. company.com used here as an example

Select the Application you configured in the previous step
Click Federate Domain to complete the federation

**NOTE: Do not federate more than one domain with the same Application. Create a separate application for each domain that needs to be federated. If a domain is accidentally federated with an application used on a different federated domain, a warning will appear and the domain will exist in a broken state in the Microsoft account. It must be unfederated using the powershell command to unfederate.

The domain will now have a green circle indicating it has been federated

Test the federation to ensure it has been federated successfully.

**Note: Although the federation will display immediately as successful in the TraitWare console and in the Azure/Entra console, it can take several minutes for the federation to appear on Microsoft logins. This is expected Microsoft behavior.

Federate Using Powershell

Prior to executing the Powershell commands, please ensure that the following have been completed and are available:

Global User Created (within the onmicrosoft.com domain)
More than one verified domain
TraitWare Microsoft Application (created above)

Get the Powershell Comand

Click on the edit icon for the domain to federate. company.com used here as an example.

Select the Application you configured in the previous step
Click >_ Run Command to show the powershell command
Copy the command

Use the Powershell Command

Open Powershell (ISE is recommended for ease of use).
Install the MsOnline Module in Powershell by running the following command

Install–Module -Name MSOnline

Select Yes to all and let the scripts run.
Connect to Azure using the Global Admin credential and run the following:

Connect-MsolService

A window will open up, enter the Global Admin username and password. This is usually the *.onmicrosoft.com Microsoft user account.
Paste the Powershell script copied from the TraitWare console in the previous step and press enter. If successful there will not be a response in the command line.

The powershell script to federate will resemble the following examples.

Simple example:

Set-MsolDomainAuthentication -Authentication Federated -DomainName yourdomain.com -IssuerUri https://YOURURI.traitware.com -LogOffUri https://portal.office.com -PassiveLogOnUri https://api.traitware.com/YOURACCOUNT/samlAuth -SigningCertificate YOURCERTINFORMATION -PreferredAuthenticationProtocol SAMLP

Verbose example:

Set-MsolDomainAuthentication -Authentication Federated -DomainName yourdomain.net -IssuerUri https://e423gfe9895fs59fe882zxf10ffa14bde9.traitware.com -LogOffUri https://portal.office.com -PassiveLogOnUri https://api.traitware.com/9212775657/samlAuth -SigningCertificate “—–BEGIN CERTIFICATE—–MIIDrjCCApYCCQCzQmtkoNSgCTANBgkqhkiG9w0BAQsFADCBmDELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExR7tXlCm2Q6g2A/3OAyJ67HaprL+pYo2RB0TEsugF584T4CcWAljLC2S5a0vBS0cNknJKNBSW/A3SVEYLw0IlL4OyJYQUkkbbeSihEx6Cw83GFlLMhXHhPcTFv44Hu0Bq4Z3FDASBgNVBAcMC05ldmFkYSBDaXR5MRIwEAYDVQQKDAlUcmFpdFdhcmUxDDAKBgNVBAsYDVQQLDANJRFAxFjAUBgNVBAMMDXRyYWl0d2FyZS5jb2MA0lEUDEWMBQGA1UEAwwNdHJhaXR3YXJlLmNvbTEkMCIGCSqGSIb3DQEJARYVc3VwcG9ydEB0cmFpdHdhcmUuY29tMB4XDTE4MTExOTIxNDM0MloXDTI4MTExNjIxNDM0MlowgZgxCzAJBgNVBAYTAlVTMRMwEQYDVQQIDApDYWxpZm9ybmlhMRQwEgYDVQQHDAtOZXZhZGEgQ2l0eTESMBAGA1UECgwJVHJhaXRXYXJlMQwwCg0xJDAiBgkqhkiG9w0BCQEWFXN1cHBvcnRAdHJhaXR3YXJlLmNvbTCCASIwDQYJKoZIhvcNAQEBBQudfhFIGS37fyzVqM4pNiWn2FpByzJocf+Cc6IZ+5IHm0eH98asHnE+cKQLdXMJiwP/z1k8ZhUjK0lRyoDFJsL+zi7r5u6g1dSGL+nqAgdFxsedxgEw6uGBp0QWYsgraqOt3JLFO7HD+zysKtrihbg9Gdqx02ROd7HeFk2h8fDxA2sUCHO90zqokMKqLag42ze4zPayy4K5PsQ+ihLhXWqTq5azEi4Yo9E0QfYIMpqXgHMIXgwdYp2E2K6phnsH9tQCSYeqH4jAU4T1o+2PigHfnYzMpwienx+lQsJ1ode9mFpXECAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAnpNNkESZCU+QADggEPADCCAQoCggEBAK/GwBauAinkRfhbNLn4rPEUU6p4JyWOODyWLgjTQnJVNsEsn5Xa9v7iNJ/4J68XzU9EICZ1mtCNLa+v0OtSulBVnpJgjs3K6KSMTAzIm4y80qhHaPOqr2iiXh36PZatapqxZQBqMyXCTai6Q8wnMiwJl8NWxKhnzrPnbGup68Fu9FppvrbL9ITom7g4TiJyR8YaYW4SR/4v0rn49f4WtR42jZO/Qxy2W4LIpmATZjl/dlCg==
—–END CERTIFICATE—–
” -PreferredAuthenticationProtocol SAMLP

Test the Federation

Test the federation to ensure it has been federated successfully.

Navigate to office.com or another Microsoft login page and enter your email address. When federation is successful you should see a screen similar to the image here.

Remove Federation

Sometimes it may be necessary to remove federation and change a domain back to managed, such as when rotating a signing key.

Remove Federation Using TraitWare Console

Click the edit icon on a federated domain to remove federation. company.com used here as an example

Click Un-Federate Domain

If successful there will be a grey dot in the Federated column for that domain

**Note: Although the removal of federation (back to managed) will display immediately as successful in the TraitWare console and in the Azure/Entra console, it can take several minutes for the removal of federation to appear on Microsoft logins. This is expected Microsoft behavior.

Remove Federation Using Powershell

Follow the above steps to select the domain where federation is to be removed
Click >_ Run Command to display the Powershell Script to remove federation
Copy the Powershell script

Paste the Powershell script after running Connect-MsolService and logging in as the Global Administrator. If successful, there will not be a response on the command line.

Set-MsolDomainAuthentication –Authentication Managed -DomainName company.com

**Note: This will disable TraitWare authentication for the selected Microsoft domain

Rotate/Change the Signing Key

At some point the signing key will expire as set when the key was originally created. It is a best security practice to have a limited lifespan for signing keys. TraitWare sends out notification emails alerting administrators that keys are expiring. The signing key needs to be changed before it expires to ensure uninterrupted service. The process of changing a key uses many of the steps listed above and is similar to how the domain was originally federated.

We suggest coordinating the steps below relatively quickly in succession to minimize any downtime. There will be downtime between the time when the key is updated on the application and when the domain is federated with the new key. If planned accordingly with the steps listed below, this should only last a few seconds.

Rotate/Change Using TraitWare Console

Order of steps we recommend to limit downtime using the TraitWare Console

Create a new signing key in the TraitWare Console
Change the signing key on the Microsoft application in the TraitWare console
Un-federate the domain in the TraitWare Console
Federate the domain in the TraitWare Console
Test the federation with a TraitWare user account to ensure the login works as expected

Rotate/Change Using Powershell

Order of steps we recommend to limit downtime using Powershell

Create a new signing key in the TraitWare Console
Prepare the script to un-federate and federate in a notepad
Log into your Microsoft account via Powershell with your username and password. This is usually your *.onmicrosoft.com Microsoft user account.
Change the signing key on the Microsoft application in the TraitWare console
Un-federate the domain using the Powershell script
Federate the domain with the new key in the Powershell script
Test the federation with a TraitWare user account to ensure the login works as expected

Create a New Signing Key

Navigate to Applications>Signing Keys in menu of the TraitWare console. Click the plus sign to add a new signing key.

Enter a name for the new key and select desired Lifetime in Years. Click Generate Key.

Assign New Signing Key to Application

Navigate to your Microsoft application (the application used with federation)

Click on Signing Key under the Configuration tab to expand that section. Click Edit Signing Key

Select the new signing key

The application has been assigned the new key. Follow the steps above to Un-Federate and Federate again with the new key (using TraitWare Console or Powershell).