Entra Documentation To Get Setup In Azure & Entra ID

User Guide: Setting Up a Federated Domain in Microsoft Entra ID

This guide walks you through the two main phases of configuring a custom domain for Single Sign-On (SSO) with an external Identity Provider (IdP), Realsmart:

Part 1: Adding and verifying your custom domain within the Microsoft Entra admin center.
Part 2: Using a PowerShell script to configure the domain for federation, which directs authentication requests to your external IdP.
Part 3: Test and final steps

Part 1: Add and Verify Your Custom Domain

Before you can federate a domain, you must first prove to Microsoft that you own it.

Prerequisites

Global Administrator Role: You need an account with Global Administrator permissions in your Entra ID tenant.
Domain Registrar Access: You need access to the DNS management panel for your custom domain (e.g., CloudFlare, quite often we at Realsmart manage this).

Step-by-Step Instructions

Sign in to Entra ID:
- Go to the Microsoft Entra admin center.
- Sign in with your Global Administrator account.
- Navigate to Custom Domain Names:
- In the left-hand menu, go to Show more > Select Settings > Domain names.
- (Alternatively, use the search bar at the top to find "Domain names").
- Add Your Custom Domain:
  - At the top of the "Domain names" blade, click + Add custom domain.
  - In the text box, type your full domain name (e.g., myschool.co.uk).
  - Click the Add domain button.
  - Get Verification Details:
  - Entra ID will now display a pop-up window with the DNS records you need to add to your domain registrar. This is typically a TXT record.
  - The window will show:
  - Record type: TXT
  - Alias or Host name: @ (or school.co.uk.)
  - Value (Points to address): MS=msXXXXXXXX (this is your unique verification code)
  - TTL: 3600 (or 1 hour)
  - Keep this window open.
    - Add DNS Record at Your Registrar:
    - Log in to your domain registrar's website.
    - Navigate to the DNS management section for your domain.
    - Create a new TXT record using the exact values provided by Entra ID in the previous step.
    - Save the new record.
  - Verify the Domain:
  - Wait a few minutes (sometimes up to an hour) for the DNS record to propagate across the internet.
  - Go back to the Entra admin center window you left open.
  - Click the Verify button.
  - Entra ID will check for the TXT record. If found, you will see a green checkmark, and the domain's status will change to Verified.
  - If it fails, wait another 15 minutes and try again.
  - Your domain is now added to Entra ID. Do not set it as your primary domain. It is now ready for federation.

Part 2: Configure Domain Federation via PowerShell

Now you will use the Microsoft Graph PowerShell SDK to tell Entra ID that this domain's users should be authenticated by your external IdP.

Prerequisites

Verified Domain: The domain you added in Part 1 must have a "Verified" status.
PowerShell 7+: It is highly recommended to use a modern version of PowerShell.
Microsoft Graph PowerShell SDK: You must have this module installed. If not, run this command in PowerShell:
IdP Federation Details: You must have the following information from Realsmart:
Signing Certificate: The public key certificate (Base64 encoded, without headers/footers) from your IdP.
Issuer URI: The unique identifier for your IdP.
Passive Sign-In URI: The URL where users will be sent to log in.
Sign-Out URI: The URL where users will be sent upon logout.

Step-by-Step Instructions

Save the PowerShell Script:
Open a text editor (like VS Code or Notepad).
Copy the entire script block below and paste it into the editor.
Save the file as Set-Federation.ps1.

CONNECT TO MICROSOFT GRAPH

This command will open a browser window for you to authenticate (You must sign in as a Global Administrator).

Write-Host "Connecting to Microsoft Graph..." -ForegroundColor Cyan Connect-MgGraph -Scopes "Domain.ReadWrite.All"

Wait for connection

CONFIGURE YOUR VARIABLES

The exact, verified domain name you added in Part 1

$domainName = "domain.co.uk"

The Base64 encoded public signing certificate from your IdP, This is a long string. Ensure there are no line breaks or spaces:

$signingCertificate = "MIIDKzCCAhOgAwIBAgIUTvs5U5uROXQ3TZwUPJzRCaNVBtYwDQYJKoZIhvcNAQELBQAwJTEjMCEGA1UEAwwac21hcnRsb2dpbi5yZWFsc21hcnQuY28udWswHhcNMjUxMDIyMTAyMDQzWhcNMzUxMDIwMTAyMDQzWjAlMSMwIQYDVQQDDBpzbWFydGxvZ2luLnJlYWxzbWFydC5jby51azCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMOpQEz74+zi0DSfyENG5v6gDCq1hMOhjZh/VI0eWJgWKk960c2u3t8VorHHdz6idjMhV1HklhccawqKTb3Iy3ifLmNJC/yu4NucDyLhJm32zapR2x6qy+38AJXaAEZ3BGJIOHJ2kvtQVQsk371YX3g4fnB8M027FM7rbWyRmSDGOxNMbdzoNOGLUd4SnatqxorBU/jXhp7fUFRGolzeTSDHj3fg2UFV+D1F1acapvTTWjZMHiJlZQJZKPVAnrPPQdalzG8yEZkqN9k8Ttqim+OozsgE/BCOr5KFlW9NoqzdtRRoz3YNRF0RDWiz6lQSlaKJlgU1H+mkq4CDJdXgDvUCAwEAAaNTMFEwHQYDVR0OBBYEFGtsRWpEWLKCWKw0+URi9dWEl47TMB8GA1UdIwQYMBaAFGtsRWpEWLKCWKw0+URi9dWEl47TMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAABYxtstUen0idshghtQAsky1LgNBnYonInDLCgpicfRUrcEMZ2r704uMoQRrbUHuLuJMJqGWsHy86vDciM5LWw6oLH7nrl4TEdKd41rBUIjn53CLflIqh0/WS7u/b71bLW2CPcxU9ZT1g/GycHO+6rVKAtg9IZHX5DohrnPnBv4WWpGD7SjdSYDRix0gE3qeAb64lGe1iZPdWOG+nCERPRo0/4546XdXPaR5FxPPPIk0C6/qtbJmyRRw79dDiS3gvzAB/aLqp6uV7UnNAM+PRG0jSfev3jj+Awls6kM2Ysx2IxO5OLLu5THaMDUUxG5ZDYDW9d/qTWRix1FCQt0a7w="

