...
Info | ||
---|---|---|
| ||
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 V2.0 Support for Assurance
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.
...
Thus, we expect assurance deployment 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. Anchor
IAQs in Metadata
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:
Silver: http://id.incommon.org/assurance/silver
Bronze: http://id.incommon.org/assurance/bronze
There will likely be a need for IAQs to be used during interoperability testing:
Silver: http://id.incommon.org/assurance/silver-test
Bronze: http://id.incommon.org/assurance/bronze-test
Note that all of the above URIs will most likely resolve to actual web pages at some point.
Technical Details
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>
InCommon Practices
See: InCommon Practices - Certification and Metadata
SP Behavior
See: Assurance - Service Provider Behavior.
IdP Behavior
See:
The <mdattr:EntityAttributes>
element and the name of the SAML Attribute (urn:oasis:names:tc:SAML:attribute:assurance-certification
) are defined by the OASIS specification 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.
SP behavior
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.
SP Policy Use Cases
Issues
- 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.
- Shibboleth SPs can rely on the
- 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"?
- How should an SP perform LoA escalation to allow for a need for increased LoA in an application when a user transitions from a context that needs little or no assurance, to a context that requires a higher LoA?
...
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.
- Edit the SP's /etc/shibboleth/attribute-map.xml configuration file. Add the following new tag:
This corresponds to the <saml:Attribute Name="urn:oasis:names:tc:SAML:attribute:assurance-certification"> tag in the IdP's "IAQs in metadata" configuration section above.Code Block <Attribute name="urn:oasis:names:tc:SAML:attribute:assurance-certification" id="assurance-certification"/>
- Edit the SP's /etc/shibboleth/shibboleth2.xml configuration file. In the <ApplicationDefaults ...> tag, add the following attribute:
You will now have an <ApplicationDefaults ...> tag that looks like the following:Code Block metadataAttributePrefix="Meta-"
This will add new Apache server environment variables of the form HTTP_META_... and allow the SP software to automatically populate the Apache server environment with the IdP's metadata <EntityAttributes>. This is useful for the SP to programatically determine which assurance attributes are valid from the IdP.Code Block <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-">
- Restart the SP's shibd process.
One way for the SP to request silver-test from the Idp is to use the authnContextClassRef Query String Parameter to create the session.
Code Block |
---|
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:
Code Block |
---|
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:
Code Block |
---|
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.
IdP behavior
See Assurance - Identity Provider Behavior.
References
- SAML V2.0 Core
- SAML V2.0 Metadata Extension for Entity Attributes
- SAML V2.0 Identity Assurance Profiles
...