Skip to main content

Registering a Custom Domain in Entra ID

Step 1: Sign into the portal with a user who has Global administrator role Step 2: Search and run Entra Active Directory service Step 3: Navigate to Custom domain names and start the registration flow by clicking on Add Custom Domain Step 4: Verify ownership of the domain at the end of the process. This is usually done by adding a TXT record with a specific value in a primary DNS server for your domain. Note that this process may take some time as DNS records have TTL set in hours in some cases

Creating a New Entra ID Adapter Using TruU Admin Console

Step 1: Navigate to Integrations and click on the (+) in the top right corner Step 2: Add a new Single Sign On adapter by clicking the (+) in the upper right corner Step 3: Select Entra ID type and click Create Step 4: Enter the adapter descriptive name, the public URL where the IDS will be available, the domain which is going to be federated, and select a certificate validity period Image 1! 1 Step 5: Click Apply. This will download a PowerShell script needed to setup federation in AAD Image 2! 2

Setting Up Entra ID to TruU Federation Using a PowerShell Script

Step 1: Run Powershell 64 app on Windows as administrator Step 2: Copy and Paste the following script
# Check if Microsoft.Graph module is installed, install if not
if (-not (Get-Module -ListAvailable -Name Microsoft.Graph)) {
    Write-Host "Microsoft.Graph module not found. Installing..."
    Install-Module Microsoft.Graph -Scope CurrentUser -Force
}
Else{
    Write-Host "Microsoft.Graph module is already installed."
}

# Step 1: Connect to Microsoft Graph with required scopes
$requiredScopes = @("Domain.ReadWrite.All", "Directory.ReadWrite.All")
Connect-MgGraph -Scopes $requiredScopes

# Step 2: Validate that the required scopes are granted
$tokenDetails = Get-MgContext
if (-not ($tokenDetails.Scopes -contains "Domain.ReadWrite.All" -and $tokenDetails.Scopes -contains "Directory.ReadWrite.All")) {
    Write-Error "Required scopes not granted. Please re-authenticate with the correct scopes."
    exit
}
Else {
    Write-Host "Required scopes are granted."
}
# Step 3: Federate the domain to TruU IDP copy and paste the content from TruU downlaoded script here.



# Check if domain is already federated before proceeding
$domain = Get-MgDomain -DomainId $dom
if ($domain.AuthenticationType -eq "Federated") {
    Write-Host "Domain $dom is already federated. Converting to managed before proceeding..."
    Update-MgDomain -DomainId $dom -AuthenticationType "Managed"
    # Refresh domain info after conversion
    $domain = Get-MgDomain -DomainId $dom
    if ($domain.AuthenticationType -eq "Managed") {
        Write-Host "Domain $dom successfully converted to managed. Waiting for a few moments before federating."
        Pause -Seconds 60 # Wait for a few seconds to ensure the change is applied
    } else {
        Write-Error "Failed to convert $dom to managed. Aborting federation."
        exit
    }
}

# Proceed with federation
New-MgDomainFederationConfiguration -DomainId $dom -DisplayName $brandName -PassiveSignInUri $passiveLogOnIdpUri -SigningCertificate $signingCert -IssuerUri $issuerUri -SignOutUri $logoffIdpUri -MetadataExchangeUri $metadataExchangeUri -PreferredAuthenticationProtocol $protocol -FederatedIdpMfaBehavior $mfaBehavior
Write-Host "Domain federated to TruU successfully."

# Step 4: Validate federation
$domain = Get-MgDomain -DomainId $dom
if ($domain.AuthenticationType -eq "Federated") {
     Write-Host "Federation validated for $dom."
} else {
    Write-Error "Federation not applied. Please check the configuration."
}
Step 3: Open the script download from the TruU Admin Console Step 4: Copy the following section and paste it under Step 3 of the Powershell script

Ensuring All Users in the Federated Domain Have “ImmutableId” Field Configured

All users from the federated domain must have ImmutableId field specified. For existing users run a powershell command similar to this one: Set-MsolUser -UserPrincipalName “test1@exitcode.net” -ImmutableId “test1@exitcode.net To create a new user, use Powershell: New-MsolUser -UserPrincipalName “test2@exitcode.net” -ImmutableId “test2@exitcode.net” -DisplayName “Test User 2” Note, once you federate a domain, you won’t be able to create users for that domain in Entra Portal directly. In that case, only two options are available: Use New-MsolUser command Use Entra ID Connect sync

Testing Federated Authentication

After all of the above steps have been completed, test the federated authentication. Try to sign into Entra Portal or Office365 with one of test AAD users. You should be redirected to TruU authentication page. Once you approve the request on your mobile device, you should be automatically signed into portal or office.

Reverting Federation

To revert federation and switch authentication back to managed mode, you can use the PowerShell command:
    Update-MgDomain -DomainId "#Domain name" -AuthenticationType "Managed"


Prerequisites

Domain Properties

Before federating an Entra ID domain with TruU, review all configured domains within the customer’s Microsoft Entra ID tenant. The domain to be federated must meet the following prerequisites:
  • The domain MUST be in a Verified state.
  • The domain CANNOT be the Primary domain.
  • The domain CANNOT be the default onmicrosoft.com domain created with the tenant.
In the example below, the demotruu.com domain meets all the prerequisites above and is eligible for federation with TruU. The demotruu.onmicrosoft.com domain is not eligible because it is the default suffix created with the tenant, and the domain is configured as the Primary domain (the Primary domain determines the default suffix assigned when new user accounts are created). Image 1! 3 If the domain does not meet the Microsoft Entra ID federation prerequisites, the federation command will fail. The example below shows the error displayed when attempting to federate the default onmicrosoft.com domain with TruU. Image 2! 4

Reverting a Federated Domain

Although users will not be locked out of Microsoft Entra ID during a domain cut-over, it is recommended to keep the revert command available in case the domain needs to be returned from Federated to Managed authentication. The example below demonstrates the complete workflow:
  • Step 1 – Federate the demotruu.com domain to TruU.
  • Step 2 – Verify that the demotruu.com domain has been successfully federated.
  • Step 3 – Revert the demotruu.com domain back to Managed authentication and verify the updated status.
Image 3! 4

Federating the Default onmicrosoft.com Domain

The default onmicrosoft.com domain created for a Microsoft 365 tenant cannot be federated with TruU or any third-party identity provider. For cloud-only organizations that only use the default onmicrosoft.com domain, complete the following steps before federation:
  1. Create a secondary custom domain.
  2. Change the UPN suffix for all users to the new custom domain.
  3. Configure the new custom domain as the Primary domain.
  4. Verify that users can successfully sign in to Microsoft Entra ID and access federated resources using the new domain suffix.
  5. After completing these steps, proceed with federating the new custom domain with TruU.
Image 4! 3

Immutable ID

Another federation prerequisite is the presence of an On-premises Immutable ID for every synchronized user. An Immutable ID is automatically populated for users synchronized from on-premises Active Directory to Microsoft Entra ID. For cloud-only users, the provided PowerShell scripts can be used to manually configure the Immutable ID by using the user’s UPN as the Immutable ID value.
Image 5! 3
Before running Command
Image 6! 3
After running Command

Account Creation After Federation

For cloud-only customers whose users are created directly in Microsoft Entra ID (and are not synchronized from on-premises Active Directory), new user accounts must be created programmatically using the provided PowerShell scripts after the domain has been federated with TruU. This is required because Microsoft Entra ID does not allow account creation, modification, or delegation directly through the portal for the federated domains.