Seitenhistorie

The Shibboleth IDP's Attribute Resolver collects data from authoritative sources (systems of record) and transforms and encodes the data as needed, before it is passed on to the attribute filter.

All parts of the resolver are always executed in a default configuration, even though much of the data gathered may be discarded later on in the attribute release/filtering stage. Because of this all configured data sources (such as LDAP Direcory Services or Relational Database Systems) should be highly available (and contain up-to-date, correct data, of course) – at least as highly available as you expect your IDP deployment to be. With LDAP directory servers achieving redundancy and replication usually is a much simpler (and cheaper) task than with RDBMSs, so sometimes it 's may be worth the extra effort of synchronising data from other sources (e.g. your HR and/or Student Information Systems) into an LDAP directory Directory Service first and only pointing the IDP to these LDAP data sources. But all of this depends on local Identity Management decisions and processes and no one recipe will fit all. Feel free to discuss pros and cons of approaches and tools on the eduID.at community mailing list.

We'll essentially replace the default /opt/shibboleth-idp/conf/attribute-resolver.xml content with our own definitions below, though keeping all the attribute ids that are now standardised (via the IDP's Attribute Registry feature, more on that below). Backup copies of all configuration files can always be found in /opt/shibboleth-idp/dist/conf/ for comparison and as source for copying/pasting of more/other definitions.

