Updating Entra ID Federation with TruU

Over time you may need to update the federation configuration between your Entra ID domain and TruU — most commonly because the signing certificate on the existing adapter is nearing expiration and needs to be rotated. This guide walks through generating a fresh configuration and applying it to your existing federated domain. Updating federation does not require you to re-register your custom domain in Entra ID or repeat the initial onboarding steps. The process is performed through a combination of actions in the TruU Admin Console and PowerShell scripts. You will generate a new certificate for the Entra ID federation adapter in the TruU Admin Console, stage that certificate in Entra using PowerShell (so your federation accepts assertions signed by both the old and new certificate), rotate the

Generate a new certificate for the Entra ID fedefration adapter in the TruU Admin Console
Run a PowerShell script to stage the new certificate in Entra (enabling trust for both old and new certificates)
Rotate the certificate used for assertion signing in the TruU Admin Console (now TruU begins signing assertions with the new certificate)
Validate that federation continues functioning properly
Run a PowerShell script to promote the new certificate into the primary slot
Finalize the transaction in the TruU Admin Console to mark the rotation as complete

Prerequisites

Global administrator role in the Entra ID tenant
Access to the TruU Admin Console for the environment being updated
The domain must already be federated with TruU (see Federating Entra ID Domain to TruU for Authentication)
PowerShell or PowerShell ISE, run as administrator, on a Windows machine with network access to Entra ID
The Microsoft Graph PowerShell module installed, with an active Connect-MgGraph session authenticated as an account with permission to manage domain federation settings (Domain.ReadWrite.All)

Generating a New Federation Signing Certificate

Navigate to Integrations and find the appropriate Entra ID adapter
Click on the adapter to open the Edit dialog window
Click Rotate signing certificate to generate the new certificate

Note: You can keep Edit Adapter dialog window open. If you close it, you can click on the adapter to open the dialog and resume.

Stage the New Certificate Using stage.ps1 PowerShell

Run PowerShell ISE
Copy the stage.ps1 script below into a new file
Copy the Domain value from the Edit Adapter dialog in the TruU Admin Console
Paste the copied Domain value as the value for the $domain variable in the stage.ps1 script
Do the same with the new signing certificate, pasting it into the $nextCertificate variable in the PowerShell script
On the PowerShell command line, execute Connect-MgGraph -Scopes "Domain.ReadWrite.All"
Run the stage.ps1 PowerShell script

Note: The script will output a few lines describing the steps being executed. Analyze and correct any errors before continuing.

stage.ps1 PowerShell Script

#==============================================================================
# Run this script to stage a new federation signing certificate.
# After executing this script, your Entra ID tenant will accept
# assertions signed by the previous certificate and by the staged certificate.
#==============================================================================

#=============================
# Edit the script here. 
# Copy the values from your adapter into these variables.
#=============================
$domain = ''
$nextCertificate = ''

#=============================
# No need to edit below this
#=============================

# Test Graph authentication status
Write-Host "Checking to see if session is logged into Graph..."
$graphContext = Get-MgContext
if ($null -ne $graphContext) {
    Write-Host "Success: Logged into Graph as $($graphContext.Account) (Tenant: $($graphContext.TenantId))" -ForegroundColor Green
    # Check if the required scope is in the Scopes array (case-insensitive)
    if ($graphContext.Scopes -contains "Domain.ReadWrite.All") {
        Write-Host "Success: 'Domain.ReadWrite.All' scope is present." -ForegroundColor Green
    } else {
        Write-Warning "Missing Scope: Current session does not have 'Domain.ReadWrite.All'."
        Write-Host "Active scopes: $($graphContext.Scopes -join ', ')" -ForegroundColor Yellow
        Write-Host "Please check the roles attached to the user and try again." -ForegroundColor Yellow
        exit
    }
} else {
    Write-Warning "Please log into Graph using Connect-MgGraph -Scopes \"Domain.ReadWrite.All\""
    exit
}

# Validate existing federation settings for the domain
$existing = Get-MgDomainFederationConfiguration -DomainId $domain
if (-not $existing) {
    throw "No existing federation configuration found for '$domain'. This script only rotates an already-federated domain."
}

# Extract the federation ID (UUID) into a variable
$fedId = $existing.Id
Write-Host "Found existing federation config for $dom (InternalDomainFederationId: $fedId)" -ForegroundColor Green

# Update the federation configuration's staged signing certificate.
# This will not change the existing signing certificate.
# After executing this, the tenant will accept assertions signed by the existing
# signing certificate and assertions signed by the next signing certificate.
Update-MgDomainFederationConfiguration `
-DomainId $domain `
-InternalDomainFederationId $fedId `
-NextSigningCertificate $nextCertificate

Write-Host "New signing certificate staged for $domain" -ForegroundColor Green
Write-Host "`nIn your TruU admin console, click to confirm that the stage script has been run." -ForegroundColor Green
#=============================
# End of script
#=============================

Begin Using the New Certificate