The Issuer URI from your IdP, please note "tenant-id" should be replaced with your tenant ID in Entra.

$issuerUri = "https://smartlogin.realsmart.co.uk/tenant-id"

The Passive Sign-In (login) URL from your IdP, please note the "schoolId" should be replaced with your School ID provided by Realsmart.

$passiveSignInUri = "https://smartlogin.realsmart.co.uk/smartlogin/login?school=schoolId"

The Sign-Out URL from your IdP

$signOutUri = "https://smartlogin.realsmart.co.uk/smartlogin/logout"

A friendly name for this configuration in Entra ID, please note the "schoolId" can be replaced with your School ID provided by Realsmart.

$displayName = "schoolId Realsmart SSO"

CREATE THE FEDERATION CONFIGURATION

Create the parameter object (splat) for the command:

$params = @{ DomainId = $domainName DisplayName = $displayName IssuerUri = $issuerUri PassiveSignInUri = $passiveSignInUri SignOutUri = $signOutUri SigningCertificate = $signingCertificate PreferredAuthenticationProtocol = "saml" # Use "saml" or "wsFed" FederatedIdpMfaBehavior = "acceptIfMfaDoneByFederatedIdp" }

try {

Write-Host "Attempting to create federation configuration for $domainName..." -ForegroundColor Yellow

# This command creates the federation object AND links it to the domain

New-MgDomainFederationConfiguration @params

Write-Host "SUCCESS: Federation configuration created for $domainName." -ForegroundColor Green

Write-Host "It may take a few minutes for the changes to propagate."

} catch {

Write-Host "ERROR: Failed to create federation configuration." -ForegroundColor Red Write-Host $_.Exception.Message

}

VERIFY THE CONFIGURATION

Write-Host "Verifying domain settings..." $domain = Get-MgDomain -DomainId $domainName $domain | Select-Object Id, AuthenticationType

Write-Host "Verifying federation object settings..." Get-MgDomainFederationConfiguration -DomainId $domainName | Select-Object IssuerUri, PassiveSignInUri, SignOutUri

Make sure that you carefully replace the placeholder values for $domainName, $signingCertificate, $issuerUri, $passiveSignInUri, and $displayName with the exact values provided by Realsmart.

Important: The $signingCertificate must be one long string with no line breaks or spaces.

Run the Script:

Open a PowerShell 7 terminal, or an Azure Cloud Shell Terminal.

Paste and run the Script.

A browser window will open. Sign in with your Global Administrator account and consent to the requested permissions (Domain.ReadWrite.All).

The script will continue to run in your PowerShell terminal.

Review the Output:

The script will first attempt to create the federation. You should see the message: SUCCESS: Federation configuration created for school.co.uk.

Next, it will run verification commands. The output should look similar to this:

Verifying domain settings...

Id AuthenticationType

school.co.uk Federated

Verifying federation object settings...

IssuerUri PassiveSignInUri SignOutUri

https://smartlogin.realsmart.co.uk/tenant-id
https://smartlogin.realsmart.co.uk/smartlogin/login... https://smartlogin.realsmart.co.uk/smartlogin/logout

If the AuthenticationType is Federated, your setup was successful.

Part 3: Test and Final Steps

Update User UPNs (if necessary):

Your users must have a UserPrincipalName (UPN) that matches the federated domain to use the new SSO.

In the Entra admin center, update a test user's UPN to use the new domain (e.g., change user@tenant.onmicrosoft.com to user@domain.co.uk).

Test the Sign-In Flow:

Open a new private browsing session (Incognito/InPrivate).

Go to a Microsoft login page, such as https://portal.office.com or https://myapps.microsoft.com.

Enter the UPN of your test user (e.g., test.user@domain.co.uk) and press Enter or Tab.

Expected Result: You should be instantly redirected to your IdP's login page (the $passiveSignInUri you configured). You should not see the Microsoft password prompt.

Troubleshooting:

Error running script: Double-check that all variables are correct, especially the $signingCertificate (no spaces/breaks) and that the $domainName exactly matches the verified domain.

Not redirected: The AuthenticationType for the domain may not be "Federated". Re-run the verification part of the script. It can also take a few minutes for the change to take effect.

IdP shows an error: Your IdP may not be configured correctly to trust Microsoft Entra ID as a Service Provider. Check your IdP's SAML configuration.