A quick summary – we are working on a custom STS which the ADFS will federate with. In our previous blog entry we have federated our custom RP application with the ADFS. What we have so far is then a fully functional custom STS, the ADFS and a sample RP application to test the federation.
In this part of the tutorial we are going to modify the custom STS so that the ADFS could be federated with it. This means that the RP application which is federated with the ADFS will not need to be reconfigured at all but the ADFS will offer a new way to login with the custom STS serving as the Identity Provider STS (IP-STS).
Several things must happen correctly to create the federation relation between ADFS the custom STS.
SAML and WS-FederationPassive Endpoints
Although our custom STS has already been implemented to publish the metadata, the ADFS will not accept it as the IP-STS until the SAML and WS-FederationPassive endpoints are provided in the metadata. It is possible to configure all the endpoints manually in the ADFS configuration console but it’s easier to modify the metadata generation code with two simple descriptors (ipsso, spsso below):
with following consts
I have found 0 (zero!) examples of using these classes in the internet and have figured most things by inspecting the metadata of the ADFS itself and trying to implement similar structures in the custom STS metadata. Fortunately, ADFS can be federated with another ADFS rather easily which was the reason to dig deeper into the ADFS metadata to find any stuff specific to STS-to-STS federation.
Matching the EntityID and the IssuerName
The metadata declares the EntityID of the STS. On the other hand, the certificate used to sign the SAML token declares the name of the certificate issuer.
For some reason, these two must match otherwise the ADFS will not accept claims from your STS. I’ve blogged about one of the ways to handle this. Another solution would be to declare one string const in your code and access it from the two places in the code.
First, in the metadata:
And then in the custom STS configuration class:
Correcting the ReplyToAddress
When creating the relying requests to our custom STS, the ADFS will introduce itself using its identifier (scope.AppliesToAddress). The problem is that in the default configuration, the identifier points to the URL which is invalid and will not accept response messages from your STS.
(Note the http:// protocol while ADFS is available at https://!)
There are two ways to correct this. First, you can go to ADFS, open it’s configuration panel and change its identifier.
Second, in your custom STS you can create a mapping between IDs and valid URLs of requesting parties. The mapping could have a default clause which would just copy the identifier as the return address (as it does that by default in our implementation!). For example:
Creating the Custom STS trust relation in ADFS
After all these preparations, creating the trust relationship between ADFS the custom STS is easy.
First navigate to the custom STS metadata (https://customsts.yourdomain.com/FederationMetadata/2007-06/FederationMetadata.ashx) and save it to an XML file.
Then go to ADFS configuration and create a new trust relationship. Import the provider metadata from the XML file. Create two simple claim rules which just pass Name and Role through (the ADFS should not touch them as they are created in the custom STS).
Then go to your example RP application and try to login. Instead of the ADFS login page, you should see the HomeRealmDiscovery page as ADFS is now unsure whether you want to login with your AD identity or via the trusted claims provider (custom STS). The default HRD page contains a combobox with two selections however you can easily modify this page in ADFS (it’s stored as *.aspx file).
When things fail
Couple of tips when you fail at some point.
If you do not see the HRD page in ADFS but the trust relationship has been created, it probably means that the SAML/WSFederationPassive endpoints in the custom STS are created incorrectly. Go back to the 1st section of this tutorial.
If the custom STS redirects back to wrong address, it probably means that the mapping between ADFS ID and ADFS address is incorrect in the custom STS. Go back two sections.
If the redirect hits a correct ADFS page but ADFS shows a generic error it could mean that the custom STS ID does not match the issuer name of the certificate. Go back three sections.
We are close to the very last tutorial in which we will create a WSTrustFeb2005 service endpoint in our custom STS and modify the login logic of the ADFS.