Page History

...

If you have created attribute definitions that might also be relevant for other members of the community – e.g. based on the widely used (within Austria) Campus Online software – please share them! Contributions to this wiki are very much welcome. You can also just send them to the eduID.at Operations Team, of course, and we will edit and include them here.

...

<AttributeDefinition id="givenName" xsi:type="Simple">
    <InputDataConnector ref="myLDAP" attributeNames="givenName" />
    <DisplayName xml:lang="de">Vorname</DisplayName>
    <DisplayName xml:lang="en">Given name</DisplayName></AttributeDefinition>

sn

<AttributeDefinition id="sn" xsi:type="Simple">
    <AttributeEncoder<InputDataConnector xsi:typeref="SAML1StringmyLDAP" nameattributeNames="urn:mace:dir:attribute-def:givenName" encodeType="false" />
    <AttributeEncoder xsi:type="SAML2String" name="urn:oid:2.5.4.42" friendlyName="givenName" encodeType="false" />
</AttributeDefinition>

...

sn" />
</AttributeDefinition>

displayName

If you have the displayName attribute available in your LDAP directory we'll go with that, as it's not generally being misused to store data other than the subject's real name (like "cn" commonly is, e.g. storing the subject's login name or userid instead of her real name).

<AttributeDefinition id="surnamedisplayName" xsi:type="Simple">
    <InputDataConnector ref="myLDAP" attributeNames="sndisplayName" />
    <DisplayName xml:lang="de">Zuname</DisplayName>
    <DisplayName xml:lang="en">Surname</DisplayName>
    <AttributeEncoder xsi:type="SAML1String" name="urn:mace:dir:attribute-def:sn" encodeType="false" />
    <AttributeEncoder xsi:type="SAML2String" name="urn:oid:2.5.4.4" friendlyName="sn" encodeType="false" />
</AttributeDefinition>

displayName

</AttributeDefinition>

If you only have the "cn" LDAP attribute available and it contains the subject's full name (not her login name / userid) you can simply change the InputDataConnector's attributeNames XML attribute to become attributeNames="cn" in the second line of the example above. (Don't change anything else!) In this case you'll need to be aware that contrary to "cn" displayName is defined to be single-valued, though, and therefore you should be absolutely certain that your source attribute ("cn" in the modified example here) only ever contains a single value per subject in your LDAP deployment, for all subjects! If that requirement cannot bet met you will need to use a slightly more complex AttributeDefinition that takes one of the values (usually the first one as returned by an LDAP search) and turns that into the displayName attribute.

If you don't have the subject's full name available in your LDAP deployment (or your "cn" attribute is unusable because it may contain multiple values for a subject, but your givenName and sn attributes are single-valued) you can create this SAML attribute from first name and last name dynamically within the Shibboleth IDP:If you have the displayName attribute available in your LDAP directory we'll go with that, as it's not generally being misused to store data other than the subject's real name (like "cn" commonly is, e.g. storing the subject's login name or userid instead of her real name).

<AttributeDefinition id="displayName" xsi:type="SimpleTemplate">
    <InputDataConnector<InputAttributeDefinition ref="myLDAP" attributeNames="displayNamegivenName" />
    <DisplayName<InputAttributeDefinition xml:langref="desn">Name< /DisplayName>>
    <DisplayName xml:lang="en">Name</DisplayName>
    <AttributeEncoder xsi:type="SAML1String" name="urn:mace:dir:attribute-def:displayName" encodeType="false" />
    <AttributeEncoder xsi:type="SAML2String" name="urn:oid:2.16.840.1.113730.3.1.241" friendlyName="displayName" encodeType="false" />
</AttributeDefinition>

