Enable Federated Authentication for an Azure AD tenant with PowerShell

For organizations that have deployed Azure AD Connect and are synchronizing their on-premise identities to Azure AD, you may start of with setting up Password Synchronization and letting Azure AD handle your authentications instead of using Active Directory Federation Services (ADFS). However, there are many good reasons to implement (not just for security considerations) but also for additional capabilities like forcing Multi-Factor Authentication when end users are outside of the corporate network boundaries. If your Azure AD tenant is currently set for Password Synchronization, I’d recommend looking into changing to Federated Authentication.
Converting an Azure AD tenant to Federated Authentication is a fairly easy task. It requires some PowerShell knowledge and access to a Global Admin account. In this post, I’ve decided to share the script I normally use to accomplish the switch from Password Synchronization to Federated Authentication. Making this switch though, requires that you’ve successfully deployed a functioning ADFS Farm in your on-premise environment, which is not covered in this post.

Script

Below you’ll find the script that I’m using when converting an Azure AD tenant from Password Synchronization to Federated Authentication. This script will first prompt for your Global Admin username and password, which is required in order to setup a connection to your tenant. Next the ADFS context specified in the Computer parameter is set and a couple of validation tests are performed in order to make sure that you’re not attempting to convert an Azure AD tenant that’s already set for Federated Authentication.

<#
.SYNOPSIS
    Convert a top-level verified domain name from managed to federated, and enable a trust between
    on-premise Active Directory Federation Services and an Azure Active Directory tenant.
.DESCRIPTION
    This script will setup a trust between your on-premise Active Directory Federation Services and an Azure Active Directory tenant, by converting to from managed to federated.
    It supports multiple top-level domains by specifying the SupportMultipleDomain parameter.
.PARAMETER Computer
    Specify the internal FQDN of the Primary ADFS server that will be used as context for configuration.
.PARAMETER DomainName
    Specify the top-level verified domain for your Azure Active Directory tenant that will be converted to federated authentication.
.PARAMETER SupportMultipleDomain
    Use this switch if you need support for multiple top-level domains.
.EXAMPLE
    Convert a managed domain name called 'domain.com' to federated authentication and use an on-premise Active Directory Federation Services primary server called 'ADFS01.domain.local' as the configuration context:
    .\Convert-AADDomainToFederated.ps1 -Computer ADFS01.domain.local -DomainName domain.com
    Convert a managed domain name called 'domain.com' to federated authentication with support for additional domains and use an on-premise Active Directory Federation Services primary server called 'ADFS01.domain.local' as the configuration context:
    .\Convert-AADDomainToFederated.ps1 -Computer ADFS01.domain.local -DomainName domain.com -SupportMultipleDomain
.NOTES
    FileName:    Convert-AADDomainToFederated.ps1
    Author:      Nickolaj Andersen
    Contact:     @NickolajA
    Created:     2016-09-12
    Updated:     2016-09-12
    Version history:
    1.0.0 - (2016-09-12) Script created
