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.
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:
- Update the metadata for SAML V2.0
- Add one or more SAML V2.0 endpoints to metadata
- Add an encryption key to metadata
- Wait for the newly updated metadata to propagate throughout the Federation
- Partially configure the software for SAML V2.0
- Configure the software with the corresponding decryption key
- Configure the software to consume SAML V2.0 assertion responses
- Test the configured
<md:AssertionConsumerService>endpoint(s) - Configure the software to issue SAML V2.0 authentication requests
- Test the configured
<md:AssertionConsumerService>endpoint(s) again
Procedural details:
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.
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 may 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) weeks for the metadata to propagate, since any given Federation metadata file has an explicit 3-week lifetime.
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 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.
Do not configure your software to issue SAML V2.0 authentication requests at this time (but see step 5). A strategy that incrementally enables software functionality makes it easier to debug any problems that might arise.
To test your software's ability to consume SAML V2.0 assertion responses (at step 4), independently push an unsolicited response to each <md:AssertionConsumerService> endpoint enabled at the previous step. Unsolicited responses are initiated at the IdP. (to be described)
Configure your software to issue SAML V2.0 authentication requests at step 5. (to be described)
Finally, at step 6, test your software's ability to issue SAML V2.0 authentication requests by initiating SAML Web Browser SSO at the SP itself. (to be described)