If you only have the "cn" LDAP attribute available and it contains the subject's full name (not her login name / userid) you can simply change the InputDataConnector's attributeNames XML attribute to become attributeNames="cn" in the second line of the example above. (Don't change anything else!) In this case you'll need to be aware that contrary to "cn" displayName is defined to be single-valued, though, and therefore you should be absolutely certain that your source attribute ("cn" in the modified example here) also only ever contains a single value per subject in your LDAP deployment, for all subjects! If that requirement cannot bet met you will need to use a slightly more complex AttributeDefinition that takes one of the values (usually the first one as returned by an LDAP search) and turns that into the displayName attribute. You can request such an example to be added to this wiki on the eduid-discuss mailing list.

If you don't have the subject's full name available in your LDAP deployment (or your "cn" attribute is unusable because it may contain multiple values for a subject, but your givenName and sn attributes are single-valued) you can create this SAML attribute from first name and last name dynamically within the Shibboleth IDP:

<Template>${givenName} ${sn}</Template>
</AttributeDefinition> 

Note that givenName and sn allow for multiple values, just like cn! So only use the above method if you're certain that your LDAP directory is only using those attributes with single values.

Identifiers

With the notable exception of Library Services almost all (other) SAML Service Providers will need to consistently recognise a returning subject. I.e., they may not need to know who you are based on the identifier alone, but they will need to know that you are the same subject accessing their services as when you accessed them previously. That's what subjects expect themselfs, of course, otherwise all their work/data would be unavailable to them the next time they accessed the same service! See also this comparison of commonly used identifiers and their properties from the Shibboleth wiki.

All eduID.at IDPs should be able to produce all of these identifiers, in order to be able to interoperate with – and make use of – all SAML Services Providers your community members may need to work with.

mail

If you have a "mail" attribute with the subject's email address available in your LDAP directory, the example below is all you need. Ideally the LDAP attribute should in practice be single-valued (i.e., never contain more than one attribute value for a subject) as some SAML Service Providers cannot handle multi-valued attributes. This attribute's specification does allow for multiple values, of course, but you may make your life harder by not being able to supply a single-valued version of what's in your LDAP directory.

<AttributeDefinition id="mail" xsi:type="Simple

<AttributeDefinition id="displayName" xsi:type="Template">
    <InputDataConnector ref="myLDAP" attributeNames="givenName snmail" />
    <DisplayName xml:lang="de">Name</DisplayName>
    <DisplayName xml:lang="en">Name</DisplayName>
    <Template>${givenName} ${sn}</Template>
    <SourceAttribute>givenName</SourceAttribute>
    <SourceAttribute>sn</SourceAttribute>
    <AttributeEncoder xsi:type="SAML1String" name="urn:mace:dir:attribute-def:displayName" encodeType="false" />
    <AttributeEncoder xsi:type="SAML2String" name="urn:oid:2.16.840.1.113730.3.1.241" friendlyName="displayName" encodeType="false" />
</AttributeDefinition> 

Note that givenName and sn allow for multiple values (just like cn). So only use the above method if you're certain that your LDAP directory is only using them with single values.

Identifiers

With the notable exception of Library Services almost all (other) SAML Service Providers will need to consistently recognise a returning subject. I.e., they may not need to know who you are based on the identifier alone, but they will need to know that you are the same subject accessing their services as when you accessed them previously. That's what subjects expect themselfs, of course, otherwise all their work/data would be unavailable to them the next time they accessed the same service! See also this comparison of commonly used identifiers and their properties from the Shibboleth wiki.

All eduID.at IDPs should be able to produce all of these identifiers, in order to be able to interoperate with – and make use of – all SAML Services Providers your community members may need to work with.

mail

If you have a "mail" attribute with the subject's email address available in your LDAP directory, the example below is all you need. Ideally the LDAP attribute should in practice be single-valued (i.e., never contain more than one attribute value for a subject) as some SAML Service Providers cannot handle multi-valued attributes. This attribute's specification does allow for multiple values, of course, but you may make your life harder by not being able to supply a single-valued version of what's in your LDAP directory.

<AttributeDefinition id="mail" xsi:type="Simple">
    <InputDataConnector ref="myLDAP" attributeNames="mail" />
    <DisplayName xml:lang="de">E-Mail-Adresse</DisplayName>
    <DisplayName xml:lang="en">Email address</DisplayName>
    <AttributeEncoder xsi:type="SAML1String" name="urn:mace:dir:attribute-def:mail" encodeType="false" />
    <AttributeEncoder xsi:type="SAML2String" name="urn:oid:0.9.2342.19200300.100.1.3" friendlyName="mail" encodeType="false" />
</AttributeDefinition>

</AttributeDefinition>

Some Some institutions may need more complex processing than the above, e.g. getting the value from one of several LDAP attribute depending on the role/affiliation of the subject (localPersonStudentMail, localPersonStafMail). The eduID.at community (or the eduID.at Operatons Team) will be able to supply you with other/more complex examples, so please ask.

Our documentation for creation and usage of eduPersonPrincipalName also contains some info on using email addresses as identifiers (and why/when best to avoid it), but sometimes services just need an email address for email's sake and will rely on other attributes for the unique identification of the subject.

eduPersonPrincipalName

eduPersonPrincipalName is commonly produced either from the local login name (uid, sAMAccountName) or by re-using a copy of the institutional email address as its value. Our documentation for that attribute explains the pros and cons of each approach in detail. Below you'll find examples for both main methods used to create that attribute. First, the variant based on login name (replace sourceAttributeID="uid" with sourceAttributeID="sAMAccountName" or whatever holds local login names in your LDAP directory):

just need an email address for email's sake and will rely on other attributes for the unique identification of the subject.

eduPersonPrincipalName

eduPersonPrincipalName is commonly produced either from the local login name (uid, sAMAccountName) or by re-using a copy of the institutional email address as its value. Our documentation for that attribute explains the pros and cons of each approach in detail. Below you'll find examples for both main methods used to create that attribute. First, the variant based on login name (replace sourceAttributeID="uid" with sourceAttributeID="sAMAccountName" or whatever holds local login names in your LDAP directory):

<!-- https://wiki.univie.ac.at/display/federation/eduPersonPrincipalName -->
<AttributeDefinition id="eduPersonPrincipalName" xsi:type="Scoped" scope="%{idp.scope}">
    <InputDataConnector ref="myLDAP" attributeNames="uid

<!-- https://wiki.univie.ac.at/display/federation/eduPersonPrincipalName -->
<AttributeDefinition id="eduPersonPrincipalName" xsi:type="Scoped" scope="%{idp.scope}">
    <InputDataConnector ref="myLDAP" attributeNames="uid" />
    <DisplayName xml:lang="de">Benutzerkennung</DisplayName>
    <DisplayName xml:lang="en">User identifier</DisplayName>
    <AttributeEncoder xsi:type="SAML1ScopedString" name="urn:mace:dir:attribute-def:eduPersonPrincipalName" encodeType="false" />
    <AttributeEncoder xsi:type="SAML2ScopedString" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" friendlyName="eduPersonPrincipalName" encodeType="false" />
</AttributeDefinition>

...

<AttributeDefinition id="eduPersonPrincipalName"<AttributeDefinition id="eduPersonPrincipalName" xsi:type="Prescoped">
    <InputDataConnector ref="myLDAP" attributeNames="mail" />
    <DisplayName xml:lang="de">Benutzerkennung</DisplayName>
    <DisplayName xml:lang="en">User identifier</DisplayName>
    <AttributeEncoder xsi:type="SAML1ScopedString" name="urn:mace:dir:attribute-def:eduPersonPrincipalName" encodeType="false" /Prescoped">
    <AttributeEncoder<InputDataConnector xsi:type="SAML2ScopedString" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" friendlyName="eduPersonPrincipalName" encodeType="falseref="myLDAP" attributeNames="mail" />
</AttributeDefinition>

...

The SAML SubjectID can be seen as an opaque (not name-based, long "ugly" values), more stable version of eduPersonPrincipalName. It is intended as a replacement for the eduPersonUniqueID attribute , possibly and possibly also for eduPersonPrincipalName itself. The example provided below re-uses configuration already made to support persistent NameIDs, namely the settings properties idp.persistentId.sourceAttribute (from /opt/shibboleth-idp/conf/saml-nameid.properties) and idp.persistentId.salt (from the file /opt/shibboleth-idp/confcredentials/saml-nameidsecrets.properties).

Provided you already have a stable, non-recycled (i.e., not reassigned from one subject to another) internal identifier for your subjects you can set that attribute in the idp.persistentId.sourceAttribute property of the referenced config file, and it will also be used as the basis for the SubjectID attribute. The configuration below also re-uses the salt configured in the property idp.persistentId.salt to generate a salted hash of the chosen source attribute as (local part of the) SubjectID attribute value:

<AttributeDefinition id="subjectHash" xsi:type="ScriptedAttribute" dependencyOnly="true">
    <InputDataConnector ref="myLDAP" attributeNames="%{idp.persistentId.sourceAttribute}" />
    <Script><![CDATA[
      var digestUtils = Java.type("org.apache.commons.codec.digest.DigestUtils");
      var saltedHash  = digestUtils.sha256Hex(%{idp.persistentId.sourceAttribute}.getValues().get(0) + "%{idp.persistentId.salt}");
      subjectHash.addValue(saltedHash);
    ]]></Script>
</AttributeDefinition>

<AttributeDefinition id="subject-id" xsi:type="Scoped" scope= + "%{idp.persistentId.scopesalt}">);
     <InputAttributeDefinition ref="subjectHash" />subjectHash.addValue(saltedHash);
    <DisplayName xml:lang="de">Opake Benutzerkennung</DisplayName>
    <DisplayName xml:lang="en">Opaque user identifier</DisplayName>
    <AttributeEncoder xsi:type="SAML2ScopedString" name="urn:oasis:names:tc:SAML:attribute:subject-id" friendlyName="subject-id" encodeType="false]]></Script>
