VelocityVariables

Nearly all interaction with the user agent (usually the browser, sometimes a program on the command line) is rendered via the Velocity template engine. This allows significant customizing of the output based on various properties that the IdP (and the Spring framework) make available. Prior to rendering browser pages with Velocity, the IdP makes several Velocity context variables available. Some are available in many views, while some are specific to an individual view (for instance login or attribute release consent).

In addition the Spring framework provides the deployer with the option to use macros. This is described here. Probably the most useful macro is #springMessageText(token,'default value'), which looks up the appropriate (language specific) message property (in files in the messages directory) and returns that value or the default.

Examples of using variables and message properties can be found in the distributed templates (in the views directory).

Available variables are listed below. Many are advanced and unlikely to be needed by most deployers.

1 Variables Available in All Templates
2 Variables Available to Password Login View
3 Variables Available During Attribute Release Consent
4 Variables Available During Logout
5 Variables Available in Other Circumstances
- 5.1 Terms of Use
6 Examples
- 6.1 Locating the OpenSAML EntityDescriptor for the Relying Party
- 6.2 Show a particular HTML Element depending on the requesting SP's EntityId

Variables Available in All Templates

Property	Description

Property	Description
encoder	An HTMLEncoder object (javadoc here). This allows safe HTML encoding of various types. This is further described here.
profileRequestContext	A ProfileRequestContext (javadoc here). This is primarily used to locate subsidiary contexts: `#set ($rpContext = $profileRequestContext.getSubcontext('net.shibboleth.idp.profile.context.RelyingPartyContext'))` This is an advanced topic and out of scope for this page.
environment	The Spring Environment (javadoc here). This will be most frequently used to resolve properties (defined in idp.properties or other files), by calling the getProperty method. For instance `environment.getProperty("idp.whatever","default")`
custom	The Spring bean with id "`shibboleth.CustomViewContext`". This can be whatever you define it to be (in `global.xml`)
request	The HttpServletRequest (javadoc here). This is an advanced topic and out of scope for this page.
response	The HttpServletResponse (javadoc here). This is an advanced topic and out of scope for this page.
flowRequestContext	The Spring Web Flow RequestContext (javadoc here). This is an advanced topic and out of scope for this page.
springMacroRequestContext	A help context supplied by Spring. Primarily used to render language specific resources from the message bundles. For instance `$springMacroRequestContext.getMessage("idp.message", "An unidentified error occurred."))`

During password login, the templates login.vm and login-error.vm are used and have access to additional variables:

Property	Description

Property	Description
rpUIContext	A RelyingPartyUIContext object. This object allows language sensitive rendering of specific information about the relying party (logos and so forth). This is described further here.
authenticationContext	An AuthenticationContext object. This object contains a large amount of information about the state of the authentication process.
authenticationErrorContext	An AuthenticationErrorContext object. When present (which is only after a previous login error), this provides more detailed information on the failure which can then be displayed. The default views/login-error.vm file demonstrates how the contents of this context can be used to drive language specific message lookup (as in messages/authn-messages.properties).
authenticationWarningContext	An AuthenticationWarningContext object. This isn't typically used within this view, but if warnings about account state are detected at the same time an error is also detected, it may be available.
ldapResponseContext	An LDAPResponseContext object. This isn't typically used within this view, but if warnings about account state are detected at the same time an error is also detected, it may be available.
extendedAuthenticationFlows	Collection of AuthenticationFlowDescriptor objects configured as "extended" flows callable by the login form.

Property	Description

Property	Description
rpUIContext	A RelyingPartyUIContext object. This object allows language sensitive rendering of specific information about the relying party (logos and so forth). This is described further here.
attributeDisplayNameFunction	A class (javadoc here) with one method 'apply'. This takes an IdPAttribute (usually from $attributeReleaseContext.getConsentableAttributes().values()) and outputs the DisplayName appropriate to the browser locales.
attributeDisplayDescriptionFunction	A class (javadoc here) with one method 'apply'. This takes an IdPAttribute (usually from $attributeReleaseContext.getConsentableAttributes().values()) and outputs the DisplayDescription appropriate to the browser locales.
consentContext	A ConsentContext (javadoc here). A context representing the state of a consent flow (current and previous consents). Further information TBD.
attributeReleaseContext	An AttributeReleaseContext (javadoc here). This can be used to provide an iterable group of those attributes to which consent can be applied via the call `$attributeReleaseContext.getConsentableAttributes().values().` Specific attributes can be found by direct lookup `$attributeReleaseContext.getConsentableAttributes().get($attributeId)`. In Java terms, `$attributeReleaseContext.getConsentableAttributes()` is a Map.

Variables Available During Logout

Property	Description

Property	Description
logoutContext	A LogoutContext (javadoc here). This contains information to list the services accessed during the session that has been terminated
multi-rpContext	A MultiRelyingPartyContext (javadoc here). This allows lookup of the RelyingPartyContext (javadoc here) for each service listed in the logoutContext

Typically the RelyingPartyContext is further interrogated to get individual rpUIContexts.

#foreach ($sp in $logoutContext.getSessionMap().keySet())
  #set ($rpCtx = $multiRPContext.getRelyingPartyContextById($sp))
  #if ($rpCtx)
    #set ($rpUIContext = $rpCtx.getSubcontext("net.shibboleth.idp.ui.context.RelyingPartyUIContext"))
  #end
  #if ($rpUIContext) 
    ## Do stuff with rpuicontext - just like the login page
  #end
#end

Variables Available in Other Circumstances

Terms of Use

During terms of use consent the intercept/terms-of-use.vm view template has two properties available :

rpUIContext as used in the login case
termsOfUseId. A ConsentContext (javadoc here). A context representing the state of a consent flow (current and previous consents). Further information TBD.

Examples

Locating the OpenSAML EntityDescriptor for the Relying Party

The EntityDescriptor (Javadoc here) is located in the MetadataContext. Finding this requires some navigation:

#set ($outboundContext = $profileRequestContext.getOutboundMessageContext())
#set ($samlPeerContext = $outboundContext.getSubcontext('org.opensaml.saml.common.messaging.context.SAMLPeerEntityContext'))
#set ($metadataContext = $samlPeerContext.getSubcontext('org.opensaml.saml.common.messaging.context.SAMLMetadataContext'))
#set ($spEntity = $metadataContext.getEntityDescriptor())

Show a particular HTML Element depending on the requesting SP's EntityId

#set ($spEntityId = $profileRequestContext.getSubcontext('net.shibboleth.idp.profile.context.RelyingPartyContext').getRelyingPartyId())
...
 #if ($spEntityId.equals("https://sp.examle.org/shibboleth"))
	<a>particular HTML element</a>
 #end