Pro Tip! Use the claim rules from ADFSHelp for your ‘Office 365 Identity Platform’ Relying Party Trust

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:

The ADFSHelp Portal in Microsoft Edge (click for larger screenshot)

ADFSHelp ToolsIn 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?

ADFSHelp FeedbackHow 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!

6 Responses to Pro Tip! Use the claim rules from ADFSHelp for your ‘Office 365 Identity Platform’ Relying Party Trust

  1.  

    Great find. Thanks for sharing. Good for customers that still have the 3 default claim rules in the O365 Relying Party and not have ADFS managed by AD Connect.

    • Indeed!

      These days, it's also beneficial to organization that are experiencing double Multi-factor Authentication prompts (the "double MFA problem"), because the claims rules on ADFSHelp include two more lines, when compared to the claims rules, set by Azure AD Connect v1.1.654.0.

       
  2.  

    Hi,

    After configuring AD FS, we found that authentication to portal.office.com gets redirected to my AD FS server, but on the login page its showing "An error occurred". After diagnosis I found that no relying party trust was made in AD FS during configuration. But I found my DNS domain was federated. My AD FS server does not have internet access, can I manually configure "relay party trust" and other things? If yes, please provide me the steps. Please note I cannot give access to Internet.

    • Hi Suvom,

      While other cloud applications, services and systems allow for manual configuration of the Relying Party Trust (RPT), Microsoft does not support this option for Azure Active Directory and the accompanying 'Office 365 Identity Platform' RPT.

      The FederationMetadata.xml needs to be made available to the Internet. Microsoft's recommendation is to implement Web Application Proxies in a perimeter network. F5 appliances can act as Web Application Proxies. Alternatively, you can set up a webserver that only hosts the FederationMetadata.xml file for the required metadata exchange between your AD FS implementation and Azure AD, and script automatic copying of the file from your AD FS Server(s) to the publicly available webserver.

      Tips:

      • Do not disable the 'Monitor relying party' and 'Automatically update relying party' options for the 'Office 365 Identity Platform' RPT in AD FS.
      • If you want to disable AD FS authentications from the Internet, use Access Control Policies in AD FS.
      • In environments with existing F5 appliances, reuse the F5 appliances as fully-fledged Web Application Proxies. F5 is the first vendor to support Microsoft's open MS-ADFSPIP protocol.
      • Use Windows Server 2016 or Windows Server 2019 for AD FS. As Windows Server 2012 and Windows Server 2012 R2 have entered the extended support lifecycle period yesterday, please refrain from implementing new and/or additional AD FS Servers and/or Web Application Proxies using these Operating Systems.
       
    • Hi Suvom,

      When creating a Relying Party Trust (RPT) between AD FS and Azure AD, the AD FS needs to be accessible from the Internet.
      Microsoft's recommendation is to deploy the Web Application Proxy role in a perimeter network, to achieve this.

      Alternatively, you can use Password Hash Synchronization (PHS) or Pass-through Authentication (PTA) instead of AD FS as the authentication method.

       
  3.  

    Suvom, As per MS advice (and if possible) go for PTA or PHS with SSO. If Company requirements are to authenticate to on-prem pick PTA otherwise PHS with SSO is also possible but then authentication is at cloud (azure). Most SaaS apps support saml federation with azure ad so real need for adfs is not necessary anymore (but slightly depens on your requirements). Also check your cliënt apps if they support modern authentication cq PTA of you go that way, but most do.

leave your comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.