</AttributeDefinition>

<AttributeDefinition id="samlSubjectID" xsi:type="Scoped" scope="%{idp.scope}">
    <InputAttributeDefinition ref="subjectHash" />
</AttributeDefinition>

...

<AttributeDefinition id="subjectIdBasis" xsi:type="Template" dependencyOnly="true">
    <InputDataConnector ref="myLDAP" attributeNames="userPrincipalName whenCreated" />
    <Template>${userPrincipalName} ${whenCreated}</Template>
</AttributeDefinition>

...

Now the "subjectHash" attribute definition will use the "fabricated" identifier (combined from the userPrincipalName and whenCreated attributes) as basis and the rest of that example above works the same way for everyone (including the "subject-id" samlSubjectID attribute defintion which does not need to be changed at all).

...

The SAML PairwiseID is an opaque, persistent, service-specific pseudonym. It is intended as a replacement for the replaces the eduPersonTargetedID attribute as well as for standard SAML 2.0 persistent NameIDs. The example provided below re-uses configuration already made to support persistent NameIDs, namely the settings properties idp.persistentId.sourceAttribute and  (from /opt/shibboleth-idp/conf/saml-nameid.properties) and idp.persistentId.salt from the file  (from /opt/shibboleth-idp/confcredentials/saml-nameidsecrets.properties).

