Attribute release

For the UK federation's attribute release recommendations generally, please see section 7 of the UK federation's Technical Recommendations for Participants. There are four attributes that the UK federation regards as "core" attributes: eduPersonScopedAffiliation, eduPersonTargetedID, eduPersonPrincipalName and eduPersonEntitlement. The most commonly used of these are eduPersonScopedAffiliation and eduPersonTargetedID, so we focus on those here.

Attribute filter

The attribute filter configuration determines which attributes are released to which service providers, and is configured in the conf/attribute-filter.xml file. Most service providers in the UK federation require the attribute eduPersonScopedAffiliation with an affiliation value equivalent to full membership, eg. member, staff or student. The affiliation values released for a given user must be determined on the basis of the user's genuine affiliation with your organisation from your organisation's point of view.

In general the UK federation considers there to be very little personally identifying information carried by either eduPersonScopedAffiliation or eduPersonTargetedID so considers it safe to release them to any SP; the following configuration snippet does just that. However, your organisation should do its own risk analysis in consultation with its data protection officer rather than taking our word for it.

Note that this snippet would release these two attributes to any SP with which the IdP successfully authenticated; this might be a UK federation SP, or an SP imported from another federation via eduGAIN interfederation, or another SP for which the IdP has the metadata configured one way or another. More sophisticated attribute filters are possible; please see the Shibboleth documentation.

  <!-- 
    The UK federation considers there to be very little personally identifying
    information carried by either eduPersonScopedAffiliation or eduPersonTargetedID
    so considers it safe to release them to any SP
  --> 
  <AttributeFilterPolicy id="releaseToAnyone">
     <PolicyRequirementRule xsi:type="ANY" />
     <AttributeRule permitAny="true" attributeID="eduPersonScopedAffiliation" />
     <AttributeRule permitAny="true" attributeID="eduPersonTargetedID" />
     <AttributeRule permitAny="true" attributeID="eduPersonTargetedID.old" />
  </AttributeFilterPolicy>

Also note If your previous attribute release policies had depended on your use of a metadata aggregate tagged with groupID="http://ukfederation.org.uk" or the equivalent for metadata aggregate files from other federations (see the Benefits and risks section of the MDQ page), you may find the method for tagging per-entity metadata as described in the Internet2 Metadata Distribution Service documentation useful.

Attribute resolver

The attribute resolver configuration specifies how attributes are retrieved or generated on behalf of your users. You will need to make sure that there is a DataConnector element set up in the file to connect to your LDAP, assuming the attributes for your users are stored in an LDAP, or attributes or groups from the LDAP can be used to generate attributes. A database might also be used to store attributes.

There is an example attribute-resolver.xml file in the conf directory containing an example LDAP DataConnector configuration, called attribute-resolver-ldap.xml. The DataConnector configuration will need to be modified for your local set-up.

Note the IdP only reads attribute-resolver.xml and not the attribute-resolver-ldap.xml file.

As discussed previously in LDAP Configuration the default configuration of Active Directory often only has unencrypted LDAP (TCP port 389 or 3268) enabled. If using the attribute-resolver-ldap.xml as a base, then you may need to remove or comment out the following within the DataConnector id="myLDAP".

 useStartTLS="%{idp.attribute.resolver.LDAP.useStartTLS:true}"
 trustFile="%{idp.attribute.resolver.LDAP.trustCertificates}"

eduPersonScopedAffiliation

Assuming you have a DataConnector configuration with id="myLDAP", and the LDAP has been populated with the eduPersonAffiliation attribute for all your users, then you can use the eduPersonAffiliation attribute as the basis to generate eduPersonScopedAffiliation by means of the following snippet in attribute-resolver.xml:

  <AttributeDefinition id="eduPersonScopedAffiliation" xsi:type="Scoped"
                        scope="%{idp.scope}">
        <InputDataConnector ref="myLDAP" attributeNames="eduPersonAffiliation"/>
        <AttributeEncoder xsi:type="SAML1ScopedString"
                         name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation"
                         encodeType="false" />
        <AttributeEncoder xsi:type="SAML2ScopedString" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9"
                         friendlyName="eduPersonScopedAffiliation" encodeType="false" />
    </AttributeDefinition>

If the LDAP has not been populated with eduPersonAffiliation and it is not possible to arrange for it to be populated then you may need to use either a script or mapped attribute definition for eduPersonAffiliation, based on other attributes or groups in the LDAP. An example of this can be found on our Mapped Affiliation page.

Note: previously versions of this documentation may have link to a scripted example, we advise avoiding the user of Scripted Attributes within the IdP if possible.

eduPersonTargetedID

This attribute again depends on having a DataConnector configuration to connect to your LDAP. It also requires a ComputedId DataConnector.

