Content Comparison

...

The file starts with DataConnectors. A typical connector identifies a database or LDAP directory as a source, and a query (in SQL or LDAP query language) to present to the source. Currently Shibboleth pulls data from Oracle instances (ACS, IST, IDM, HOP), the IDR SQL Server database, the Public LDAP Directory, and the Windows AD LDAP directory.

...

• A database query can return exactly one row. Then you can think of the row as a user object, and the column names become the properties of the object.
• A database query can return more than one row but only one column. Then you have a "multivalued" property for one user.
• An LDAP query returns the User object from the directory. LDAP User objects have properties some of which are single valued and some of which are multivalued.

Subsequent configuration elements define one or more attributes based on the results of the queries. They specify the name of the query and the name of the database column or LDAP object property from which the value or values are obtained.A query creates an attribute object for each database result set column or each property of the LDAP user object returned. These attribute objects are not directly useful because they are attached to the object created to represent the query result. You use them to create derived attribute objects that can stand on their own. To do this you configure an AttributeDefinition element with a sourceAttributeID that names the column/property and a Dependency that references the id of the query.

<resolver:AttributeDefinition id="idrFirstName" xsi:type="ad:Simple" sourceAttributeID="FirstName">
    <resolver:Dependency ref="IDRQuery" />
</resolver:AttributeDefinition>

This element creates a new attribute with an id of "idrFirstName" that is the value of the FirstName column of single row returned by the IDRQuery database query (defined elsewhere in the file). In this definition you had to give both the sourceAttributeID and the Dependency.

In most cases an AttributeDefinition will also have one or more AttributeEncoder elements that tell Shibboleth how to produce SAML representing this attribute when it is sent to a Service Provider. Typically the element specifies a FriendlyName like "FirstName" or "GivenName" and an (unfriendly) name like "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" or "urn:oid:2.5.4.42". However, in a few cases the AttributeDefinition will appear just as in the box above. Without an Encoder it cannot be used to generate SAML, but it serves a different purpose to fix a bug in the Shibboleth configuration schema.

Previously defined attributes can be used to define secondary attributes. This can occur when you define an Attribute with a block of JavaScript code, or if you need to plug the attribute into a subsequent query or insert it into a string.

So here is the problem. An AttributeDefinition can have any number of Dependency statements, but only one can meaningfully reference a DataConnector (that is a Query). For that one Dependency, the sourceAttributeID on the AttributeDefinition selects one column or property and makes that variable available as a pre-defined JavaScript variable with the sourceAttributeID= name. Every other Dependency has to reference an AttributeDefinition instead of a DataConnector. Each of those other Dependencies creates a pre-defined JavaScript variable with the ref= name on the Dependency statement (which is the id= of the referenced AttributeDefinition. If an AttributeDefinition had two different DataConnectors referenced by two Dependency elements, then Shibboleth would not know which Query contained the sourceAttributeID column, and if both queries had the sourceAttributeID as a column name it could not create two JavaScript variables with the same name. So using a separate AttributeDefinition like the one in the box above creates an unambiguous statement. A Dependency with a ref="idrFirstName" creates a JavaScript variable named "idrFirstName" that has the value of the "FirstName" column returned by the result set of the "IDRQuery" DataConnector. Any other first names from any other queries can be similarly give unique identifiers.

Note: Oracle queries return column names that are all UPPERCASE. It is a best practice to use uppercase names in the query and in all subsequent references to the column. If you specify an Oracle column name in lower or mixed case in subsequent XML, then the Java code will fail to match the UPPERCASE name in the Oracle result set and a null or missing value will be returned.

...