This document is for U-M information technology staff members. It (1) Provides brief background information about federated identity management, InCommon, Shibboleth and attributes; (2) Describes the procedure for requesting that U-M release attributes to a Shibboleth Service Provider (SP) to permit access to U-M users; (3) Provides detailed information about the attributes available to SPs; and (4) Details the general procedure for reviewing and approving attribute release.
About Federated Identity Management
Many individuals need access to resources based in different university units. Federated identity management grants access to multiple websites with the same login information.
With federated identity management, institutions join together in a group—a federation—and agree to trust each other's identity credentials. This can be analogized with bank ATM access- many banks allow ATM access even if the ATM belongs to a different bank.
-
U-M is a member of the InCommon Federation. This means that InCommon members agree to trust U-M to vouch for the identity of someone who has logged in using U-M's web authentication method (Cosign).
-
U-M also maintains the UMICH Federation, a federation consisting of U-M services that are not part of the InCommon federation.
Federations use federated identity management software to allow them to vouch for their users' identities and to share information about whether those users meet the authorization requirements for a particular service (for example, a license that limits access to students). U-M has agreed to trust other InCommon members when they vouch for the identity of people who have logged in using their authentication methods. These institutions share additional identity information, called "attributes," to allow them to make authorization decisions.
About Shibboleth
The InCommon Federation uses Shibboleth federated identity management software from Internet2. According to Internet2:
Shibboleth is a standards based, open source software package for web single sign-on across or within organizational boundaries. It allows sites to make informed authorization decisions for individual access of protected online resources in a privacy-preserving manner.
Shibboleth has two primary components:
-
Identity Provider (IdP). The Internet2 website describes an IdP as, "the software run by an organization with users wishing to access a restricted service." The U-M IdP, which is run by ITS, can be configured to interact with each service that U-M users wish to access via Shibboleth.
-
Service Provider (SP). Internet2 describes an SP as, "the software run by the provider managing the restricted service." U-M units may wish to install Shibboleth SP software to allow users at other institutions to access the web-based services that they provide. For details about and help setting up an SP at U-M, see the Shibboleth Documentation.
About Attributes
Attributes are specific bits of information about people. They include such things as a person's name and email address. There are established attributes with specific names that are used for federated identity management. Institutions can also create their own attributes.
Attributes can be used
-
To determine if someone is authorized to use a particular service. For example, a particular service might be provided only to faculty members.
-
To customize services for people after they have logged in. For example, once you are logged in, a service page may greet you by name and show you a customized menu based on what you are authorized to use.
A basic set of attributes has been pre-approved for release to SPs that are members of the InCommon or UMICH federation. Requests for release of additional attributes must go through an approval process.
User Confirmation of Attribute Release
Depending on the service an individual is logging in to and the last time they confirmed release of their attributes, he/she may be asked to confirm release of their attributes to the SP.
For Services Provided Through U-M
-
No confirmation necessary: For services using Shibboleth that are provided by the university through an agreement with another provider—such as
U-M Box andU-M Google—users are not asked to confirm attribute release.
For Other Services
When logging in to other services, people have the opportunity to confirm or deny release of their attributes. However, attribute release may be required for log in. (See Logging in to Shibboleth-Enabled Services and Websites for a screenshot of the attribute release confirmation screen.)
-
Annual confirmation required: The first time users log in to a new Shibboleth-enabled service and annually thereafter, they are prompted to confirm release of their attributes.
-
Confirmation required when information changes: Users are prompted to confirm attribute release when any of the attributes to be released have changed. For example, if an individual changes his/her name, affiliation, or uniqname, he/she will be asked to confirm attribute release. People may also be asked to confirm attribute release if the Service Provider or Identity Provider software changes or is updated.
-
Users may choose to confirm at each login: When users login to a particular service and see the attribute release screen, they have the option to choose to asked to consent to release at their next login to that service.
Attributes Pre-Approved for U-M Release
These attributes are pre-approved by U-M for release, upon confirmation by the user, to Shibboleth-enabled SPs that are members of InCommon or that have been added to the UMICH federation. They are also pre-approved upon user confirmation to SPs that InCommon has designated as being in its Research and Scholarship Category.
These pre-approved attributes are based on InCommon's recommended Essential Attribute Bundle. U-M IT staff members do not need to submit a request for attribute release or perform any set-up work. No additional configuration is necessary. U-M users will be able to login. These attributes are released by default to UMICH federation and InCommon federation service providers, unless the service provider requests otherwise during configuration (see Requesting that U-M Withhold Specific Attributes below).
MCommunity is the authoritative source for most of these attributes. See Data Sources for MCommunity in MCommunity Overview for details. The givenName, displayName, and umichDisplaySN attributes are populated in MCommunity from various data sources, depending on the person’s relationship to the university. If the data source is Wolverine Access/M-Pathways and the user has set a preferred name there, the preferred name will appear in the givenName, displayName, and umichDisplaySN attribute.
| Attribute | Definition | Encoding |
|---|---|---|
| eduPersonPrincipalName | This is [email protected], where uniqname has been replaced with the person's actual uniqname. The uniqname is pulled from the MCommunity uid attribute, then @umich.edu is added to it. | SAML 1 urn:mace:dir:attribute-def:eduPersonPrincipalName SAML 2 urn:oid:1.3.6.1.4.1.5923.1.1.1.6 |
| This is the person's email address as listed in MCommunity. It is not the email forwarding address. This is [email protected], where uniqname has been replaced with the person's actual uniqname. It is pulled from the MCommunity mail attribute. | SAML1 urn:mace:dir:attribute-def:mail SAML2 urn:oid:0.9.2342.19200300.100.1.3 |
|
| eduPersonAffiliation | The affiliation information is pulled from the umichInstRoles attribute in MCommunity. One or more of these values is/are returned: student, faculty, staff, employee, alum, affiliate, member. See below for details about which MCommunity affiliations fit into these attributes. | SAML1 urn:mace:dir:attribute-def:eduPersonAffiliation SAML2 urn:oid:1.3.6.1.4.1.5923.1.1.1.1 |
| eduPersonScopedAffiliation | The institution the person is affiliated with is added to the eduPersonAffiliation attribute. Ann Arbor affiliations are appended with @annarbor.umich.edu, Dearborn affiliations with @dearborn.umich.edu, and Flint affiliations with @flint.umich.edu. These values are not email addresses. | SAML 1 urn:mace:dir:attribute-def:eduPersonScopedAffiliation SAML 2 urn:oid:1.3.6.1.4.1.5923.1.1.1.9 |
| displayName | This is pulled from the Display Name attribute in MCommunity. | SAML1 urn:mace:dir:attribute-def:displayName SAML2 urn:oid:2.16.840.1.113730.3.1.241 |
| givenName | This is the person's first name. It is pulled from the givenName attribute in MCommunity. | SAML1 urn:mace:dir:attribute-def:givenName SAML2 urn:oid:2.5.4.42 |
| sn | Sn stands for surname. It is the person's last name. It is pulled from the umichDisplaySN attribute in MCommunity. | SAML1 urn:mace:dir:attribute-def:sn SAML2 urn:oid:2.5.4.4 |
| eduPersonEntitlement | This is the standard entitlement attribute used by InCommon. It is used to determine whether a user is entitled to use a particular service. It is open-ended and depends on the request made by the SP. If, for example, the SP has licensing restrictions that limit access to current students, this attribute could be derived from eduPersonScopedAffiliation. | SAML1 urn:mace:dir:attribute-def:eduPersonEntitlement SAML2 urn:oid:1.3.6.1.4.1.5923.1.1.1.7 |
Note Shibboleth has deprecated eduPersonTargetedID. Shibboleth Identity Provider (IdP) software version 3.1.2 does not include the eduPersonTargetedID attribute. Use of this attribute is no longer supported. The mechanism to generate that attribute is expected to be removed from Shibboleth in the future.
The table below shows which eduPersonAffiliation attributes released by the U-M Shibboleth IdP correspond to which umichInstRoles MCommunity attributes.
| eduPersonAffiliation | umichInstRoles (in MCommunity) |
|---|---|
| student | Student, EnrolledStudent |
| faculty | Faculty |
| staff | RegularStaff |
| employee | Faculty, RegularStaff, TemporaryStaff |
| alum | Alumni |
| affiliate | SponsoredAffiliate |
| member | Student, EnrolledStudent, Faculty, RegularStaff, TemporaryStaff, Retiree, Alumni |
Requesting that U-M Withhold Specific Attributes
There are situations in which the SP may not need access to the user's name, email address, or other identity information. University units can request that any of the auto-release attributes listed above be withheld from a particular InCommon-member SP.
To request that an attribute be withheld from an SP, contact [email protected].
Requesting U-M Release of Additional Attributes
Important Please submit your request as soon as you know you will need release of additional attributes beyond those pre-approved. This will leave the Shibboleth Technical Team and the appropriate data steward enough time to review and implement your request.
In general, an attribute will not be released unless there is a business reason for its release. If you request release of an attribute, please be sure that there is a real need for its release.
To request approval of release of additional attributes, fill out and submit the online ITS Shibboleth Attribute Release Request form
Note that requests must be made by U-M IT staff representing a university department or unit.
The following table contains examples of commonly requested attributes and their encodings.
| Attribute | Definition | Encoding |
|---|---|---|
| employeeNumber | This is the person's UMID. It is pulled from the entityid attribute in MCommunity. | SAML1 urn:mace:dir:attribute-def:employeeNumber SAML2 urn:oid:2.16.840.1.113730.3.1.3 |
| uid | This is the person’s uniqname. It is pulled from the uid attribute in MCommunity. Most often used as a unique identifier in a form other than email address. | SAML1 urn:mace:dir:attribute-def:uid SAML2 urn:oid:0.9.2342.19200300.100.1.1 |
How Attribute Release Requests Are Handled
ITS reviews requests for release of additional attributes for technical feasibility and completeness. If the Shibboleth team has questions about your attribute release request, they will contact you. Both the review process and the set-up for attribute release are iterative, and you may be asked for clarification or additional information at any point in the process.
If the attributes you are requesting fall under established review procedures, ITS will pass your request on to the appropriate data steward(s), manager(s) or review group.
Straightforward requests may be approved within a few business days and implemented in just a few more days after that.
Complex or difficult requests may require several weeks for approval and several additional weeks for setup. A request can take extra processing time if it entails new data feeds, custom programming, or if several units/institutions need to coordinate with each other. Please take this into account when creating your project plan.
For further help with Shibboleth, send an email to [email protected].