Please note: the ComputedId was previously deprecated and the Shibboleth team recommended that it and the eduPersonTargetedID attribute are no longer used, and that a persistent ID should be released as a subject name identifier instead. However, there has since been a reversal of this and the connector is no longer deprecated and remains in place whilst new profiles for SAML subject identification (pairwise-id). Please see the ComputedId documentation and the subject name identifier documentation.

However, there are legacy SPs and non-Shibboleth SPs that may not be able to accept subject name identifiers in place of eduPersonTargetedID, so the UK federation recommends that UK federation IdP operators continue to release eduPersonTargetedID.

The UK federation advise is now to streamline your configuration with that for the pairwise-id, by setting many of the details (source attribute, salt) in saml-nameid.properties, and refering to these values in the DataConnector

Assuming your DataConnector configuration has id="myLDAP" then the ComputedId DataConnector might look like this:

  <DataConnector id="computed" xsi:type="ComputedId"
                            generatedAttributeID="computedId"
                            salt="%{idp.persistentId.salt}"
                	    algorithm="%{idp.persistentId.algorithm:SHA}"
                            encoding="%{idp.persistentId.encoding:BASE32}">
       <InputDataConnector ref="myLDAP" attributeNames="%{idp.persistentId.sourceAttribute}" />
   </DataConnector>

Within saml-nameid.properties, you then set the #idp.persistentId.sourceAttribute be that uid often used in OpenLDAP based directories. Whichever source attribute is chosen, it should not change over time.

    idp.persistentId.sourceAttribute=uid

In Active Directory, the users login name is often called sAMAccountName, although this has been known to change during the lifetime of a user's account. Depending on your system, either objectGUID or objectSid could be used.

The objectGUID is binary, so if it is to be used as the source attribute it should be declared as binary by adding this line to the LDAP DataConnector with id="myLDAP":

 <LDAPProperty name="java.naming.ldap.attributes.binary" value="objectGUID"/>

If you use objectSid, you'll need to add a similar element to the LDAP DataConnector.

Note that the order of the elements within the DataConnector matters. Please consult the LDAP Connector documentation on the Shibboleth wiki for the appropriate placing of the LDAPProperty.

The property idp.persistentId.salt can be set in saml-nameid.properties or possibly another properties file used for storing passwords, or the value can be included directly in the DataConnector. It is a random string of at least 16 bytes which you choose. It should be kept secret.

   idp.persistentId.salt=0123456789abcdef

If you are migrating from an earlier version of the software you should use the same source attribute and salt value as you used previously, and set idp.persistentId.encoding = BASE64 setting in saml-nameid.properties, which will ensure that the same values are generated for each of your users. This is necessary to retain access to personalisations saved on SPs that are keyed to eduPersonTargetedID values.

   idp.persistentId.encoding = BASE64

There are two forms of eduPersonTargetedID, a scoped form which we refer to here eduPersonTargetedID.old and the unscoped form which we refer to as eduPersonTargetedID. We suggest you release both forms, to allow for older SPs that do not recognise the unscoped form. Here are the attribute definitions for these two forms:

   <AttributeDefinition xsi:type="SAML2NameID" id="eduPersonTargetedID"
                        nameIdFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">
        <InputDataConnector ref="computed" attributeNames="computedId"/>
        <AttributeEncoder xsi:type="SAML1XMLObject"
                          name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" />
        <AttributeEncoder xsi:type="SAML2XMLObject"
                          name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10"
                          friendlyName="eduPersonTargetedID" />
  </AttributeDefinition>

   <AttributeDefinition xsi:type="Scoped" id="eduPersonTargetedID.old"
                        scope="%{idp.scope}">
        <InputDataConnector ref="computed" attributeNames="computedId"/>
        <AttributeEncoder xsi:type="SAML1ScopedString"
                          name="urn:mace:dir:attribute-def:eduPersonTargetedID" />
  </AttributeDefinition>

Attribute Release Consent

The v3 IdP includes a flexible mechanism to allow people using your IdP to consent to the release of attributes about them. This is enabled by default for new installations and is a significant change to user interaction from the v2 IdP. See our documentation on Attribute Release Consent for details.

Consent example configuration

The following example configuration could be used, this ensures users only see the consent notification where personal information is being released, but for identifiers and affiliations they do see the notification.

Within in %{idp.home}/config/intercept/consent-intercept-config.xml, add <value> statements for eduPersonTargetedID.old eduPersonScopedAffiliation eduPersonAffiliation and eduPersonEntitlement, within the shibboleth.consent.attribute-release.BlacklistedAttributeID list. The section of configuration should now look like this;

    <util:list id="shibboleth.consent.attribute-release.BlacklistedAttributeIDs">
        <value>transientId</value>
        <value>persistentId</value>
        <value>eduPersonTargetedID</value>
        <value>eduPersonTargetedID.old</value>
        <value>eduPersonScopedAffiliation</value>
        <value>eduPersonAffiliation</value>
        <value>eduPersonEntitlement</value>
    </util:list>