An HTTP module for use with ADFS which adds Relying-Party-specific data to ADFS' SAML authentication requests
When ADFS is being used as a passive RP- or FP-STS, it lacks a way of configuring some information about a Relying Party (RP) which should be passed upstrea to a SAML Identity Provider (IdP). For example, there is no way to configure the types of credentials that are required by an RP. There is also no way to specify which claims are required. This can be problematic if the RP deliver this information to ADFS for it to forward to the IdP. This limitation can make it impossible for an upstream SAML Identity Provider (IdP) to authenticate the user at a sufficient level. This can be handled at the RP or in ADFS with an authorization rule, but this results in a poor user experience. This lack of functionality may also manifest itself in other scenarios. To overcome this shortcoming, this HTTP module provides a way of configuring RP-specific settings that can be passed along from a downstream RP (whether using SAML or WS-Federation) with an upstream SAML IdP.
In the case where credentials requirements of a particular RP should be conveyed, this module updates the SAML authentication requests with an AuthnContextClassRef elements, allowing the IdP to receive these requirements in a standards-based manner. For times when required claims should be delivered northward, a common extension to SAML is used to add information about the desired claims. This extension makes use of the SAML metadata specification to convey the required attributes in the authentication request. It is easy to extend the module further with other RP-specific settings must also be sent upstream.
RP-specific configuration is stored in the notes field of the RP trust. This allows ADFS administrators to update the information in the same place and in the same manner as other RP trust information. If another data source is preferred, only the settings provider implementation needs to be changed.
This module adds RP-specific settings to the outgoing authentication request by subscribing to the EndRequest event defined by the IHttpModule. This causes it to fire with each request made to ADFS. It should be the last module to run in the ASP.NET processing pipeline, allowing it to alter the response created by ADFS. If ADFS' response has a 302 status code and if the module can parse the RP ID out of the request, it will determine the RP's settings and alter the response accordingly.
To this end, the module uses a provider that queries some sort of data source. This provider may look in ADFS' web.config file, ADFS' database, or some other repository. Which provider is used can be configured using the RelyingPartySettingsProvider app setting in ADFS's web.config file. Alternatively, you can subclass the module and override the RelyingPartySettingsProvider property. The included RelyingPartySettingsProvider class uses the ADFS PowerShell GetRelyingPartyTrustCommand cmdlet to get the value of the Notes from the ADFS configuration for RP trusts. It splits this field on back slash character (\). The first is the required credentails and the second part is the required claims. Each is split on a comma (,) to obtain the required data. This implementation allows ADFS admins to keep the credential information together with the rest of the settings associated with the RP.
When the HTTP module sees that ADFS is redirecting the end user, it is checks that it is using the SAML protocol's redirect binding to forward the authentication request to an upstream IdP. The module parses the associated request to determine the RP ID by:
- Checking for a
wtrealmin the query string. This is the case when the downstream RP is using WS-Federation to integrate with ADFS. - Checking for a
SAMLRequestin the query string. This is the case when the downstream SP is using the SAML redirect binding to communicate with ADFS. - Check for a
SAMLRequestslot of the request object'sParamsdictionary. If this is not null, it is because ADFS has placed into it a SAML authentication request send from a downstream SP using the POST binding.
If the RP ID can be found, the settings provider is quired for the required claims and credentials that subjects should use when authenticating to the upstream IdP. If the provider returns required credentials or claims, the redirect location set by ADFS is interrogated. This contains the SAML authentication request that ADFS has created. This has a lot of important information, such as the assertion ID, that must not be altered. This SAML authentication request is not signed, however, so we can change some parts of it. The credentials provided by the plug-in are then inserted into this request as AuthnContextClassRefelements. Any required claims are added to a RequestedAttributes element that is a child of the Extensions element defined by the SAML specification. Each required claims is added to this list as a RequestedAttribute element. After these requirements are used to update ADFS' SAML authentication request, the altered message is re-encoded and put into the RedirectLocation of the response. Consequently, ADFS will send it on to the upstream IdP. When ADFS receives the response, it will handle it as if the alteration never took place.
If you have questions, issues or need more info, open an ticket or send a pull request.