How To: Change the authentication for an Azure child domain from Federated to Managed.

Silver Contributor

Hi, folks.


This is a quick article intended to provide some more granularity on a specific topic relating to the Microsoft Docs article that outlines how to convert an Azure child domain from Federated (which is inherited from its parent domain) to Managed.


The Microsoft Docs reference article

Change subdomain authentication type using PowerShell and Graph - Azure Active Directory - Microsoft...


The original problems with the Docs article

These problems relate specifically to the step immediately below the Change subdomain to a root domain heading, which is a POST request ending in "/promote".


  1. The original issue was that the POST request referenced the newer Microsoft Graph endpoint ( - which ironically doesn't actually support the "/promote" action, rather than the required Azure Graph endpoint ( The Docs article has since been corrected;
  2. The second issue is that the document is nowhere near detailed enough for the likely intended audience, which is administrators, consultants and the likes.

Issue 2 is the reason I'm putting this additional information out here, though hopefully the official article will be updated so that it's actually navigable by the people most likely to read it.


Rather than repeating the details around issue 1, here's a link to the GitHub issue that provides the detail as well as screenshots.


Change subdomain to a root domain process failing the POST .../promote step. · Issue #92957 · Micros...


Detailed look at the /promote step

All Microsoft gives you is the following abstract guidance relating to the /promote step. There's no guidance at all on how to authenticate or how to action the POST.




Where the intended audience is likely more familiar with using Microsoft's various suites of PowerShell modules, dealing natively with REST calls doesn't come naturally. This article aims to fill these gaps (hopefully temporarily.)


The steps below were actioned under Windows PowerShell 5.1 while authenticating against Azure AD using an account with Global Administrator membership.



  • The Az.Accounts module from Microsoft (version 2.8.0 at the time of writing);
  • You'll need to know your Tenant ID GUID for some of the commands;
  • You'll need to have registered and verified your child domain.

You can install this module for just yourself or per device - it doesn't impact the following steps.


For yourself

Install-Module -Name Az.Accounts -Force;


For the device (aka all users)

(You will need to be running in an elevated PowerShell session for this to work)

Install-Module -Name Az.Accounts -Scope AllUsers -Force;


For reference, here's my list of domains, where the parent domain is underlined in green and the child I want to change is underlined in red (noting it's now showing as Managed where it was set to Federated prior.)



Now, onto the detail around the /promote step.



Most of these steps are basic, so I'll bunch up the commands to save space.


Here, we are simply authenticating to Azure AD and fetching a token for the endpoint (not the more recent endpoint!)

Connect-AzAccount -Tenant;
$AadToken = (Get-AzAccessToken -ResourceUri '').Token;


Actioning the /promote against the child domain

Now we are ready to action the vague POST reference from the Docs article.

# Invoke-RestMethod -Method Post -Headers @{Authorization="Bearer $($AadToken)"; "Content-Type"="application/json"} -Uri '{your Tenant GUID goes here}/domains/{your child domain name goes here}/promote?api-version=1.6'

# For example:
Invoke-RestMethod -Method Post -Headers @{Authorization="Bearer $($AadToken)"; "Content-Type"="application/json"} -Uri ''


Obviously, you need to use your own tenant GUID and child domain references in that command.


The two key components here that do not feature in the Docs article are:


  1. You need to include the "Content-Type"="application/json" in the header, and;
  2. You must include the API version directive! (the "?api-version=1.6" part)


If you forget to include either, you will run into errors - as outlined in the GitHub issue linked above - and your child domain will not promote.


A successful promotion looks something like this:



Verification and finishing up

If you receive this response then you can continue with the remaining steps from the Docs article - I won't go into detail other than to include a screenshot of them as confirmation they do work as described - sort of.


I say "sort of" because after the step above, my child domain changed from Federated to Managed meaning the Set-MsolDomainAuthentication wasn't necessary.



Still, here's the "official" process showing the Set-MsolDomainAuthentication step:



And finally, you can now use this child domain freely with Azure AD when creating new, Azure AD-native accounts.



Hopefully this helps until the Docs article is improved upon.




0 Replies