This page shows how to migrate a production set up an SP deployment to support for SAML V2.0 Web Browser SSO. The procedures apply to new SPs as well as existing SPs migrating from SAML V1.1 to SAML V2.0. We assume the SP deployment is currently consuming SAML V1.1 assertions and that your SP software 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!
...
Configuring the SP
This section shows how to update metadata and configure the SP software for SAML V2.0 Web Browser SSO.
Preconditions:
- The organization responsible for the SP deployment is currently in productionis an InCommon Federation participant
- The SP deployment is currently consuming SAML V1.1 assertionsThe SP software supports both SAML V1.1 and SAML V2.0 Web Browser SSO
- A deployment choice with respect to IdP discovery (e.g., the SAML V2.0 Identity Provider Discovery Protocol) has been made
Procedure:
- Update the InCommon metadata for SAML V2.0
- Add one or more SAML V2.0 endpoints to metadata
- Add an encryption key to metadata (if necessary)
- Wait for the newly updated metadata to propagate throughout the Federation
- Configure the software for SAML V2.0 Web Browser SSO
- Configure the software with the corresponding decryption key (if necessary)
- Configure the software for IdP discovery
- Configure the software to issue SAML V2.0 authentication requests
- Configure the software to consume SAML V2.0 assertion responses
Procedural details:
Metadata InCommon metadata is updated at step 1 in advance of migrating to configuring the software for 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 zero or more <idpdisc:DiscoveryResponse> endpoint endpoints. See the comprehensive wiki topic on SP Endpoints for requirements and recommendations.
...
At step 2, you must wait for the new metadata to propagate before continuing with the remaining steps. We recommend you wait at least three (3) days for the metadata to propagate, but you may have to wait longer if your partners do not routinely refresh metadata.
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.
If the SP deployment will use the SAML V2.0 Identity Provider Discovery Protocol, the software is configured to issue such protocol requests in the presence of an unauthenticated user. Otherwise this configuration step may be omitted in favor of some other approach to IdP discovery.
Finally the software is 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
...
Once the SP has been upgraded to SAML V2.0, the a natural tendency is test the complete, end-to-end SAML flow. If this works, greatyou may be done, but if it doesn't, or you require more targeted testing thorough testing, a targeted test sequence may be required to isolate the problememployed:
- Test the SP's ability to consume a SAML V2.0 assertion response (bypassing the SAML V2.0 authentication request)
- Test the SP's ability to issue a SAML V2.0 authentication request (bypassing IdP discovery)
- Test the SP's ability to issue a SAML V2.0 Identity Provider Discovery Protocol request (bypassing nothing)
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 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
entityIDof 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:
| Code Block |
|---|
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:
| Code Block |
|---|
...&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.
Such tests limit the scope of the problem and therefore make bugs easier to findNext test your software's ability to issue SAML V2.0 authentication requests by initiating SAML V2.0 Web Browser SSO at the SP itself.