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
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".
- The original issue was that the POST request referenced the newer Microsoft Graph endpoint (graph.microsoft.com) - which ironically doesn't actually support the "/promote" action, rather than the required Azure Graph endpoint (graph.windows.net). The Docs article has since been corrected;
- 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.
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.
Prerequisites
- 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.
Authenticating
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 graph.windows.net endpoint (not the more recent graph.microsoft.com endpoint!)
Connect-AzAccount -Tenant mytenant.onmicrosoft.com;
$AadToken = (Get-AzAccessToken -ResourceUri 'https://graph.windows.net').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 'https://graph.windows.net/{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 'https://graph.windows.net/e1e1000e-2fd9-4915-b086-b123ffa4321a/domains/child.mydomain.com/promote?api-version=1.6'
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:
- You need to include the "Content-Type"="application/json" in the header, and;
- 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.
Cheers,
Lain