<AttributeDefinition id="pairwise-idsamlPairwiseID" xsi:type="Scoped" scope="%{idp.scope}">
    <InputDataConnector ref="computed" attributeNames="ComputedID" />
    <DisplayName xml:lang="de">Service-spezifische Benutzerkennung</DisplayName>
    <DisplayName xml:lang="en">Service-specific pseudonym</DisplayName>
    <AttributeEncoder xsi:type="SAML2ScopedString" name="urn:oasis:names:tc:SAML:attribute:pairwise-id" friendlyName="pairwise-id" encodeType="false   <InputDataConnector ref="computed" attributeNames="computedId" />
</AttributeDefinition>

...

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

Similarly to SubjectIDs above: If you don't have a stable, non-reassigned internal identifier in your Systems of Record (LDAP directory, relational database) and decided to fabricate one as – (as shown in the examples for SubjectID above – you) you'll need to replace that DataConnector's dependency with the custom one you created earlier, e.g.:

...

Authorization / Org data

...

eduPersonScopedAffiliation is sometimes used for simple authorisation cases. eduPersonAffiliation describes a person's relationship with the IDP's organisation in general terms (from a controlled vocabulary of only 8 allowed values), and eduPersonScopedAffiliation is simply the scoped variant of that (i.e., the applicable affiliation values each suffixed with "@" + the main institutional domain, same as for eduPersonPrincipalName or eduPersonUniqueIDsamlSubjectID). Only the scoped version should be used for federated use cases: Even if a recieving Service Provider did not want to differentiate between e.g. staff@example-unifaculty@example.atedu and staff@researchfaculty@research.example.com it can always easily throw away the scope with minimal processing, yielding the unscoped version (here: "stafffaculty" in both cases).

