(2012-08-31) Leveraging Federation Metadata To Setup A Federation Trust (Claims Provider Or Relying Party)

To be able to accept security tokens packaged with claims as a service provider (SP) STS from another identity provider (IdP) STS or to send security tokens packaged with claims as an IdP STS to an SP STS a federation trust MUST be in place. However, what does it really mean having a federation trust in place? Do you really understand the concept behind federation?

Figure 1: A Possible Federation Architecture With All Kinds Of Components That Can Be Used

-

A federation trust is always unidirectional and has two endpoints. A federation trust can also be seen as the embodiment of a business level agreement or partnership between two entities (endpoints). One of the endpoints (figure 1, left side), called the Claims Provider (CP), the Identity Provider (IdP) or Account Partner (AP) is responsible for the identities and the related identity information in terms of identification, creation, storage, management and authentication. This endpoint defines a so called replying party trust representing the other endpoint. In turn the other endpoint (figure 1, right side), called the Relying Party (RP) or the Service Provider (SP) is responsible for the hosted applications and services including the available authorizations within the applications or services. This endpoint defines a so called claims provider trust representing the previous endpoint. Then on every trust endpoint you define the business rules how claims are filtered, passed through and/or transformed. On the CP trust the business rules are the “Acceptance Transform Rules” and on the RP trust the business rules are the “Issuance Authorization Rules” and the “Issuance Transform Rules”.

-

So, based upon what I say above, you may ask yourself: “who determines who gets access to what?” Is it the IdP or the SP? Looking at who manages the identities that would therefore be the IdP that also decides who gets access to what. That means that an SP must accept handing over the control of who gets access to what within its applications and/or services. This becomes even more important when the application is owned by the SP, but the data is also owned by the SP! (e.g. two organizations working together where one organization, the SP, hosts an application and owns both the application and the data, and the other organization, the IdP uses the same data). This is less important when the SP owns the application, but not the data. The data in that case is then owned by the IdP. (e.g. Office 365).

So, with federation you must understand the chain of trust you are accepting, especially if you are the SP and you are the application owner, but also the data owner within that application! With that, when the SP has a federation trust with an IdP, the chain of trust is:

• Organization with organizational role “Service Provider (SP)” explicitly trusts:
  • The STS of the IdP (because of the federation trust that’s in place)
    (and because of that…)
  • All the security tokens issued and signed by that IdP STS
    (and because of that…)
  • All the packaged claims in the security token
    (and because of that…)
  • All the attribute values derived from ID data repositories at the IdP
    (and because of that…)
  • All IdM processes (manual or automatic) with regards to identification, authentication, provisioning in all required ID stores, deprovisioning from all required ID stores, keeping data up-to-date in all required ID stores and password management following business policies @ IdP (NOT the business policies @ the SP!!!!!)

-

For some organizations in the organizational role “Service Provider (SP)”, that’s a HUGE step to take!

How do you still have control who can get to what application, while still allowing the IdP control who has what access within each application? (I know the answer, but that’s some other blogpost! )

-

So, to even be able to setup a federation trust, the following federation metadata is required (required information depends also on the trust endpoint type):

• Display Name;
• Supported Profile features;
• Token Signing Certificate (Public Key only); (on CP trust endpoint only!)
• Token Encryption Certificate (Public Key only); (on RP trust endpoint only!)
• Whether or not SAML Protocol and/or WS-Federation Protocol are supported, incl. the corresponding protocol URL;
• Federation Identifier(s);
• Initial Authorization Rule “Allow” or “Deny” (can be changed afterwards) (on RP trust endpoint only!)

-

Federation trusts do not just need to be created, but these need also to be maintained. Independent of the method used, the information needed during the creation of the federation trust that also needs to be maintained during the lifetime of the federation trust are the WS-Federation Passive protocol URL and/or the SAML 2.0 Web SSO protocol URL, one or more identifiers and, typically, the X.509 Certificates used to sign and encrypt security tokens.

-

Depending on the trust endpoint type, the information can be provided in three ways:

[1] Using The Federation Metadata Exchange URL (figure 2)

 

Figure 2: Using The Federation Metadata Exchange URL (LEFT: Adding Claims Provider Trust) (RIGHT: Adding Relying Trust)

-

