The Incommon Federation wiki has moved.

Please visit the new InCommon Federation Library wiki for updated content. Remember to update your bookmarks.

Click in the link above if you are not automatically redirected in 15 seconds.



You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 10 Next »

This page shows how to migrate a production SP deployment to support SAML V2.0 Web Browser SSO. We assume the SP deployment is currently consuming SAML V1.1 assertions and has the ability to issue SAML V2.0 requests and consume SAML V2.0 assertions.

Generally speaking, before making any changes to the software configuration, an SP's metadata is updated for SAML V2.0 and allowed to propagate throughout the Federation. Since Web Browser SSO almost always begins at the SP, exposing endpoints in SP metadata that are not supported in software is usually harmless. On the other hand, issuing SAML V2.0 requests without appropriate SAML V2.0 endpoints in metadata is a recipe for disaster!

Upgrading the SP

Preconditions:

  • The SP deployment is currently in production
  • The SP deployment is currently consuming SAML V1.1 assertions
  • The SP software supports both SAML V1.1 and SAML V2.0 Web Browser SSO

Procedure:

  1. Update the metadata for SAML V2.0
    • Add one or more SAML V2.0 endpoints to metadata
    • Add an encryption key to metadata (if necessary)
  2. Wait for the newly updated metadata to propagate throughout the Federation
  3. Configure the software for SAML V2.0 Web Browser SSO
    • Configure the software with the corresponding decryption key (if necessary)
    • Configure the software to issue SAML V2.0 authentication requests
    • Configure the software to consume SAML V2.0 assertion responses

Procedural details:

Metadata is updated at step 1 in advance of migrating to SAML V2.0. First add one or more SAML V2.0 endpoints to metadata, including at least one <md:AssertionConsumerService> endpoint and at least one <idpdisc:DiscoveryResponse> endpoint. See the comprehensive wiki topic on SP Endpoints for requirements and recommendations.

Since a SAML V2.0 IdP typically encrypts assertions transmitted through the browser, the SP is obliged to add an encryption key to metadata as well. In the InCommon Federation, this will already be done since a key in SP metadata is designated as a multiple use key by default. (See the wiki topic on Key Usage for details.)

At step 2, you must wait for the new metadata to propagate before continuing with the remaining steps. We recommend you wait three (3) days for the metadata to propagate, but you may have to wait longer.

At step 3, begin by configuring the software with the private decryption key corresponding to the public encryption key in metadata. If an encryption key was already in metadata when you started this procedure, perhaps the decryption key is likewise already configured in software. Double-check your configuration to be sure.

The software is also configured to issue SAML V2.0 authentication requests and consume SAML V2.0 assertion responses at step 3. One or more endpoint configurations are required, depending on the <md:AssertionConsumerService> endpoint(s) added to metadata at step 1.

Testing the SP

A typical SAML flow involves multiple exchanges, most of them terminating at the SP. Since it is up to the SP to initiate the next exchange in the flow, this is where most errors originate. Ironically, many of these errors manifest themselves at the IdP, as a result of faulty SP metadata. Thus it is critical that SP metadata accurately reflect the capabilities of the SP.

Once the SP has been upgraded to SAML V2.0, the natural tendency is test the complete, end-to-end SAML flow. If this works, great, but if it doesn't, more targeted testing may be required to isolate the problem:

  1. Test the SP's ability to consume a SAML V2.0 assertion response (bypassing the SAML V2.0 authentication request)
  2. Test the SP's ability to issue a SAML V2.0 authentication request (bypassing IdP discovery)
  3. Test the SP's ability to issue a SAML V2.0 Identity Provider Discovery Protocol request (bypassing nothing)

Phase 1 Testing

To test your software's ability to consume SAML V2.0 assertion responses, methodically push an unsolicited response to each configured <md:AssertionConsumerService> endpoint. Since an unsolicited response is initiated at the IdP, an explicit authentication request is bypassed, which focuses testing on the SP. To perform this test, you need the following information:

  • The unsolicited SSO endpoint location at the IdP (which is not advertised in IdP metadata)
  • The entityID of the SP
  • The <md:AssertionConsumerService> endpoint location(s) at the SP

First initiate an unsolicited response for the default <md:AssertionConsumerService> endpoint location at the SP:

https://idp.protectnetwork.org/protectnetwork-idp/profile/SAML2/Unsolicited/SSO?providerId=https%3A%2F%2Fservice1.internet2.edu%2Fshibboleth

In the previous request, we use the unsolicited SSO endpoint location at the ProtectNetwork IdP and the entityID of the InCommon Operations SP (suitably encoded). Your mileage may vary of course.

Subsequently test a specific <md:AssertionConsumerService> endpoint location at the SP by appending a shire parameter to the above query string:

...&shire=https%3A%2F%2Fservice1.internet2.edu%2FShibboleth.sso%2FSAML2%2FPOST

Continue to test every <md:AssertionConsumerService> endpoint location in this way.

Note that the HTTP parameters used to trigger an unsolicited response (providerId and shire) are the same parameters used in a Shibboleth 1.x AuthnRequest, but since the endpoint at the IdP is a SAML V2.0 endpoint, a SAML V2.0 flow is initiated.

Phase 2 Testing

Next test your software's ability to issue SAML V2.0 authentication requests by initiating a SAML V2.0 discovery response at the SP itself. Similar to the way we initiated an unsolicited response at the IdP, we can initiate a discovery response at the SP. Two additional pieces of information are needed:

  • The <idpdisc:DiscoveryResponse> endpoint location(s) at the SP
  • The entityID of the IdP

Initiate a discovery response for an <idpdisc:DiscoveryResponse> endpoint location at the SP as follows:

https://service1.internet2.edu/Shibboleth.sso/DS?entityID=urn%3Amace%3Aincommon%3Aidp.protectnetwork.org

In the previous request, we use the (one and only) discovery response endpoint location at the InCommon Operations SP and the entityID of the ProtectNetwork IdP. Again, your mileage may vary.

Repeat the test for each configured discovery response endpoint. Each such endpoint is configured for a different type of authentication request, so be sure to exercise each of them in turn.

Phase 3 Testing

TBD

#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))
  • No labels