Click the I’ve run the stage script - Confirm button in the TruU Admin Console
In a minute or two TruU will begin using the new certificate
Open a new browser (and optionally a SAML tracer extension) and test SSO by logging into https://login.microsoftonline.com/ or any federated application
If using a SAML tracer, you should see the new certificate in the WS-Fed/SAML assertion sent to https://login.microsoftonline.com/login.srf

Note: You can keep the Edit Adapter dialog open and proceed to the next step.

Promoting the New Certificate

At this point you should see a note in the Edit Adapter dialog window stating, “TruU is now signing with the new certificate.” Now it is time to promote the new certificate, removing the old certificate from your federation configuration in Entra ID.

Copy the promote.ps1 PowerShell script below into a new file in PowerShell ISE
Update the $domain and $signingCertificate variables in the script with the values from the Edit Adapter dialog (copy the Domain and New Signing Certificate values from the dialog window into the promote.ps1 script)
Run the promote.ps1 script

Note: The script will output a few lines describing the steps being executed. Analyze and correct any errors before continuing.

promote.ps1 PowerShell Script

#==============================================================================
# Run this script to promote a staged federation signing certificate.
# After executing this script, your Entra ID tenant will only accept
# assertions signed by a single certificate.
#==============================================================================

#=============================
# Edit the script here. 
# Copy the values from your adapter into these variables.
#=============================
$domain = ''
$signingCert = ''

#=============================
# No need to edit below this
#=============================

# Test Graph authentication status
Write-Host "Checking to see if session is logged into Graph..."
$graphContext = Get-MgContext
if ($null -ne $graphContext) {
    Write-Host "Success: Logged into Graph as $($graphContext.Account) (Tenant: $($graphContext.TenantId))" -ForegroundColor Green
    # Check if the required scope is in the Scopes array (case-insensitive)
    if ($graphContext.Scopes -contains "Domain.ReadWrite.All") {
        Write-Host "Success: 'Domain.ReadWrite.All' scope is present." -ForegroundColor Green
    } else {
        Write-Warning "Missing Scope: Current session does not have 'Domain.ReadWrite.All'."
        Write-Host "Active scopes: $($graphContext.Scopes -join ', ')" -ForegroundColor Yellow
        Write-Host "Please check the roles attached to the user and try again." -ForegroundColor Yellow
        exit
    }
} else {
    Write-Warning "Please log into Graph using Connect-MgGraph -Scopes \"Domain.ReadWrite.All\""
    exit
}

# Validate existing federation settings for the domain
$existing = Get-MgDomainFederationConfiguration -DomainId $domain
if (-not $existing) {
    throw "No existing federation configuration found for '$domain'. This script only rotates an already-federated domain."
}

# Extract the federation ID (UUID) into a variable
$fedId = $existing.Id
Write-Host "Found existing federation config for $domain (InternalDomainFederationId: $fedId)" -ForegroundColor Green

# Update the federation configuration's signing certificate.
# This should use the NextSigningCertificate configured in the stage.ps1 script.
Update-MgDomainFederationConfiguration `
-DomainId $domain `
-InternalDomainFederationId $fedId `
-SigningCertificate $signingCert

Write-Host "Certificate rotation completed for $domain" -ForegroundColor Green
Write-Host "`nIn your TruU admin console, click to confirm that the promote script has been run." -ForegroundColor Green
#=============================
# End of script
#=============================

Finalizing the Rotation

Click the I’ve run the promote script - Confirm button in the Edit Adapter dialog
Click Accept on the Complete Rotation confirmation dialog window

Note: The old certificate is no longer paired with this Entra ID federation adapter. You may delete the old certificate and private key from the Integrations > Key Store page in the TruU Admin Console.

Federating Entra ID Domain to TruU for Authentication

Overview

TruU Tenant Setup

Infrastructure Configuration

TruU Adapters & Integrations

Deploy TruU on Windows

Deploy TruU on macOS

Deploy Frontline Access

Deploy Continuous Authentication

Admin Console Overview

Updating Entra ID Federation with TruU

Prerequisites

Generating a New Federation Signing Certificate

Stage the New Certificate Using stage.ps1 PowerShell

stage.ps1 PowerShell Script

Begin Using the New Certificate

Promoting the New Certificate

promote.ps1 PowerShell Script

Finalizing the Rotation

​Prerequisites

​Generating a New Federation Signing Certificate

​Stage the New Certificate Using stage.ps1 PowerShell

​stage.ps1 PowerShell Script

​Begin Using the New Certificate

​Promoting the New Certificate

​promote.ps1 PowerShell Script

​Finalizing the Rotation

​Related Documentation

Prerequisites

Generating a New Federation Signing Certificate

Stage the New Certificate Using stage.ps1 PowerShell

stage.ps1 PowerShell Script

Begin Using the New Certificate

Promoting the New Certificate

promote.ps1 PowerShell Script

Finalizing the Rotation

Related Documentation