When using method [1] (figure 2: Using The Federation Metadata Exchange URL), you can imagine it is the preferred way as all the information is monitored and maintained/updating automatically and therefore greatly simplifies on-going management! Before being able to use this both parties need to be able to support this. The publishing party needs to be able to support this and the consuming party also needs to be able to support this. If you are using ADFS v2.x on either side then you are good to go! I do not know about other federation platforms or claims based applications/systems. Anyone else know? Feel free to comment on that!

Figure 3: The ADFS Federation Service Endpoints

-

To know what the URL is, you open the ADFS MMC Console and navigate to the Endpoints node. The ADFS Service Endpoint for which the type is “Federation Metadata” (figure 3) is the one you need. In front of that relative URL path you need to add “https://<federation service FQDN>” so that the full URL becomes: “https://<federation service FQDN>/FederationMetadata/2007-06/FederationMetadata.xml”. You can determine the federation service FQDN through the federation service properties

-

[2] Using The Federation Metadata XML File (figure 4)

 

Figure 4: Using The Federation Metadata XML File (LEFT: Adding Claims Provider Trust) (RIGHT: Adding Relying Trust)

-

When using method [2] (figure 4: Using The Federation Metadata XML File), you need to get the metadata XML file from the admin managing the other endpoint. This prevents you from entering all the information manually, but does not provide for automatic monitoring/updates (e.g. expired and updated certificates), unless to enable it after the creation of the trust. But then, you could have used method [1] right away couldn’t you!?

The admin at the other endpoint has two was of creating the federation metadata XML file. The first method is by targeting the Federation Metadata Exchange URL within Internet Explorer (IE), selecting everything shown copying and pasting that into a (XML) file. If you use IE and you end up with a blank page not showing any error at all, then click on the “Compatibility View” button in IE and the info you are looking for will show up and shown in the picture below.

Figure 5: Federation Metadata Shown In Internet Explorer

-

A second method to get the federation metadata into an XML file, is to use the following PowerShell script, which will perform several steps to “export” the federation metadata from ADFS.

# CREATED BY: Jorge de Almeida Pinto [MVP-DS] (08-2012)
# --> http://jorgequestforknowledge.wordpress.com/
#
# SCRIPT NAME: RetrieveFederationMetadata.ps1
#
# Supports: ADFS v2.0 on W2K8 and W2K8R2
# Supports: ADFS v2.1 on W2K12

Clear-Host
Write-Host ""
Write-Host "***************************************************" -ForeGroundColor Yellow
Write-Host "*                                                 *" -ForeGroundColor Yellow
Write-Host "*       --> Retrieve Federation Metadata <--      *" -ForeGroundColor Yellow
Write-Host "*                                                 *" -ForeGroundColor Yellow
Write-Host "*   Written By: Jorge de Almeida Pinto [MVP-DS]   *" -ForeGroundColor Yellow
Write-Host "*                                                 *" -ForeGroundColor Yellow
Write-Host "***************************************************" -ForeGroundColor Yellow
Write-Host ""

# Determining Windows Version
$windowsVersion = (Get-WmiObject Win32_OperatingSystem).Version
$windowsBuildNumber = (Get-WmiObject Win32_OperatingSystem).BuildNumber

# Based Upon The Windows Version, Either Load The ADFS PoSH Snap-In Or The ADFS PoSH Module
If ($($windowsVersion.SubString(0, $windowsVersion.Length - $windowsBuildNumber.Length - 1)) -eq "6.1") {
    # ADFS v2.0 PowerShell CMDlets
    [array] $SnapInListToLoad = "Microsoft.Adfs.PowerShell"
    ForEach($SnapIn In $SnapInListToLoad) {
        If(@(Get-PSSnapin | Where-Object {$_.Name -eq $SnapIn} ).count -eq 0) {
            If(@(Get-PSSnapin -Registered | Where-Object {$_.Name -eq $SnapIn} ).count -ne 0) {
                Add-PSSnapin $SnapIn
                Write-Host "`nPoSH Snap-In '$SnapIn' Has Been Loaded...`n" -ForeGroundColor Green
            } Else {
                Write-Host "`nPoSH Snap-In '$SnapIn' Is Not Available To Load...`n" -ForeGroundColor Red
            }
        } Else {
            Write-Host "`nPoSH Snap-In '$SnapIn' Already Loaded...`n" -ForeGroundColor Green
        }
    }
} Else {
    # ADFS v2.x PowerShell CMDlets
    [array] $PoSHModulesToLoad = "ADFS"
    ForEach($PoSHModule In $PoSHModulesToLoad) {
        If(@(Get-Module | Where-Object {$_.Name -eq $PoSHModule}).count -eq 0) {
            # WHEN POSH MODULE IS NOT LOADED TRY TO LOAD IT
            If(@(Get-Module -ListAvailable | Where-Object {$_.Name -eq $PoSHModule} ).count -ne 0) {
                Import-Module $PoSHModule
                Write-Host "`nPoSH Module '$PoSHModule' Has Been Loaded...`n" -ForeGroundColor Green
            } Else {
                Write-Host "`nPoSH Module '$PoSHModule' Is Not Available To Load...`n" -ForeGroundColor Red
            }
        } Else {
            Write-Host "`nPoSH Module '$PoSHModule' Already Loaded...`n" -ForeGroundColor Green
        }
    }
}

