To Federate Microsoft EntraID domains it is necessary to use Microsoft PowerShell. While Microsoft Powershell comes preinstalled with Windows 10/11 and is available for download on Apple macOS, neither includes the required Microsoft PowerShell modules to manage EntraID.

Prior to March 30, 2024 the PowerShell Module used to federate EntraID domains is named “MSOnline.” The MSOnline module is only compatible with Microsoft PowerShell for Microsoft Windows computers. As of March 30, 2024 Microsoft has deprecated MSOnline (https://learn.microsoft.com/en-us/powershell/azure/active-directory/install-msonlinev1?view=azureadps-1.0 ) forcing customers to use a different PowerShell Module named “Microsoft.Graph.” This is great news for Apple macOS users as Microsoft.Graph is compatible with Microsoft Powershell for macOS.

To see what has changed, The remainder of this document compares he old MSOnline method and the new Microsoft.Graph to federate the domain. Do not attempt to use both methods.

Which EntraID domain do you need to Federate?

The default primary domain for Microsoft EntraID will be YourTenantName.ONMICROSOFT.COM. I don’t recommend federating this one, I recommend setting up a Custom Domain and using the Custom Domain as the federated domain. To see a list of available domains in your EntraID tenant:

1. Login to https://entra.microsoft.com
2. On the left-hand menu expand Identity then scroll down to the bottom and select “…Show More” to reveal the Settings menu
3. Expand Settings and select Domain Names
4. The Custom Domain name page is displayed and indicates which domain is the Primary and if any of the domains are federated. If the domain you need to use is already Federated scroll to the bottom of this blog for instructions on how to remove the existing Federation.
5. Make a note of the name of the domain as you’ll be using this later.

Download the Workspace ONE Access Signing Certificate:

Federation requires the use of a Signing Certificate. There are multiple ways to get to this data but a handy trick that I first heard about from Steve D’Sa over at Steve the Identity Guy is to copy it directly from your Workspace ONE Access Tenant URL as follows:

1. Edit then launch the following URL: https://YourAccessTenant/SAAS/API/1.0/GET/metadata/idp.xml
2. Look for the <ds:X509Certificate> section of the page and copy the very very long string to your favorite text editor for use later on in this process.

Configure Apple macOS:

There are multiple methods available to install Microsoft PowerShell on macOS. In this example I’m using Homebrew. Here are the steps:

1. Launch Terminal
2. Install HomeBrew by running the command:
   
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   
3. Install Microsoft PowerShell by running the command:
   
   brew install powershell/tap/powershell
   
   To verify the installation is successful run:
   pwsh
   
4. Microsoft PowerShell for macOS is regularly updated. To upgrade the version installed run:
   
   brew update
brew upgrade powershell
   
   Note that these commands can be called from within a PowerShell host but upon completion the shell must be exited and restarted to complete the upgrade
   
5. After launching Terminal Run pwsh to launch PowerShell
   
6. Run Install-Module -Name Microsoft.Graph -Force

Construct the PowerShell

Use the table below to construct the powershell command that will need to be run:

Here’s an example of a completed PowerShell Command:

$DomainName = "aftersixcomputers.com"
$FederationBrandName = "After Six Computers"
$PassiveLogOnUrl = "https://aftersixcomputers.workspaceoneaccess.com:443/SAAS/API/1.0/POST/sso"
$ActiveLogOnUri = "https://aftersixcomputers.workspaceoneaccess.com:443/SAAS/auth/wsfed/active/logon"
$MetadataExchangeUri = "https://aftersixcomputers.workspaceoneaccess.com:443/SAAS/auth/wsfed/services/mex"
$LogOffUri = "https://login.microsoftonline.com/logout.srf"
$IssuerURI = "https://aftersixcomputers.workspaceoneaccess.com"
$SigningCertificate = "YourVeryVeryLongString"
$PreferredAuthenticationProtocol = "wsFed"
$MfaBehavior = "acceptIfMfaDoneByFederatedIdp"

New-MgDomainFederationConfiguration `
  -DomainId $DomainName `
  -DisplayName $FederationBrandName `
  -PassiveSignInUri $PassiveLogOnUrl `
  -ActiveSignInUri $ActiveLogOnUri `
  -SigningCertificate $SigningCertificate `
  -MetadataExchangeUri $MetadataExchangeUri `
  -IssuerUri $IssuerURI `
  -SignOutUri $LogOffUri `
  -PreferredAuthenticationProtocol $PreferredAuthenticationProtocol `
  -FederatedIdpMfaBehavior $MfaBehavior `
  | Fl *

Notice that with Microsoft.Graph the command to trigger the Federation is New-MgDomainFederationConfiguration which replaces the MSOnline command Set-MsolDomainuthentication

Connect to Microsoft Graph and Run the PowerShell

This next step is like a game with Russian Matryoshka Dolls in that you need to use PowerShell to authenticate with Microsoft EntraID, then run more PowerShell to set the Federation and then run more PowerShell to validate the configuration.

With MSOnline Authentication to Microsoft Entra was handled by running:

$Msolcred = Get-credential
Connect-MsolService -Credential $MsolCred

With Microsoft.Graph Authentication is now handled through Connect-MgGraph and requires defining the scope as part of the command as follows:

1. Launch Terminal
2. Run
   pwsh
3. Run
   Connect-MgGraph -Scopes "Directory.Read.All”, “Domain.Read.All”, “Domain.ReadWrite.All”, “Directory.AccessAsUser.All"
   
   If this is the first time someone is running Microsoft.Graph it will trigger a Tenant Permissions request similar to the one below.  Make sure to check the box “Consent on behalf of your organization” and click Accept.
   
   
   
   Note that a successful authentication will end up creating a new enterprise app in Azure named Microsoft Graph.
   
4. Copy and Paste the completed PowerShell Command from the previous section into the Terminal to complete the Federation
   
5. The process is complete and EntraID is now Federated with Workspace ONE Access.

More Info and General Troubleshooting:

Microsoft’s documentation of the New-MgDomainFederationConfiguration includes a switch named -NextSigningCertificate. It is not a required field. The flag is described as “Fallback token signing certificate for example when the primary signing cert expires. base64 encoded strings of the public portion of the federated iDP’s token signing certificate.” There is not an equivalent command in the MSOnline modules and it is unclear to me if Workspace ONE Access supports a Fallback token signing certificate. So it is being skipped for now while I do more research into this capability.

Uninstall / Remove Federation

If you made a typo in your template, I have not found a method to update specific configuration details which means it will be necessary to delete the entire configuration and re-apply a new one.

1. To remove the Federation from PowerShell you will need to know the TenantID value, a unique string of numbers associated to each domain.   From PowerShell run:
    
   Get-MgDomainFederationConfiguration -DomainId “aftersixcomputers.com”
   
   The result will display the “ID” which is used in the next command.
   
2. Run the following as a single-line:
   
   Remove-MgDomainFederationConfiguration -DomainID 'aftersixcomputers.com' -InternalDomainFederationId 'longstring'

Note that each time you create a Federation a new internal ID is generated.

Troubleshooting:

The hardest part of this entire configuration was figuring out the correct scope to use when connecting to Microsoft.Graph. Prior to figuring that out, I ended up adjusting permissions for the Microsoft Graph Command Line Tools Enterprise Application thinking that might be part of the problem. I don’t know if they helped/hurt or just don’t matter to the overall process, but I’m leaving there here in case anyone else wants to shed some light on these.

1. Login to https://entra.microsoft.com
2. From the left hand menu expand Identity > Applications > Enterprise Applications
3. Choose the newly created “Microsoft Graph Command Line Tools”
4. Choose Manage > Roles and Administrators and notice no one is assigned to “Cloud Application Administrator”
5. Select the “Cloud Application Administrator” Role
6. Choose Add Assignments and define which users will get this Role. I added my two primary EntraID admin accounts to the permission set.

Microsoft has published a command line reference document to help with the transition from MSOnline to Microsoft.Graph:

https://learn.microsoft.com/en-us/powershell/microsoftgraph/azuread-msoline-cmdlet-map?view=graph-powershell-1.0#connect-to-your-directory

A few useful ones not already used:

• Get-MsolUser replaced by Get-MgUser
• Set-MsolUser and Set-MsolUserPrincipalName replaced by Update-MgUser

Acknowledgments

It takes a village to do anything useful with technology these days. Thank you to Steve D’Sa for the tips. Thank you to Anuraag Mishra and his blog over at (https://wsonetidbits.wordpress.com/2024/01/29/federate-entraid-access-microsoft_graph/ ) for helping me sort out PreferredAuthenticationProtocol and to everyone else I bugged to review this document before publishing.