...
Deployment Considerations for the R&S Category
...
| Table of Contents | ||
|---|---|---|
|
...
It is important that the implementation and deployment of all InCommon services facilitate initial on-boarding processes to avoid operational and technical impediments to adoption, as described in Recommended Practices for InCommon Participants.
More specifically, R&S services generally have a broad user community, often including people who do not have a close relationship with the Service Provider, or whose IdPs IdP operators do not have a close relationship with the Service Provider. For this reason, R&S Service Providers are encouraged to consider the following guidelines:
- The service should R&S category is most useful to those services that do not require out-of-band negotiation with IdPs.
- The service should request a subset of R&S Category Attributes, and furthermore, the service should request only those attributes it absolutely needs. (See the section on R&S Category Attributes section above for details.)
- The SP should fully support SAML V2.0 Web Browser SSO (see the SP Endpoints wiki page).
- The SP should provide a complete set of User Interface Elements in metadata. In particular, a Privacy Statement and a Logo are highly recommended.
- In addition to the Technical technical and Administrative administrative Contacts in Metadata required of all SPs, a Security security contact should also be provided (once that option becomes available).
- The SP should strive to provide a good, overall Federation User Experience federated user experience. In particular, the SP should should intelligently handle errors involving the release of requested attributes.
| Tip |
|---|
Identity Providers
Preparing IdP Metadata
To reduce user confusion and frustration, R&S SPs will provide a detailed error page with specific instructions in the event the user is returned to the SP without sufficient attributes. In particular, the SP will direct the user to the administrative contact at the IdP. Thus administrative contact information in IdP metadata is essential information in our effort to reduce manual boarding processes at the SP.
The IdP can short-circuit such an error page simply by including an errorURL in metadata. This gives the IdP the ability to own this problem by documenting (on the error page) and supporting whatever error handling process it desires.
Configuring a Shibboleth IdP to Release Attributes to an R&S SP
An IdP releases attributes to any R&S SP (identified by an entity attribute), not specific SPs (identified by entityID). In effect, an attribute release policy is configured just once for all R&S SPs.
An IDP can choose between possible configurations, depending on its policy needs:
- Always release the same set of attributes to every R&S SP.
- Release only those attributes an SP requests via its metadata element.
Always Release the Same Set of Attributes
Configure a new <AttributeFilterPolicy> element for R&S SPs.This example releases all of the R&S attributes; a campus should customize as appropriate (eg changing the attributeID values).
...
<AttributeFilterPolicy id="releaseToRandS">
<PolicyRequirementRule xsi:type="saml:AttributeRequesterEntityAttributeExactMatch"
attributeName="http://id.incommon.org/attribute/entity/category"
attributeValue="research-and-scholarship"/>
<AttributeRule attributeID="eduPersonPrincipalName">
<PermitValueRule xsi:type="basic:ANY" />
</AttributeRule>
<AttributeRule attributeID="email">
<PermitValueRule xsi:type="basic:ANY" />
</AttributeRule>
<AttributeRule attributeID="displayName">
<PermitValueRule xsi:type="basic:ANY" />
</AttributeRule>
<AttributeRule attributeID="givenName">
<PermitValueRule xsi:type="basic:ANY" />
</AttributeRule>
<AttributeRule attributeID="surName">
<PermitValueRule xsi:type="basic:ANY" />
</AttributeRule>
<AttributeRule attributeID="eduPersonScopedAffiliation">
<PermitValueRule xsi:type="basic:ANY" />
</AttributeRule>
</AttributeFilterPolicy>
Release Only Those Attributes an SP Requests via Its Metadata Element
| Info | ||
|---|---|---|
| ||
The following configuration requires Shibboleth IdP v2.3.4 (released on October 27, 2011) or later, which fully supports using entity attributes in SP metadata as part of an attribute release filter policy. For IdPs prior to v2.3.4, InCommon provides a tool that can be run on a regular basis to convert InCommon metadata into an explicit |
The following IdP configuration implicitly releases attributes to any R&S SP. An attribute is released if and only if it is listed in SP metadata.
...
<AttributeFilterPolicy id="releaseToRandS">
<PolicyRequirementRule xsi:type="saml:AttributeRequesterEntityAttributeExactMatch"
attributeName="http://id.incommon.org/attribute/entity/category"
attributeValue="research-and-scholarship"/>
<AttributeRule attributeID="eduPersonPrincipalName">
<PermitValueRule xsi:type="ua:AttributeInMetadata" onlyIfRequired="false"/>
</AttributeRule>
<AttributeRule attributeID="email">
<PermitValueRule xsi:type="ua:AttributeInMetadata" onlyIfRequired="false"/>
</AttributeRule>
<AttributeRule attributeID="displayName">
<PermitValueRule xsi:type="ua:AttributeInMetadata" onlyIfRequired="false"/>
</AttributeRule>
<AttributeRule attributeID="givenName">
<PermitValueRule xsi:type="ua:AttributeInMetadata" onlyIfRequired="false"/>
</AttributeRule>
<AttributeRule attributeID="surName">
<PermitValueRule xsi:type="ua:AttributeInMetadata" onlyIfRequired="false"/>
</AttributeRule>
<AttributeRule attributeID="eduPersonScopedAffiliation">
<PermitValueRule xsi:type="ua:AttributeInMetadata" onlyIfRequired="false"/>
</AttributeRule>
</AttributeFilterPolicy>
| ||
Although R&S is specifically designed to facilitate attribute release, errors are expected and therefore service providers are strongly encouraged to support Federated Error Handling. A centralized Error Handling Service is provided for this purpose. |
Note: An alternative implementation exists in the uApprove add-on for Shibboleth. Information about uApprove is available at http://www.switch.ch/aai/support/tools/uApprove.html. No other IdP implementation is known to support entity attributes in SP metadata.
Further Policy Controls
If a campus determines that it wants to block release of attributes for certain community members (e.g., students who have opted out under FERPA), IdP operators could create an additional attribute release policy to enforce this decision. An example is available on the Shibboleth wiki. IdP plugins, such as uApprove, that provide end-user control over attribute release may also be useful to satisfy additional controls.
Metadata Support for the R&S Category
Upon approval, the following R&S entity attribute is inserted into SP 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="http://id.incommon.org/attribute/entity/category">
<saml:AttributeValue>http://id.incommon.org/category/research-and-scholarship</saml:AttributeValue>
</saml:Attribute>
</mdattr:EntityAttributes>
Assuming other SP categories are added in the future, an SP belonging to multiple categories would have a single entity <saml:Attribute> with multiple <saml:AttributeValue>'s.
...