# Get ADFS Federation Metadata URL
$ADFS_Federation_Metadata_URL = (Get-ADFSEndpoint | ?{$_.Protocol -eq "Federation Metadata"}).FullUrl.ToString()
Write-Host "Federation Metadata URL: "$ADFS_Federation_Metadata_URL -ForeGroundColor Yellow

# Download The Federation Metadata To A File
$ADFS_Config = Get-ADFSProperties | Select HostName
$ADFS_SVC_Name = $ADFS_Config.HostName
$ADFS_Federation_Metadata_XML = "C:\"+$ADFS_SVC_Name+"_FederationMetadata.xml"
$WebClient = New-Object System.Net.WebClient
$WebClient.DownloadFile($ADFS_Federation_Metadata_URL, $ADFS_Federation_Metadata_XML)
Write-Host "`nFederation Metadata XML: "$ADFS_Federation_Metadata_XML -ForeGroundColor Yellow

-

-

<UPDATE 2012-09-07>

In the previous script, just before the last line I had the following lines specified:

• $targetXMLdoc = [xml](Get-Content -Path $ADFS_Federation_Metadata_XML)
• $targetXMLdoc.Save($ADFS_Federation_Metadata_XML)

While the download of the federation metadata file is good enough to import in ADFS when creating either a claims provider trust or a relying party trust, we as humans cannot read IF you are not using an XML editor such as for example notepad. If you are using an XML editor such for example notepad++ you can read it fine. However, if you want to read it using a non-XML editor you would need to apply the 2 lines mentioned in the bullet list, BUT that XML file cannot be used because the signature of the file gets screwed. If you try to create a claims provider trust or a relying party trust using the XML generated with the lines in the bullet list, you will most likely see the following error “ID6013: The signature verification failed.”

Figure 6: Failing The Signature Verification Of The Federation Metadata File During The Creation Of A Federation Trust In ADFS

</UPDATE 2012-09-07>

-

[3] Providing All The Federation Metadata Manually (figure 6)

 

Figure 7: Providing All The Federation Metadata Manually (LEFT: Adding Claims Provider Trust) (RIGHT: Adding Relying Trust)

-

When using method [3] (figure 6: Providing All The Federation Metadata Manually), you still need to get all the metadata from the admin at the other endpoint somehow and then enter everything manually.

-

Figure 2, 4 and 6 show you how to add a federation trust using the ADFS MMC Console. It is also possible to do the same using the PowerShell CMDlets “Add-ADFSClaimsProviderTrust” (figure 8) and “Add-ADFSRelyingPartyTrust” (figure 9)

Figure 8: Adding a Claims Provider Trust Through The PowerShell CMDlet “Add-ADFSClaimsProviderTrust”

-

Figure 9: Adding a Relying Party Trust Through The PowerShell CMDlet “Add-ADFSRelyingPartyTrust”

-

For more detailed information a reference is made to the following link(s):

• Create a Claims Provider Trust Using Federation Metadata
• Create a Claims Provider Trust Manually
• Create a Relying Party Trust Using Federation Metadata
• Create a Relying Party Trust Manually
• Using Federation Metadata to establish a Relying Party Trust in AD FS 2.0

-

Cheers,

Jorge

———————————————————————————————

* This posting is provided "AS IS" with no warranties and confers no rights!

* Always evaluate/test yourself before using/implementing this!

* DISCLAIMER:
http://jorgequestforknowledge.wordpress.com/disclaimer/


———————————————————————————————

############### Jorge’s Quest For Knowledge #############

#########
http://JorgeQuestForKnowledge.wordpress.com/
########

———————————————————————————————