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.
SAML's support for identity assurance is embodied in a concept called "Authentication Context". The context of an authentication event is designed to capture both technical and procedural elements that factor into the "confidence" expressed by the identity provider in the event. In terms of assurance, this maps to the concepts of technical strength and identity proofing strength that make up an assurance profile.
Every authentication statement issued by an IdP contains an
<saml:AuthnContext> element that expresses the context of the authentication event. There are a variety of syntaxes supported, but the most common one is to define a "class" of authentication contexts that all share essential characteristics that are of interest to a relying party. These classes are mapped to URI constants that are expressed in an element called
<saml:AuthnContextClassRef>, of which a single value can be expressed by the IdP.
In addition, SAML V2.0 SPs have the capability to include simple or complex matching requirements in their authentication requests that influence the Authentication Context supplied by the IdP. The intent is to allow IdPs that support varying levels of assurance to honor requests based on the requirements of the SP and not a one-size-fits-all policy. In practice, this approach can be tricky to implement and may depend on customization of one's software deployment.
Thus, we expect assurance implementation to be gradual, and we will continue to evolve documentation to reflect what we learn. We also encourage deployers to talk to their software suppliers about the support (or lack thereof) of these features.
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).
IAQs are provided in metadata so that supporting software may be configured to make use of the information when processing assertions containing assurance qualifiers. Participants are not obligated to enforce policies or otherwise make use of these qualifiers, however.
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.
The following extension is the immediate child element of the IdP's
<md:EntityEescriptor> element in metadata:
<md:Extensions xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"> <mdattr:EntityAttributes xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute"> <saml:Attribute xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" Name="urn:oasis:names:tc:SAML:attribute:assurance-certification"> <saml:AttributeValue>http://id.incommon.org/assurance/silver-test</saml:AttributeValue> <saml:AttributeValue>http://id.incommon.org/assurance/bronze-test</saml:AttributeValue> </saml:Attribute> </mdattr:EntityAttributes> </md:Extensions>
<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.
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.
authnContextClassRefsetting 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.
<saml:Attribute>elements in IdP metadata. Other approaches?
This example shows how a Service Provider can request a silver-test assurance from an IdP. First, both the IdP and SP must use IdP metadata configured as shown in the "IAQs in metadata" section above. The IdP will also need to release silver-test as a valid <AuthenticationMethod> for the chosen <LoginHandler>, typically done in the IdP's handler.xml configuration.
<Attribute name="urn:oasis:names:tc:SAML:attribute:assurance-certification" id="assurance-certification"/>
<ApplicationDefaults id="default" policyId="default" entityID="https://example.org/shibboleth" REMOTE_USER="persistent-id targeted-id eppn" signing="false" encryption="false" homeURL="https://example.org/" metadataAttributePrefix="Meta-">
One way for the SP to request silver-test from the Idp is to use the authnContextClassRef Query String Parameter to create the session.
Location: https://sp.example.org/Shibboleth.sso/Login? target=https%3A%2F%2Fsp.example.org%2Fsecure%2Fresource.asp& entityID=https%3A%2F%2Fidp.example.org%2Fidp%2Fshibboleth& authnContextClassRef=http%3A%2F%2Fid.incommon.org%2Fassurance%2Fsilver-test
Upon successful authentication from the IdP, the secure SP session should have the following environment variables:
HTTP_SHIB_AUTHENTICATION_METHOD http://id.incommon.org/assurance/silver-test HTTP_META_ASSURANCE_CERTIFICATION http://id.incommon.org/assurance/silver-test;http://id.incommon.org/assurance/bronze-test
Contrast this with the same session initiation WITHOUT the authnContextClassRef=... parameter:
HTTP_SHIB_AUTHENTICATION_METHOD urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport HTTP_META_ASSURANCE_CERTIFICATION http://id.incommon.org/assurance/silver-test;http://id.incommon.org/assurance/bronze-test
Note that if you attempt to pass the authnContextClassRef=... parameter to an IdP which has not been configured, you will most likely receive an opensaml::FatalProfileException.
See Assurance - Identity Provider Behavior.