Part 1 of 3 – Debugging WS-Federation Issues
Fiddler is simply the best tool to debug federation issues. Optimal IdM has just released a White Paper on this which you can download on the left side of this page. This is part one of a three-part blog series on this topic. In this blog we will cover how to use Fiddler to debug WS-Federation issues.
The URI for a relying party or identity provider may be in the form of a URL (such as http://my.test.com) or a URN (urn:my.test.com). URIs (both URNs and URLs) are case sensitive when used for Federation. For URLs in the form of URIs, every “/” is part of the name as is the protocol. When used as a URI the URLs http://my.test.com, http://my.test.com/, https://my.test.com, and https://my.test.com/ would all be considered different URIs. This often causes federation errors.
After capturing the Fiddler trace look for HTTP Response codes with value 404. The response code is the second column from the left by default and a response code will typically be highlighted in red. If you see a 404 error, it is likely one of two reasons; 1) the URL is wrong and does not point to a valid location, or 2) the URL length exceeds that which the server can support.
If you see a 404 error in the browser that does not show up in the Fiddler trace then that indicates the URL length exceeds the URL length limit of your browser. Browser URL length limits are vendor dependent.
The Basic Flow of WS-Federation
The basic flow of WS-Federation is:
- The user requests an access to a relying party
- The user is redirected to the Identity Provider (IdP) with a WS-Federation authentication request
- The user then authenticates at the IdP
- A WS-Federation authentication response is then posted to the relying party
If in the authentication request you get an error on the Identity Provider indicating that the relying party URI is not recognized, run a Fiddler trace reproducing the issue. Then look for a GET request to the IdP with the following URL parameters shown below. You can see the URL parameters by selecting the line in the request list and then going to the Inspectors -> Web Forms tab.
URL Parameters for WS-Fed Authentication
The URL parameters for the WS-Fed authentication request are:
- wa = wsignin1.0
- wtrealm = <relying party URI>
- wctx = <federation context>
- wct = <request time in UTC>
Make sure the value in the wtrealm URL parameter matches the value configured at the identity provider for the relying party. Also look at the raw URL which can be seen on the Inspectors -> Raw tab. Make sure the wtrealm URL parameter is properly URL encoded in the raw authentication request URL.
The WS-Federation response is an HTTP POST request with the follow form data. You can see the form data by selecting the line in the request list and then going to the Inspectors -> Web Forms tab.
The form data for the WS-Fed authentication response are:
- wa = wsignin1.0
- wresult = <WS-Fed response XML>
- wctx = <federation context> (should match the authentication request)
From the WS-Fed response XML validate the following:
- Make sure the IdP URI matches the value configured on the relying party. This value can be found in the WS-Fed response XML Issuer element.
- Make sure the signing certificate matches the signing certificate configured on the relying party. The signing certificate can found in the WS-Fed response XML in the Certificate element under the Signature element.
- Make sure the assertion audience matches the relying party URI. The assertion audience can be found in the Audience element of the assertion.
- WS-Federation supports either SAML 1.1 or SAML2 assertions, make sure the type of the assertion matches what the relying party is expecting. For SAML 1.1 assertions the major and minor version attributes on the Assertion element will be set to 1. For SAML2 assertions the version attribute on the Assertion element will be set to 2.