Whenever I talk about the claim rules in Active Directory Federation Services (AD FS) for the ‘Office 365 Identity Platform’ Relying Party Trust (RPT), between the on-premises AD FS implementation and Azure AD, I get the following question:

How do we manually set up the advanced claim rules that Azure AD Connect configures automatically?

Let’s look at the ways to set up the Relying Party Trust and how to do it in a way that benefits you and your organization the most.

About Relying Party Trusts

Active Directory Federation Services (AD FS) utilizes Relying Party Trusts (RPTs) to define trust relationships between applications (and sometimes identity hubs, towards their applications) and itself, as a security token service for its identity provider (IdP), which most of the times is Active Directory Domain Services (AD DS).

Whenever a person accesses an application that has a Relying Party Trust (RPT) in AD FS, and expresses to use his/her account in your Active Directory, the device is redirected to AD FS for authentication. AD FS will talk Kerberos to AD DS and then translate the information into claims, using the claims rules. The claims are sent from AD FS to the device. Then, the device sends them to the application to authenticate to the application (or the identity hub), based on the trust relationship.

The claim rules indicate the contents of the claims tokens that are being exchanged. As such, they play a vital role in authorization.

Ways to create the Relying Party Trust

When you want to take advantage of a Relying Party Trust towards Azure AD and onwards to Office 365, any of the 2900+ Azure AD-integrated applications, or your own apps, there are three ways to set it up:

1. Configure the Relying Party Trust using PowerShell
2. Configure the Relying Party Trust using Azure AD Connect
3. Configure the Relying Party Trust manually

PowerShell

To setup the ‘Office 365 Identity Platform’ Relying Party Trust using Windows PowerShell, you can use the Convert-MSOLDomainToFederated Cmdlet from the MSOnline PowerShell Module.

If you haven’t installed the MSOnline PowerShell Module on your system, yet, run the following PowerShell one-liner, once:

Install-Module MSOnline -Force

Then, execute these lines, after you’ve changed the grayed-out DNS Domain Name with your information, on the (primary) AD FS Server in the AD FS Farm:

Import-Module MSOnline

Import-Module ADFS

Connect-MSOLService

Convert-MsolDomainToFederated -DomainName domain.tld -SupportMultipleDomain

Each of these three actions triggers the automatic creation of the ‘Office 365 Identity Platform’ Relying Party Trust with default rules:

• When you convert the first DNS Domain Name in Azure AD to federated in the context of the AD FS Farm specified using Convert-MSOLDomainNameToFederated.
• When you update the first DNS Domain Name in Azure AD to be federated to the AD FS Farm specified, after being federated to another AD FS Farm previously using Update-MSOLFederatedDomain.
• When you create a new DNS Domain Name in Azure AD to be federated to the AD FS Farm specified using New-MSOLFederatedDomain.

The rules created by the MSOnline PowerShell module are basic.

Azure AD Connect

Microsoft’s Azure AD Connect tool also offers to manage Active Directory Federation Services (AD FS). You can:

• Setup and configure AD FS Servers and Web Application Proxies from Azure AD Connect, specifying hosts and settings for the AD FS Farm.
• Change or set the sign-in options to Federation and point to a previously configured AD FS Farm to start managing its Azure AD and Office 365 settings using Azure AD Connect.

Using Azure AD Connect results in more extensive claims rules for the ‘Office 365 Identity Platform’ Relying Party Trust, including claim rules to specify the mS-DS-ConsistencyGUID user attribute as source anchor with the ObjectGUID attribute as fall-back.

The claim rules created are subject to the version of Azure AD Connect used to configure the RPT. Currently, version 1.1.654.0 is the most recent version available for download, which is 3 months old. Hence, the claims rules logic is 3 months old.

Manually

Creating Relying Party Trusts (RPTs) manually is not something I can recommend. However, updating RPTs manually, is something I do nearly every day. This is also the situation where the question in the first paragraph stems from. However, there are a couple more questions to ask:

How do I gain access to the latest claim rules for the ‘Office 365 Identity Platform’ RPT?

Previously, we used a development instance of Azure AD Connect with a development Azure AD tenant to investigate the rules. However, Microsoft has created new functionality in the adfshelp.microsoft.com ADFSHelp Portal:

In the Tools section, there is now a Claims Generator wizard labeled Azure AD RPT Claim Rules, that will help you get optimized claims rules for the ‘Office 365 Identity Platform’ RPT.

The wizard asks you for the source anchor (Immutable ID) you’d want to use, where your choices include ‘ObjectGUID’, ‘ms-Ds-consistencyGuid with fallback to ObjectGUID’ and ‘Other’. Then, you can specify the attribute that users will use to sign into Azure AD. ‘userPrincipalName’ is default, but you can specify ‘Alternate ID’. To offer multiple domain support, question 3 asks you if you have multiple domains. If you do, you can specify multiple DNS Domain Names in Azure AD, or upload a *.csv file with the information needed. The last button is aptly labeled ‘Generate claims’.

How do I implement these claim rules without the risk of mistyping the rules?

After you use the wizard, you have two options. You can copy a Windows PowerShell script that will target the ‘Office 365 Identity Platform’ RPT and will update the claims rules for it.

Alternatively, the rules themselves are also displayed. You can compare them to the output of  the Get-ADFSRelyingPartyTrust PowerShell Cmdlet to see if you actually have to update the claims rules. You might already run the latest rules, right?

How do I provide feedback on the functionality of the claim rules?

The adfshelp.microsoft.com ADFSHelp Portal offers a Feedback option. You can leave behind any feedback you have, whether it is a problem, suggestion or something general.

Concluding

Microsoft now offers the adfshelp.microsoft.com ADFSHelp Portal with useful functionality.

Throughout the past years, we’ve been discussing Active Directory Federation Services (AD FS), Azure Active Directory and Office 365. I’ve provided tips and you’ve provided feedback and additional questions. I’m very pleased with the interaction we’ve got going. Let’s keep that up!