> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truu.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Federating Entra ID Domain to TruU for Authentication
> This guide provides detailed instructions on configuring the TruU Entra ID Adapter. This adapter enables Entra ID to communicate with TruU Identity Server(s) and the TruU Identity Platform for passwordless authentication to Entra ID applications. The steps to integrate TruU with Entra ID for SSO include registering a custom domain in EID, creating an Entra ID adapter in TruU Admin Console, setting up Entra ID to TruU federation using a PowerShell script, ensuring all users in the federated domain have “ImmutableId” field configured, and testing federated authentication.
### 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**
**Step 5:** Click **Apply**. This will download a PowerShell script needed to setup federation in AAD
### 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
```powershell theme={null}
# 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](mailto:test1@exitcode.net)” -ImmutableId “[test1@exitcode.net](mailto:test1@exitcode.net)”
To create a new user, use Powershell:
New-MsolUser -UserPrincipalName “[test2@exitcode.net](mailto:test2@exitcode.net)” -ImmutableId “[test2@exitcode.net](mailto: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:
```powershell theme={null}
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**](http://onmicrosoft.com) domain created with the tenant.
In the example below, the [**demotruu.com**](http://demotruu.com) domain meets all the prerequisites above and is eligible for federation with TruU. The [**demotruu.onmicrosoft.com**](http://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).
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**](http://onmicrosoft.com) domain with TruU.
## 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**](http://demotruu.com) domain to TruU.
* **Step 2** – Verify that the [**demotruu.com**](http://demotruu.com) domain has been successfully federated.
* **Step 3** – Revert the [**demotruu.com**](http://demotruu.com) domain back to **Managed** authentication and verify the updated status.
## Federating the Default [onmicrosoft.com](http://onmicrosoft.com) Domain
The default [**onmicrosoft.com**](http://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**](http://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.
## 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.
*Before running Command*
*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.