The Basics

There are many places within Shibboleth where information can most easily be constructed based on a template. Shibboleth uses the Velocity template engine in these cases. Velocity provides a template language that allows simple things to be expressed simply. However, it also provides more complex constructs ranging from if/else statements and loops all the way up to custom defined functions which allow users to develop very intelligent templates.

Attribute Resolver Templates

Many attribute resolver components, such as the relational database connector, the LDAP data connector, and the template attribute definition use templates to construct some portion of information. For each of these components the following information is available within the template:

The edu.internet2.middleware.shibboleth.common.profile.provider.SAMLProfileRequestContext as a template variable called requestContext.
The attributes provided by those data connectors and attribute definitions listed as dependencies for the plugin. These edu.internet2.middleware.shibboleth.common.attribute.BaseAttribute objects are registered under a template variable corresponding to their attribute ID. The value of these variables is always a java.util.List.

Example Template Using Principal

SELECT * FROM PEOPLE WHERE netid='${principal.get(0)}'

Example Template Using Attributes and Principal

SELECT
 id,
 #if (${eduPersonAffiliation.values.contains("student")}
 courseid
#end
FROM PEOPLE
#if (${eduPersonAffiliation.values.contains("student")}
LEFT JOIN COURSES ON people.id=courses.personid
#end
WHERE uid='${principal.get(0)}'

Variables passed in through dependencies used in your query may actually be collections and need special handling. As an example, if you use a static data connector to define a fixed value to be passed into your SQL, it is actually a collection of values. What this means is that a given a static data connector foo that defines a value students used in a query like this:

     SELECT * FROM PEOPLE WHERE userid = '$requestContext.principalName' and group = '$foo'

will result in a select statement to your database of:

     SELECT * FROM PEOPLE WHERE userid = 'george' and group = '[students]'

to get what you would expect, define the query as:

     SELECT * FROM PEOPLE WHERE userid = '$requestContext.principalName' and group = '$foo.get(0)'

and will result in a select statement to your database of:

     SELECT * FROM PEOPLE WHERE userid = 'george' and group = 'students'