In the examples below we'll first create the unscoped version using one of several alternative methods, since this part will need be done differently at most organisations as it depends on local Identity Management choices. Then further below we'll create the scoped variant from that, in a configuration snippet that can be the same for everyone, no matter how the (unscoped) affiliation values was created.

Here's a first very simple example that creates a few of the affiliation values based on a regex match of some other attribute's value, in this case the login name as stored in the "uid" LDAP attribute (cf. sourceAttributeID). Replace with "sAMAccountName" or "cn" or whatever as needed in your deployment. This method can be used if you assign login names based on a schema that encodes the role/affiliation of a subject into her login name/userid. While overloading identifiers with semantics (such as role information) is not generally recommended such practices exist , so you might as well make use of them if it makes your IDP configuration easier. Note that identical SouceValue SourceValue elements are used twice below to make sure all students are also members, and all staff are also members, too, as required by the eduPerson specification.

...

Finally, it's time to turn the (unscoped) eduPersonAffiliation values created by one of the methods above into a properly scoped one:unscoped) eduPersonAffiliation values created by one of the methods above into a properly scoped one:

<AttributeDefinition id="eduPersonScopedAffiliation"

<AttributeDefinition id="eduPersonScopedAffiliation" xsi:type="Scoped" scope="%{idp.scope}">
    <InputAttributeDefinition ref="eduPersonAffiliation" />
    <DisplayName xml:lang="de">Rollen an der Institution</DisplayName>
    <DisplayName xml:lang="en">Affiliations</DisplayName>
    <AttributeEncoder xsi:type="SAML1ScopedString" name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation" encodeType="false" />
    <AttributeEncoder xsi:type="SAML2ScopedStringScoped" namescope="urn:oid:1.3.6.1.4.1.5923.1.1.1.9" friendlyName="eduPersonScopedAffiliation" encodeType="false%{idp.scope}">
    <InputAttributeDefinition ref="eduPersonAffiliation" />
</AttributeDefinition>

...

<AttributeDefinition id="eduPersonEntitlement" xsi:type="Mapped">
    <InputAttributeDefinition ref="eduPersonAffiliation" />
    <DisplayName xml:lang="de">Berechtigungen</DisplayName>
    <DisplayName xml:lang="en">Entitlements</DisplayName> ref="eduPersonAffiliation" />
    <ValueMap>
        <ReturnValue>urn:mace:dir:entitlement:common-lib-terms</ReturnValue>
        <SourceValue>member</SourceValue>
        <SourceValue>library-walk-in</SourceValue>
    </ValueMap>
    <AttributeEncoder xsi:type="SAML1String" name="urn:mace:dir:attribute-def:eduPersonEntitlement" encodeType="false" />
    <AttributeEncoder xsi:type="SAML2String" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.7" friendlyName="eduPersonEntitlement" encodeType="false" />/SourceValue>
    </ValueMap>
</AttributeDefinition>

Another use-case relevant to ACOnet and GÉANT communities is the GÉANT Trusted Certificate Service that relies on a specific eduPersonEntitlement value to signal that a given subject satisfies the criteria to automatically issue them personal X.509 certificates (based on personal data provided in other SAML attributes, such as name and email address).

