Technical implementation of identity assurance requires system changes from InCommon Operations, IdPs, and SPs. This page captures lessons learned, recommended practices, and outstanding issues regarding the technical aspects of identity assurance.
Participation in the InCommon Identity Assurance Program requires the use of SAML V2.0 Web Browser SSO. IdP and SP operators should plan to upgrade to SAML V2.0 as soon as possible.
InCommon Operations will add identity assurance qualifiers (IAQs) to published metadata following notification of certification by InCommon management. IAQs will be added to the appropriate IdP entity descriptor of the certified IdP operator (IdPO).
Proposed IAQ URIs are:
There will likely be a need for non-production IAQs for use in interoperability testing, probably with test instances of metadata:
Note that all of the above URIs will resolve to actual web pages at some point.
IAQs in metadata
The following extension is the immediate child element of the IdP's
<md:EntityEescriptor> element in metadata:
<mdattr:EntityAttributes> element and the name of the SAML Attribute (
urn:oasis:names:tc:SAML:attribute:assurance-certification) are defined by the OASIS specification entitled SAML V2.0 Metadata Extension for Entity Attributes and the OASIS SAML V2.0 Identity Assurance Profiles, respectively.
A complete, working metadata sample is attached to this wiki topic. To schema validate this sample metadata, you can use XmlSecTool:
xmlsectool.sh --validateSchema \
--schemaDirectory schema-files --inFile incommon-idp-metadata.xml
For convenience, we provide a set of (suitably modified) schema files that permit offline schema validation.
- The entity attribute and/or the IAQ has to be dated or versioned to indicate exactly what IAP is referred to.
Ideally SPs that require a particular assurance level will initiate the assurance flow by including the desired IAQ in the SAML AuthnRequest element.
SPs will receive IAQs (either in response to a specific request, or sent unsolicited) in assertions from IdPs. SPs should use metadata to check that the IdP is authorized to assert the IAQs being asserting.
SPs will rely on local policy to decide how to handle incoming IAQs. For example if the SP requires InCommon Bronze but receives InCommon Silver, that is probably acceptable.
- Some SPs may not be able to use the AuthnRequest mechanism due to software or other limitations. Are they simply out of luck?
- One option may be to use additional software to generate requests on behalf of the broken SP, although this isn't guaranteed to work with all SPs. Otherwise, such SPs will be forced to rely on OOB configuration of IdPs.
- How is the AuthnRequest configured using the Shib SP? The simpleSAMLphp SP?
- Shibboleth SPs can rely on the authnContextClassRef setting to control the value requested when particular resources are accessed. To include multiple values in a request, the AuthnRequest "template" mechanism described in the SessionInitiator documentation can be used.
- Boarding process: Since an IAQ in metadata makes a statement about certification (not live service), how does an SP determine that an IdP supports assurance operationally (ala attribute support)? One approach is to include
<saml:Attribute> elements in IdP metadata. Other approaches?
- There is no metadata support for this requirement. SPs should be able to handle errors returned by IdPs that indicate the requested assurance level was not supported. The federation should help establish guidelines for describing such errors, perhaps with a FAQ page that could be linked in.
- Does the Shib SP software support the metadata check? Does the simpleSAMLphp SP?
- The Shibboleth SP can extract and make available the entity attribute value in a variable along with user attributes, and use the variable in authorization policy. This is described under "metadata attribute extraction".
- What matching rules are recommended, or acceptable?
- How is an SP supposed to "know" that Silver is acceptable in lieu of Bronze? Is there a role for InCommon to provide "advice"?
Ideally IdPs will receive a desired IAQ from an SP in an AuthnRequest to initiate the process. The IdP compares the requested IAQ to its matching rule and interacts with the local IdM system to determine if the current user meets the requirements. If so, the appropriate IAQ is returned in the AuthnContext element in the assertion.
- What matching rules are supported?
- The Shibboleth IdP directly supports only "exact" matching of requested IAQs, and SAML requires that such matchiing be exact (it does not allow for "equivalence"). Supporting more flexible comparison operators requires implementing a custom login handler.
- If the SP requests Bronze, is it allowable for the IdP return Silver? How does the IdP "know" the mapping? Is there a role for InC to provide "advice"?
- Returning Silver is not permissible if the request asks for Bronze and uses "exact" matching. It would be permissible if "minimum" were specified, but a custom login handler would be needed.
- Is it possible and/or desirable for the IdP to return multiple IAQs?
- The AuthnContext element that various groups decided to use for expressing them does not directly support more than one IAQ at a time. In theory an "umbrella" IAQ could be defined to capture combinations, but this would be complex to express and not supported widely.
- How does the Shib IdP interact with local IdM? Is a custom login handler required? Same question for simpleSAMLphp.
- It is virtually certain that suporting assurance in any but the most trivial of ways will require a custom login handler. It will take time to develop patterns and common requirements that could be factored into reusable code.
- If an SP does not assert an IAQ in an AuthnRequest and the current user meets the requirements for one or more IAQs, should the IdP assert the IAQ(s).
- It seems likely that IdPs should express the IAQ appropriate for a user's session if they can.
- Can the Shib (or SSP) IdP be configured to send IAQs without being requested?
- A SAML IdP always sends some form of AuthnContext information. By convention, that is being used to carry an IAQ. In Shibboleth, the term in the IdP for this data element is the "authentication method".
- If so, what are the appropriate policy knobs (per-SP, per-user, whatever)?
- For a Shibboleth IdP, it depends on the login handler(s) used. Each SP can be assigned a defaultAuthenticationMethod in the relying-party.xml file, although this is burdensome. In turn, the default method is used to select a login handler to use, and to determine whether an existing session will work without additional login. This is described here.