The attribute resolver contains two kinds of configuration items: DataConnectors, which supply input gather data from data sources (such as the LDAP or Database servers, as described above, ) and AttributeDefintions, which transform the individual data elements (e.g. name, email address) retrieved from those DataConnectors.  For the proper on-the-wire representation as SAML attributes (or for other protocols) the IDP comes with a default set of transcoding rules referenced in /opt/shibboleth-idp/conf/attributes/default-rules.xml. (Deployers of earlier versions of the software will notice how short and clean AttributeDefinitions can be, and the "missing" DisplayName and AttributeEncoder elements can all be found in the referenced transcoding rules, e.g. conf/attributes/inetOrgPerson.xml, conf/attributes/eduPerson.xml and so on.

...

Below are examples for all of the attributes commonly used in (inter-)federation today. As such all eduID.at IDPs should at least be able to create all of those attributes, but their specific definitions may vary from organisation to organisation, due to local Identity Management and software choices. For more details on the syntax and semantics of this part of the IDP configuration configuration consult the relevant upstream documentation.

...

If you have created additional 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 – software – please share them! Contributions to this wiki are very much welcome. You can also just just send them to the eduID.at Operations Team, of course, and we will edit and include them here.

...

Many SAML Service Providers will need the subject's real name in one form or another, e.g. to allow collaboration between subjects based on trusted, verified names. Some applications will only be able to use names sent in separate fields (first name, last name) and some are content with a unified field that contains the full name in a format chosen by the institution or the subject herself. So for interoperability every IDP will need to eduID.at IDP should be able to provide both forms. Assuming you have the subject's name available in an LDAP directory and configured a DataConnector for that (see further below), these are simple examples to use:

...

displayName

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

<AttributeDefinition id="displayName" xsi:type="Simple">
    <InputDataConnector ref="myLDAP" attributeNames="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 attributes (configured as per above) dynamically within the Shibboleth IDP:

...

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 it previouslyrepeatedly over time. That's what subjects most people expect themselfs, of course, otherwise all their work/data created or stored at a service would be unavailable to them the next time they accessed the same service again! See also this 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 the identifiers shown in this documentation, in order to be able to interoperate with – and make use of – all SAML Services Providers your community's members may need to own members 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 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 directoryemail attribute.

<AttributeDefinition id="mail" xsi:type="Simple">
    <InputDataConnector ref="myLDAP" attributeNames="mail" />
</AttributeDefinition>

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.

...

eduPersonPrincipalName is commonly produced either from the local login name (uid, sAMAccountName) or by re-using the institutional email address as its value. Our documentation for that attribute explains the pros and cons of each approach in detailboth approaches. Below you'll find examples for the both main methods used to create that attribute.

First, the variant based on login name (replace replace sourceAttributeID="uid" with sourceAttributeID="sAMAccountName" or whatever holds local login names in your LDAP directory):

...

...

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 aforementioned config file and it will also be used re-use it as the basis for the SubjectID attribute. The configuration below also re-uses the 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:

...

If you do not have such an identifier readily available but you can fabricate one based on other/more data that would be an alternative approach. For example, if login names may be reassigned at your organisation – meaning you cannot base SubjectID solely on login names, salted/hashed or not – you could concatenate the login name with something else that's not going to be the same in the re-assigned account to create account, creating an interim attribute within the IDP that then becomes the basis for other attributes and NameIDsand NameIDs:

For example, if accounts get a new account creation date after re-activation (i.e., when you first delete and then later re-create accounts) you should also be able to use a combination of of loginname+accountcreationdate or something along those lines, which would then still be unique even if the same login name would later be reused in a new account for another – or even for the same, which may be an unintended but still acceptable side-effect – person. So first you'd pull the data to combine into an interim attribute defintion, e.g.:

...

Then you put this attribute's id into your saml-nameid.properties configuration file so that this property can then be used in the rest of the configuration (same way for everyone, independently of the specifics):

idp.persistentId.sourceAttribute = subjectIdBasis

Finally, you'd have to change only one line from the above example of creating SubjectIDs, replacing the InputDataConnector on the "subjectHash" attribute definition with the following InputAttributeDefinition:

...

...

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

...

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

...

European Student Identifier

...

Since the ESI won't be available in the exact format required by the ESI specification we'll provide examples that dynamically generate the ESI based on the uid attribute (coming from the id="myLDAP" DataConnector). In this example the uid attribute is expected to have values of the form "x<MATRIKELNR>" where <MATRIKELNR> is the student's Austrian immatriculation number so that we can extract a useable form of the immatriculation number from the uid attribute using regular expressions. Any other values not matching the given pattern will lead to an empty ESI attribute which will ultimetely not be released by the IDP:

...

In case you have the immatriculation number available in its own attribute already (i.e., no regular expression matching is needed to extract it from other data; below we'll assume use of the a ficticious matrikelnummer attribute belowlooked up from LDAP) you could use a "Template" attribute definition instead of the "Mapped" one above:

...

Finally, institutions that do not manage immatriculation numbers for their students but that still do need to provide the ESI attribute can use the following example to dynamically generate ESI values from any other locally available identifier (below again assuming use of the the uid attribute), combining it with the canonical DNS Domain of the institution (cf. the Attribute-"scope") of the institutionScope" for all eduID.at IDPs):

<AttributeDefinition id="schacPersonalUniqueCode" xsi:type="Template">
    <InputDataConnector ref="myLDAP" attributeNames="uid" />
    <DisplayName xml:lang="de">Europäische Studierendenkennung (ESI)</DisplayName>
    <DisplayName xml:lang="en">European Student Identifier (ESI)</DisplayName>
    <Template>urn:schac:personalUniqueCode:int:esi:%{idp.scope}:${uid}</Template>
    <AttributeEncoder xsi:type="SAML2String" name="urn:oid:1.3.6.1.4.1.25178.1.2.14" friendlyName="schacPersonalUniqueCode" encodeType="false" />
</AttributeDefinition>

...

eduPersonScopedAffiliation

The eduPersonScopedAffiliation attribute is sometimes used for very simple authorisation cases. : eduPersonAffiliation describes a person's relationship with the IDP's organisation in general terms (from a controlled vocabulary of 8 allowed values) , and eduPersonScopedAffiliation is simply the scoped variant of that (i.e., the applicable affiliation values each suffixed with "@" + the main institutional DNS domain, same as for eduPersonPrincipalName or samlSubjectID).
N.B.: Only the scoped version should ever be used for federated use cases: Even if a recieving Service Provider did not need to differentiate between e.g. faculty@example.edu and faculty@researchfaculty@math.example.com it can always easily throw away the scope with minimal processing, yielding the unscoped version (here: "faculty" in both cases). The reverse process (deriving eduPersonScopedAffiliation values from eduPersonAffiliation values) is of course impossible.

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 remains the same for everyone, no matter how the (unscoped) affiliation values was created.

...

...

Another use-case relevant to the 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).

...

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):

...