...

<AttributeDefinition id="eduPersonEntitlement" xsi:type="Mapped">
    <InputAttributeDefinition ref="eduPersonAffiliation" />
    <DisplayName xml:lang="de">Berechtigungen</DisplayName>
    <DisplayName xml:lang="en">Entitlements</DisplayName>
    <ValueMap>
        <ReturnValue>urn:mace:dir:entitlement:common-lib-terms</ReturnValue>
        <SourceValue>member</SourceValue>
        <SourceValue>library-walk-in</SourceValue>
    </ValueMap>
    <ValueMap>
        <ReturnValue>urn:mace:terena.org:tcs:personal-user</ReturnValue>
        <SourceValue>faculty</SourceValue>
    </ValueMap><ValueMap>
      <AttributeEncoder xsi:type="SAML1String" name="urn:mace:dir:attribute-def:eduPersonEntitlement" encodeType="false" />
 <ReturnValue>urn:mace:terena.org:tcs:personal-user</ReturnValue>
       <AttributeEncoder xsi:type="SAML2String" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.7" friendlyName="eduPersonEntitlement" encodeType="false" /> <SourceValue>faculty</SourceValue>
    </ValueMap>
</AttributeDefinition>

You can have several SourceValue elements in a ValueMap, e.g. to additionally allow everyone with affiliation student to get a personal certificate as well. See the examples above (eduPersonScopedAffiliation) or the Shibboleth wiki for details.

...

schacHomeOrganization

schacHomeOrganization is sometimes needed by services, usually as an IDP- and entityID-independent identifier for an organization, e.g. to map subjects from an IDP to a contract in the name of the organisation that runs the IDP (without having to hard-code the IDP's entityID into some configurationn file or database). The following will work for anyone, based on the data connector provided below (that's also generic, thanks to its use of Java properties):

...

<DataConnector id="myLDAP" xsi:type="LDAPDirectory"
    ldapURL="%{idp.attribute.resolver.LDAP.ldapURL}"
    baseDN="%{idp.attribute.resolver.LDAP.baseDN}" 
    principal="%{idp.attribute.resolver.LDAP.bindDN}"
    principalCredential="%{idp.attribute.resolver.LDAP.bindDNCredential}"
    useStartTLS="%{idp.attribute.resolver.LDAP.useStartTLS:true}"
    connectTimeout="%{idp.attribute.resolver.LDAP.connectTimeout}"
    trustFile="%{idp.attribute.resolver.LDAP.trustCertificates}"
    responseTimeout="%{idp.attribute.resolver.LDAP.responseTimeout}"
    connectionStrategy="%{idp.attribute.resolver.LDAP.connectionStrategy}"
    noResultIsError="true"
    multipleResultsIsError="true"
    excludeResolutionPhases="c14n/attribute">
    <FilterTemplate>
        <![CDATA[
            %{idp.attribute.resolver.LDAP.searchFilter}
        ]]>
    </FilterTemplate>
    <ConnectionPool
        minPoolSize="%{idp.pool.LDAP.minSize:3}"
        maxPoolSize="%{idp.pool.LDAP.maxSize:10}"
        blockWaitTime="%{idp.pool.LDAP.blockWaitTime:PT3S}"
        validatePeriodically="%{idp.pool.LDAP.validatePeriodically:true}"
        validateTimerPeriod="%{idp.pool.LDAP.validatePeriod:PT5M}"
        expirationTimevalidateDN="%{idp.pool.LDAP.idleTimevalidateDN:PT10M}"
        failFastInitializevalidateFilter="%{idp.pool.LDAP.failFastInitialize:false}" validateFilter:(objectClass=*)}"
        expirationTime="%{idp.pool.LDAP.idleTime:PT10M}"/>
</DataConnector>

If you're done with editing activate the changes by restarting Tomcat – assuming you've changed some Java property files (such as saml-nameid.properties) which are only read on startup of the JVM:

...