Page History
...
The attribute resolver contains two kinds of configuration items: DataConnector
s, which supply input data from data sources as the LDAP or Database servers described above, and AttributeDefintion
s, 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.)
...
title | Preparation for missing SCHAC transcoding rules |
---|
Since IDPv4 currently does not come with transcoding rules for SCHAC Attributes we're adding those from a configuration snipped curated by our friends at DFN:
Download the referenced XML file to /opt/shibboleth-idp/conf/attributes/schac.xml
:
No Format |
---|
curl -sSo /opt/shibboleth-idp/conf/attributes/schac.xml https://download.aai.dfn.de/schema/dfnMisc.xml |
and then add an import for it to /opt/shibboleth-idp/conf/attributes/default-rules.xml
, after the other import elements:
Code Block | ||
---|---|---|
| ||
<import resource="schac.xml" /> |
...
Table of Contents | ||
---|---|---|
|
...
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 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 be able to provide both forms. Assuming you have the subject's name availabe available in an LDAP directory and configured a DataConnector for that (see further below), these are simple examples to use:
...
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 it previously. That's what subjects expect themselfs, of course, otherwise all their work/data stored at a service 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.
Info |
---|
There are a few types of identifier attributes in use within the federation community, each with their own unique properties, advantages and disadvantages. These are all explained in the Attributes section (or rather its child pages), for each attribute. So go read (and possibly re-read) those, as you will need to understand their definition and usage patterspatterns in order to be able to decide if/how you can support them in your IDP. As always: Discuss with the community if anything is unclear! |
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's members may need to work with.
...
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 the 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 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):
...
Note |
---|
Only do this if you are certain that all email address values for all subjects from your instituition are within (one of) your own institutional email domain(s). The eduPersonPrincipalName is filtered at SAML Service Providers to only allow domain values that have been whitelisted allowed per each SAML Identity Provider, cf. the "attribute scope" column in the catalog of eduID.at Identity Providers. If needed you can ask the eduID.at operations team to whitelist allow more of your domains in your IDP's SAML Metadata, to match the email domains in use within your LDAP email attributes. But you cannot use email addresses as base for eduPersonPrincipalName attribute values if you populate external (arbitrary) email addresses in the referenced LDAP attribute. |
...
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 aforementioned config file , and it will also be used as the basis for the SubjectID attributeSubjectID 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:
Code Block | ||||
---|---|---|---|---|
| ||||
<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="samlSubjectID" xsi:type="Scoped" scope="%{idp.scope}"> <InputAttributeDefinition ref="subjectHash" /> </AttributeDefinition> |
If you do not have one 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 that's not going to be the same in the re-assigned account to create an interim attribute within the IDP that then becomes the basis for other attributes and 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 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– person. So first you'd pull the data to combine into the an interim attribute defintion, e.g.:
...
This references a DataConnector with id="computed" which you'll create using the next snippet (move it to the end of the attribute-resolver.xml file together with so it ends up next to the other data connectorsDataConnector elements). Provided Provided you already have a stable, non-recycled (not reassigned from one subject to another) identifier for your subjects stored in LDAP you can set that attribute name in the the idp.persistentId.sourceAttribute
property of the referenced config file and it will also be used as the basis for the PairwiseID 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) PairwiseID attribute value:
...
Note |
---|
This simple configuration generates Using a more complex configuration with StoredID instead of ComputedID data connectors and a StorageService it is possible to override or map chosen input attributes to previously generated output attributes. That would allow to keep the generated and released identifiers ( |
European Student Identifier
...
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 samlSubjectID). Only the scoped version should be used for federated use cases: Even if a recieving Service Provider did not want need to differentiate between e.g. faculty@example.edu
and faculty@research.example.com
it can always easily throw away the scope with minimal processing, yielding the unscoped version (here: "faculty
" 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 remains 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 recommended such practices exist so you might as well make use of them if it makes your IDP configuration easier. Note that identical 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.
Code Block | ||||
---|---|---|---|---|
| ||||
<AttributeDefinition id="eduPersonAffiliation" xsi:type="Mapped" dependencyOnly="true"> <InputDataConnector ref="myLDAP" attributeNames="uid" /> <ValueMap> <ReturnValue>student</ReturnValue> <SourceValue>m.+</SourceValue> </ValueMap> <ValueMap> <ReturnValue>staff</ReturnValue> <SourceValue>p.+</SourceValue> </ValueMap> <ValueMap> <ReturnValue>member</ReturnValue> <SourceValue>m.+</SourceValue> <SourceValue>p.+</SourceValue> </ValueMap> </AttributeDefinition> |
Now hereHere's another example where the correct affiliations are derived from the name of a locally defined group attribute (phoUsergroup
in the example below). This example uses partial string matches for the individual affiliations, and a regex that makes all subjects with any group value (at least, or also) a member
:
...
Tip | ||
---|---|---|
There are of course many more ways this could be done, depending on local data available and LDAP deployment decisions (e.g. group implementation). The wiki for the old Shibboleth IDP v2.x software has more and more complex examples, including one to recursively map affiliations from nested groups within Microsoft "Active Directory" deployments.
|
Finally, it's time to turn the (unscoped) eduPersonAffiliation values created by one of the methods above into a properly scoped one:
Code Block | ||
---|---|---|
| ||
<AttributeDefinition id="eduPersonScopedAffiliation" xsi:type="Scoped" scope="%{idp.scope}"> <InputAttributeDefinition ref="eduPersonAffiliation" /> </AttributeDefinition> |
...
eduPersonEntitlement is a container for all kinds of values and data, usually only with clearly defined values within closed specific communities. One notable exception is its global use for location-independent, off-campus authorisation to Library Services. Here's a simple example that should work for most deployments, giving all subjects you have declared to have an eduPersonAffilliation
of member
earlier (see above) or of library-walk-in
(someone physically present in library premises) the common-lib-terms
entitlement, thereby stating that these all are entitled to access licensed resources on behalf of your organisation, according to the "common library licensing terms" (again, see Library Services for details):
...
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).
...
Tip |
---|
If you're supporting use of your Shibboleth IDP to access USI Wien services check out another variant to create |
schacHomeOrganization
...
And finally here's a verbatim copy of the default example of an LDAP DataConnector (taken from the file attribute-resolver-ldap.xml
). All the parameters and values in this DataConnector come from the conf/ldap.properties
file in the IDP's conf directoryor from credentials/secrets.properties
, so nothing needs to be set/changed here – with below – with the exception of possibly removing some removing some of the XML attributes. : E.g. for LDAP directory server deployments deployments without any transport-layer security (no TLS and no SSL) you'd need to remove the trustFile
XML-attribute (i.e., the whole line starting with trustFile
), the . The rest should still work for everyone, based on the (correct, or default) settings in ldap.properties
:
...