Using Federation Metadata to establish a Relying Party Trust in AD FS 2.0

Trust relationships are of course the sine qua non of AD FS 2.0. Relying Party Trusts or Claims Provider Trusts are necessary before AD FS 2.0 can provide benefit to any organization. That said, the establishment and maintenance of these relationships can be a time consuming task. Fortunately there are methods available that make this job significantly easier. AD FS provides three methods for creating Relying Party Trusts and Claims Provider Trusts. Manual entry of the necessary information is the most familiar method, but also the most time consuming and difficult to maintain. Additionally a trust can be created by importing "federation metadata", that is, data that describes a Relying Party or Claims Provider and allows for easy creation of the corresponding trust. A federation metadata document is an XML document that conforms to the WS-Federation 1.2 schema. Federation metadata may be imported from a file, or the partner may make the data available via https. The latter method provides the most straightforward method for creating a partnership and greatly simplifies any ongoing maintenance that may be required.

Manually creating a Relying Party Trust requires that the Administrator supply a fair amount of information that must be obtained from the partner organization through some out of band communication. This information includes the URLs for the WS-Federation Passive protocol and\or the SAML 2.0 Web SSO protocol, one or more relying party identifiers and, typically, the X.509 Certificate used to encrypt any claims sent to the relying party. Figure 1 below shows the various pages of the Add Relying Party Trust Wizard that must be navigated in order to create a relying party trust.

Figure 1 - Manually adding a relying party trust.

Once the relying party trust is established, it must also be maintained. It is possible that one or more of the URL's that identify the relying party may change, or the set of claims that the relying party will accept might change, but more likely, the X.509 Certificate used for encryption will have to be replaced, either because it has expired or because it has become compromised. Managing the updating of encryption certificates across an organization that might contain hundreds, or thousands, of relying parties presents a daunting challenge.

Lets explore how we create a Relying Party Trust using federation metadata.

Figure 2 - Options for entering data for a Relying Party Trust

As you can see from figure 2, it is possible to provide the metadata in the form of a file, as well as by specifying an https address. For purposes of this article I will confine our discussion to the case where the metadata is provided via https.

Each AD FS 2.0federation servers configured by default to publish metadata describing itself via https. If you click on the Service\Endpoints folder in the AD FS 2.0 snap-in you can see the highlighted endpoint in question as shown below:

Figure 3 -Showing the federation metadata endpoint provided by AD FS 2.0

To see what the actual XML looks like you can enter the endpoint into your web browser, as shown below:

Figure 4 - Example of a Federation Metadata document describing the information that is published about a specific Federation Service

I'm not going to review the structure of the federation metadata document here, except to note that it is a signed document and should not be edited or reformatted by hand. Anyone who is interested in the details of the schema, can find the specification at . https://docs.oasis-open.org/wsfed/federation/v1.2/ws-federation.pdf Instead I want to walk through an example of how to establish a Relying Party Trust using federation metadata.

The first step, of course is to launch the Add Relying Party Trust Wizard and navigate to the select data source page:

Figure 5 - Providing a federation metadata endpoint to the Add Relying Party Trust wizard

If you are interested in creating a trust using federation metadata but don't have a partner handy that provides metadata, it is perfectly feasible to have AD FS create a trust with itself. Of course, this is obviously of little use in the real world, but it's perfectly suitable for purposes of illustration. The first step is to provide the https address of the metadata document. If you know the full URL you can provide it, or you can simply enter the host name, and AD FS will attempt to find the data at the most common location. In this case enter the name of your host machine (not fs.contoso.com) and hit the next button. AD FS will read the available metadata and use it to construct the Relying Party Trust.

Figure 6 - Prompting for the relying party display name after reading federation metadata

As we can see the wizard path is considerably shorter than in the manual entry case. SAML metadata does not typically provide a display name for the relying party trust, so we are prompted to provide one, along with any comments we want to make about the relying party. Then we hit the Next button, which takes us to the Choose Issuance Authorization Rules page.

Figure 7 - The Choose Issuance Authorization Rules page

In this case, we're going to deny all users access to the relying party for now. Later we can add some issuance authorization rules to enable access to the relying party. We hit the Next button to go on to the review page.

Figure 8 - Reviewing the relying party trust that was created from metadata.

Here we can review the Relying Party Trust that we are about to create. If we examine the various tabs on the page, we can see that the Identifier URLs, encryption and signature certificates, list of accepted claims, endpoints etc., have all been provided via the metadata.

Figure 9 - The encryption certificate provided by the federation metadata

Figure 10 - The list of accepted claims provided by federation metadata

After reviewing the configuration of the relying party trust, we hit the Next button to add it to the database. In figure 11, below we see the successfully created relying party trust.

Figure 11 - Showing the newly created relying party trust

Now I mentioned previously that federation metadata not only facilitates the creation of trusts, but also their maintenance. To show this in more detail, let’s open the properties dialog for the Contoso relying party.

Figure 12 - The properties page for the Contoso relying party trust

In figure 12 above we see the properties dialog, with the Monitoring tab displayed. This tab governs how AD FS manages the updating of this relying party trust. You can see that the Monitor relying party check box is checked. This indicates that AD FS will periodically check the Federation Metadata URL shown in the dialog and compare it with the current state of the relying party trust. You will also notice that the Automatically update relying party checkbox is checked. This tells AD FS to automatically update the relying party trust in responses to changes in the metadata. With this option enabled, we do not have to worry about certificates expiring or being replaced - any changes made to the partner will be reflected in the metadata and automatically moved into the database. The Monitoring tab also displays the date on which the metadata was last checked as well as the date upon which the last update was performed. Events are also logged when an update is performed.

Note that if the Automatically update relying party check box was unchecked, then the monitoring would still continue, but AD FS would not be updated. Instead those relying parties that are no longer in sync with their metadata would be indicated in the UI, as well as in the event log.

Figure 13 - Notification that a relying party trust needs to be updated.

If you refer to figure 13, you will notice that one of the actions available for the Contoso relying party is Update from Federation Metadata... This command allows the Administrator to force an update from metadata at will.

Federation Metadata is a powerful tool for managing AD FS 2.0. In future posts we will explore other aspects and techniques for using this data.

For more information about how to create trusts via federation metadata, see the following topics in the AD FS 2.0 Deployment Guide:

• Create a Claims Provider Trust Using Federation Metadata
• Create a Relying Party Trust Using Federation Metadata