There are several methods to create the Relying Party Trust (RPT) between Active Directory Federation Services (AD FS) and Azure Active Directory automatically:
- Using Azure AD Connect with the Use an existing AD FS farm option or the Configure a new AD FS farm option, when configuring Federation with AD FS as the authentication method.
- Using the Convert-MsolDomainToFederated Windows PowerShell cmdlet from the MSOnline PowerShell Module.
However, sometimes you can’t use the above methods. In this case, the only logical conclusion is to create the Relying Party Trust manually. But how do you create then exact same functionality as when you use the above method… or in the case of the Convert-MsolDomainToFederated cmdlet method, the full functionality?
I wrote this blogpost, after I’ve successfully switched the custom DNS domain name in Azure Active Directory to AD FS on a remote workstation, but wasn’t privileged to install the MSOnline PowerShell Module on an AD FS server, create Relying Party Trusts or domain-join the Azure AD Connect installations… I had to provide the changes I needed to a more privileged person. When I ran Convert-MSOLDomaintoFederated before having the RPT created manually, it failed. After I had the RPT created manually, it succeeded. Running Update-MSOLFederatedDomain fixed the last glaring errors. I have full confidence you can come up with your own reasons and situations beyond this us ecase…
This blogpost details the steps, relying solely on cmdlets from the ADFS PowerShell module. It’s a four-step procedure:
- Creating the Relying Party Trust
- Configuring the Relying Party Trust beyond defaults
- Setting the claims issuance authorization rule
- Setting the claims issuance transformation rules
The settings for the Relying Party Trust that is created with the below steps are an identical copy of the Relying Party Trust created with Azure AD Connect version 188.8.131.52. These settings may change over time. While all effort was aimed at providing the best information, it may no longer be accurate.
Creating the Relying Party Trust
Perform these steps to create the Relying Party Trust (RPT):
- Sign in to an AD FS Server with local administrator privileges. When the AD FS farm leverages the Windows Internal Database (WID) replication method, sign in to the primary AD FS server, as it is the only AD FS server that has read/write access to the ADFSConfiguration database.
- Open an elevated Windows PowerShell screen.
- Enter the following lines of PowerShell:
-Name "Microsoft Office 365 Identity Platform" –MetadataUrl "https://nexus.microsoftonline-p.com/federationmetadata/2007-06/federationmetadata.xml"
Configuring the Relying Party Trust beyond defaults
With the above steps, many of the settings are configured perfectly for the Relying Party Trust. However, we need to set three more settings to make it perfect.
The first setting defines the additional WS-Fed Endpoints for the RPT. The other two settings enable monitoring of the RPT and automatic updating.
Enter the following lines of PowerShell, below the earlier ones to configure the settings:
$AdditionalWSFedEndpoint = @(
Set-AdfsRelyingPartyTrust -TargetName "Microsoft Office 365 Identity Platform"
Setting the claims issuance authorization rule
One of the other features of the Microsoft Office 365 Identity Platform RPT, is the default claims issuance authorization rule.
Let’s add it to the RPT by entering the following lines of PowerShell, below the earlier ones:
Set-AdfsRelyingPartyTrust -Targetname "Microsoft Office 365 Identity Platform" -IssuanceAuthorizationRules ' => issue(Type = "http://schemas.microsoft.com/authorization/claims/permit", Value = "true");'
Setting the claims issuance transformation rules
Now, all that’s left is to configure the claims issuance transformation rules. As this is the core of the magic of the Relying Party Trust, changes most often of all the RPT characteristics and requires custom rules in multi-domain scenario’s, I’m opting to create these rules using the Claims Generator on adfshelp.microsoft.com.
Perform these steps on any Internet-connected system:
- Open a browser.
- Navigate to adfshelp.microsoft.com.
- On the main page, click Online Tools.
- On the Online Tools Overview page, click the Azure AD RPT Claim Rules tile.
- Follow the steps to generate the claims issuance transformation rules applicable to your organization.
- After you’ve completed all the steps, the claims issuance transformation rules are presented as a PowerShell script, and as raw text.
- Copy the contents of the PowerShell script into a file.
- Transfer the file to the AD FS server.
Run the PowerShell script on the AD FS server, next.
After it’s done, it will create a Backup of the previously created claims issuance transformation rules. This file will be empty, as no claims issuance rules would have previously been configured. Close Windows PowerShell and log off, when done.
It’s surprising how default the Microsoft Office 365 Identity Platform Relying Party Trust is, when you think about it…
Also, the documentation on the Add-AdfsRelyingPartyTrust PowerShell cmdlet is wrong at stating that the –Identifier parameter is required; when using either the –MetadataFile or –MetadataUrl parameter, it certainly isn’t.
My colleague Barbara Forbes helped me with the Windows PowerShell antics for this blog post. I asked her help, because she uttered the immortal words ‘Surely some-one has figured this out already…’