This document describes how to map attributes that have been released to a Shibboleth Service Provider (SP) so that they are available for use within the SP application environment.
Background
A Shibboleth Identity Provider (IdP) can release user information to an SP at authentication time. The user information is presented as name-value pairs known as attributes. Attributes are useful for access control decisions and personalization within the SP application. To begin using attributes in your application, you may wish to review the Guide to NameID Formats and Attributes Available from the UW IdP and then make a request for attribute release based on your application’s requirements.
Once attributes have been released to your SP, you need to configure Shibboleth to make the attributes available to your application in the form of web server environment variables. Sample configurations are provided below.
Attribute mapping is configured in the attribute-map.xml file. This file contains many useful examples of attribute mappings that are commented out. To use them you need only uncomment them. The example below illustrates mapping for most of the attributes the UW IdP can release. Note that the “Name” field from the IdP is mapped to the “name” field on the SP. These values always match. The “FriendlyName” field from the IdP is mapped to the “id” field on the SP. The attribute-map.xml allows you to change the “id” to something different from the “FriendlyName” provided by the IdP, but there is rarely a good reason to do this.
<Attributes xmlns="urn:mace:shibboleth:2.0:attribute-map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <!-- New standard identifier attributes for SAML. Not yet available from the UW IdP. --> <Attribute name="urn:oasis:names:tc:SAML:attribute:subject-id" id="subject-id"> <AttributeDecoder xsi:type="ScopedAttributeDecoder" caseSensitive="false"/> </Attribute> <Attribute name="urn:oasis:names:tc:SAML:attribute:pairwise-id" id="pairwise-id"> <AttributeDecoder xsi:type="ScopedAttributeDecoder" caseSensitive="false"/> </Attribute> <!-- These are most of the attributes currently released by the UW IdP. In alphabetical order by id. See "Guide to NameID Formats and Attributes" at https://wiki.cac.washington.edu/x/QUioAQ. --> <Attribute name="urn:oid:2.5.4.3" id="cn"/> <Attribute name="urn:oid:2.16.840.1.113730.3.1.241" id="displayName"/> <Attribute name="urn:oid:1.2.840.113994.200.52" id="displayNameAndPronouns"/> <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.1" id="eduPersonAffiliation"> <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="false"/> </Attribute> <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.7" id="eduPersonEntitlement"/> <!-- entitlement_lib --> <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.7" id="entitlement_lib"/> <!-- entitlement_sln --> <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.7" id="entitlement_sln"/> <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="eduPersonPrincipleName"> <AttributeDecoder xsi:type="ScopedAttributeDecoder" caseSensitive="false"/> </Attribute> <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9" id="eduPersonScopedAffiliation"> <AttributeDecoder xsi:type="ScopedAttributeDecoder" caseSensitive="false"/> </Attribute> <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" id="eduPersonTargetedID"> <AttributeDecoder xsi:type="NameIDAttributeDecoder" formatter="$NameQualifier!$SPNameQualifier!$Name" defaultQualifiers="true"/> </Attribute> <Attribute name="urn:oid:2.16.840.1.113730.3.1.3" id="employeeNumber"/> <Attribute name="urn:oid:2.5.4.42" id="givenName"/> <Attribute name="urn:oid:2.5.4.11" id="homeDepartment"/> <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.5.1.1" id="isMemberOf"/> <Attribute name="urn:oid:0.9.2342.19200300.100.1.3" id="mail"/> <Attribute name="urn:oid:2.5.4.18" id="mailstop"/> <Attribute name="urn:oid:2.5.4.20" id="phone"/> <Attribute name="urn:oid:1.2.840.113994.200.47" id="preferredFirst"/> <Attribute name="urn:oid:1.2.840.113994.200.48" id="preferredMiddle"/> <Attribute name="urn:oid:1.2.840.113994.200.49" id="preferredSurname"/> <Attribute name="urn:oid:1.2.840.113994.200.32" id="registeredGivenName"/> <Attribute name="urn:oid:1.2.840.113994.200.31" id="registeredSurname"/> <Attribute name="urn:oid:2.5.4.4" id="surname"/> <Attribute name="urn:oid:2.5.4.12" id="title"/> <Attribute name="urn:oid:1.2.840.113994.200.45" id="uwEduEmail"/> <Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="uwNetID"/> <Attribute name="urn:oid:1.2.840.113994.200.51" id="uwPronouns"/> <Attribute name="urn:oid:1.2.840.113994.200.24" id="uwRegID"/> <Attribute name="urn:oid:1.2.840.113994.200.21" id="uwStudentID"/> <Attribute name="urn:oid:1.2.840.113994.200.20" id="uwStudentSystemKey"/> <!-- attributes only released for AWS --> <!-- attributes only released for Slack --> <!-- slack_email --> <Attribute name="User.Email" id="urn:oid:0.9.2342.19200300.100.1.3"/> <!-- slack_fname --> <Attribute name="first_name" id="urn:oid:2.5.4.42"/> <!-- slack_lname --> <Attribute name="last_name" id="urn:oid:2.5.4.4"/> <!-- slack_user --> <Attribute name="User.Username" id="urn:oid:0.9.2342.19200300.100.1.1"/></Attributes> |
Any time you have a shibboleth session on an SP you can view the released attributes by going to:
https://your-sp-host/Shibboleth.sso/Session |
Optionally configure the Session element in your shibboleth2.xml to show you the attribute values as well as the attribute IDs.
You can verify which attributes are being released to your SP by examining transaction.log. You should see entries like the following:
2011-06-01 21:45:36 INFO Shibboleth-TRANSACTION [4]: Cached the following attributes with session (ID: _13956486d801b3a0d2737f9f70b7d0f8) for (applicationId: default) {2011-06-01 21:45:36 INFO Shibboleth-TRANSACTION [4]: affiliation (3 values)2011-06-01 21:45:36 INFO Shibboleth-TRANSACTION [4]: eppn (1 values)2011-06-01 21:45:36 INFO Shibboleth-TRANSACTION [4]: uwnetid (1 values)2011-06-01 21:45:36 INFO Shibboleth-TRANSACTION [4]: employeeNumber (1 values)2011-06-01 21:45:36 INFO Shibboleth-TRANSACTION [4]: } |
You can verify which attributes are being mapped by examining shibd.log. You should see entries like the following for an SP using SAML 2 protocol:
2011-06-02 15:00:43 INFO Shibboleth.AttributeExtractor.XML : loaded XML resource (C:/opt/shibboleth-sp/etc/shibboleth/attribute-map.xml)2011-06-02 15:00:43 INFO Shibboleth.AttributeExtractor.XML : creating mapping for Attribute urn:oid:1.3.6.1.4.1.5923.1.1.1.62011-06-02 15:00:43 INFO Shibboleth.AttributeExtractor.XML : creating mapping for Attribute urn:oid:1.3.6.1.4.1.5923.1.1.1.92011-06-02 15:00:43 INFO Shibboleth.AttributeExtractor.XML : creating mapping for Attribute urn:oid:2.16.840.1.113730.3.1.32011-06-02 15:00:43 INFO Shibboleth.AttributeExtractor.XML : creating mapping for Attribute urn:oid:0.9.2342.19200300.100.1.1 |
Finally, you can place a script in a Shibboleth-protected directory on your SP that dumps all the web server environment variables to a web page. The following example is output from an IIS web server:
HTTP_AFFILIATION = member@washington.edu;staff@washington.edu;employee@washington.eduHTTP_EMPLOYEENUMBER = 880000000HTTP_EPPN = smith@washington.eduHTTP_UWNETID = smith |
An example .aspx script is provided with the Windows/IIS Service Provider installation instructions. All web programming environments provide some similar way to acheive the same thing. Many examples can be found on the Internet.
See Also
- Shibboleth Project’s NativeSPAddAttribute reference
- Shibboleth Project’s NativeSPAttributeAccess reference