#>
[CmdletBinding(SupportsShouldProcess=$true)]
param(
    

[parameter(Mandatory=$true, HelpMessage=”Specify the internal FQDN of the Primary ADFS server that will be used as context for configuration.”)]

[ValidateNotNullOrEmpty()] [ValidateScript({Test-Connection -ComputerName $_ -Count 1 -Quiet})] [string]$Computer,

[parameter(Mandatory=$true, HelpMessage=”Specify the top-level verified domain for your Azure Active Directory tenant that will be converted to federated authentication.”)]

[ValidateNotNullOrEmpty()] [string]$DomainName,

[parameter(Mandatory=$false, HelpMessage=”Use this switch if you need support for multiple top-level domains.”)]

[ValidateNotNullOrEmpty()] [switch]$SupportMultipleDomain ) Begin { # Import MSOnline module try { Import-Module -Name MsOnline -ErrorAction Stop -Verbose:$false } catch [System.Exception] { Write-Warning -Message “Unable to load the Azure Active Directory PowerShell module” ; break } } Process { # Get credentials for Microsoft Online Services $Credentials = Get-Credential -Message “Enter the username and password for a Global Admin account:” -Verbose:$false # Continue processing depending on whether credentials was specified or not if ($Credentials -ne $null) { # Connect to Microsoft Online Service try { Write-Verbose -Message “Attempting to connect to Microsoft Online Services” Connect-MsolService -Credential $Credentials -ErrorAction Stop -Verbose:$false } catch [System.Exception] { Write-Warning -Message “Unable to connect to Microsoft Online Services, error message was: $($_.Exception.Message)” ; break } # Create ADFS context (computer parameter should be the internal FQDN of the Primary ADFS server) try { Write-Verbose -Message “Setting on-premise Active Directory Federation Services computer context” if ($PSCmdlet.ShouldProcess($Computer, “Set context”)) { Set-MsolADFSContext -Computer $Computer -ErrorAction Stop -Verbose:$false } } catch [System.Exception] { Write-Warning -Message “An issue occured while configuring ADFS computer context, error message was: $($_.Exception.Message)” ; break } # Get specified domain in order to validate that specified domain name exists, not already configured for federated authentication and has been verified try { Write-Verbose -Message “Retrieving domain name from Microsoft Online Services” $MsolDomain = Get-MsolDomain -DomainName $DomainName -ErrorAction Stop -Verbose:$false } catch [System.Exception] { Write-Warning -Message “An issue occured while retrieving domain from Microsoft Online Services, error message was: $($_.Exception.Message)” ; break } # Validate that the domain name has been verified if ($MsolDomain.Status -like “Verified”) { if ($MsolDomain.Authentication -like “Managed”) { try { # Construct table of parameters for converting domain name to federated from standard $MsolFederatedDomainArgs = @{ DomainName = $DomainName ErrorAction = “Stop” Verbose = $false } # Add support for multiple domains to parameter table if ($PSBoundParameters.ContainsKey(“SupportMultipleDomain”)) { $MsolFederatedDomainArgs.Add(“SupportMultipleDomain”, $true) } # Convert top-level domain name to federated authentication Write-Verbose -Message “Converting domain name ‘$($MsolDomain.Name)’ to federated authentication” if ($PSCmdlet.ShouldProcess($DomainName, “Convert”)) { Convert-MsolDomainToFederated @MsolFederatedDomainArgs } } catch [System.Exception] { Write-Warning -Message “An issue occured while converting domain name to federated authentication, error message was: $($_.Exception.Message)” } # Output federation properties to pipeline if param is specified if ($PSBoundParameters.ContainsKey(“ShowFederationProperties”)) { Get-MsolFederationProperty –DomainName $DomainName -Verbose:$false } } else { Write-Warning -Message “An issue occured while validating the domain name authentication configuration. Domain name ‘$($MsolDomain.Name)’ is not currently set for Managed authentication” ; break } } else { Write-Warning -Message “An issue occured while validating if domain name has been verified. Domain name ‘$($MsolDomain.Name)’ is not currently verified, please complete the verification process before you continue converting the domain name” ; break } } else { Write-Warning -Message “Unable construct credentials object, error message was: $($_.Exception.Message)” ; break } }

Convert to Federated Authentication with PowerShell
If you environment fulfills the requirements of converting from Password Synchronization to Federated Authentication, i.e. you’ve deployed an ADFS Farm correctly in your on-premise environment and made it available both internally and externally, the final step is to simply convert the tenant which can be accomplished with the above script. This script takes a couple of parameters. First off, we need to specify an ADFS server for the script in order for it to configure the relying party trust settings between the Active Directory Federation Services (AD FS) and you tenant. As a best practice, you should specify your Primary ADFS server in the farm for the Computer parameter. Secondly, we need to specify the Azure AD verified domain name for the DomainName parameter. This would be the top-level domain name that you’ve verified in your tenant. Lastly, the script supports configuration for multiple domains, meaning that if you have multiple top-level domains e.g. domainA.com and domainB.com verified, you’ll need to specify the SupportMultipleDomain switch.
In order to leverage the above script, follow the process outlined below:
1. Save the script from above as e.g. Convert-AADDomainToFederated.ps1.
2. Open an elevated PowerShell console and run the following command, assuming that the primary ADFS server is ADFS01.corp.scconfigmgr.com and the domain name is scconfigmgr.com (not supporting multiple domains):

.\Convert-AADDomainToFederated.ps1 -Computer ADFS01.corp.scconfigmgr.com -DomainName scconfigmgr.com -Verbose

3. When prompted, provide credentials for a Global Admin account.

4. Click OK and let the conversion take place. Since the Verbose switch has been specified, the script will output the actions being taken.

You’ve now converted your domain name from Standard Authentication to Federated Authentication.