Change subdomain authentication type in Microsoft Entra ID

  • Article
  • 02/14/2025

After a root domain is added to Microsoft Entra ID, part of Microsoft Entra, all subsequent subdomains added to that root in your Microsoft Entra organization automatically inherit the authentication setting from the root domain. However, if you want to manage domain authentication settings independently from the root domain settings, you can now with the Microsoft Graph API. For example, if you have a federated root domain such as contoso.com, this article can help you verify a subdomain such as child.contoso.com as managed instead of federated.

In the Azure portal, when the parent domain is federated and the admin tries to verify a managed subdomain on the Custom domain names page, the page displays a 'Failed to add domain' error with the reason "One or more properties contains invalid values." If you try to add this subdomain from the Microsoft 365 admin center, you receive a similar error. For more information about the error, see A child domain doesn't inherit parent domain changes in Office 365, Azure, or Intune.

Because subdomains inherit the authentication type of the root domain by default, you must promote the subdomain to a root domain in Microsoft Entra ID using the Microsoft Graph so you can set the authentication type to your desired type.

Warning

This small script an example for demonstration purposes. If you intend to use it in your environment, test first. You should adjust the code to meet your requirements.

Add the subdomain

  1. Use PowerShell to add the new subdomain, which has its root domain's default authentication type. The Microsoft Entra ID and Microsoft 365 admin centers don't yet support this operation.

    # Connect to Microsoft Graph with the required scopes
    Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "Domain.ReadWrite.All"
    
    # Define the parameters for the new domain
    $domainParams = @{
        Name = "child6.mydomain.com"
        AuthenticationType = "Federated"
    }
    
    # Create a new domain with the specified parameters
    New-MgDomain @domainParams

  1. Use the following example to GET the domain. Because the domain isn't a root domain, it inherits the root domain authentication type. Your command and results might look as follows, using your own tenant ID:

    GET https://microsoftgraph.chinacloudapi.cn/v1.0/domains/foo.contoso.com/

Return:
  {
      "authenticationType": "Federated",
      "availabilityStatus": null,
      "isAdminManaged": true,
      "isDefault": false,
      "isDefaultForCloudRedirections": false,
      "isInitial": false,
      "isRoot": false,          <---------------- Not a root domain, so it inherits parent domain's authentication type (federated)
      "isVerified": true,
      "name": "child.mydomain.com",
      "supportedServices": [],
      "forceDeleteState": null,
      "state": null,
      "passwordValidityPeriodInDays": null,
      "passwordNotificationWindowInDays": null
  },

Change subdomain to a root domain

Use the following command to promote the subdomain:

POST https://microsoftgraph.chinacloudapi.cn/v1.0/{tenant-id}/domains/foo.contoso.com/promote

Promote command error conditions

Scenario Method Code Message
Invoking API with a subdomain whose parent domain is unverified POST 400 Unverified domains can't be promoted. Verify the domain before promotion.
Invoking API with a federated verified subdomain with user references POST 400 Promoting a subdomain with user references isn't allowed. Migrate the users to the current root domain before promotion of the subdomain.

Change the subdomain authentication type to managed

Important

If you change the authentication type for a federated subdomain, you should take note of the existing federation configuration values before completing the next steps. The information is needed if you decide to reimplement federation before promoting a domain.

  1. Use the following command to change the subdomain authentication type:

    Connect-MGGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "Domain.ReadWrite.All", "Directory.AccessAsUser.All"
Update-MgDomain -DomainId "test.contoso.com" -BodyParameter @{AuthenticationType="Managed"}

  2. Verify via GET in Microsoft Graph API that subdomain authentication type is now managed:

    GET https://microsoftgraph.chinacloudapi.cn/v1.0/domains/foo.contoso.com/

Return:
  {
      "authenticationType": "Managed",   <---------- Now this domain is successfully added as Managed and not inheriting Federated status
      "availabilityStatus": null,
      "isAdminManaged": true,
      "isDefault": false,
      "isDefaultForCloudRedirections": false,
      "isInitial": false,
      "isRoot": true,   <------------------------------ Also a root domain, so not inheriting from parent domain any longer
      "isVerified": true,
      "name": "child.mydomain.com",
      "supportedServices": [
          "Email",
          "OfficeCommunicationsOnline",
          "Intune"
      ],
      "forceDeleteState": null,
      "state": null,
      "passwordValidityPeriodInDays": null,
      "passwordNotificationWindowInDays": null }

Next steps