Add content to the Velocity templates used for POST web page returned to user's browser after authentication (the web page that contains the auto-submit to the appropriate SP endpoint)

Starting with version 2.4.0 of the IdP, there is an easier way to add content to the default Velocity templates that generate the POST response web page that is returned to the user's browser, and then auto-submitted to the appropriate SP endpoint. One has always been able to override those Velocity templates altogether, and create your own templates, if you know what you are doing. But this new feature for the IdP makes it much easier to make particular kinds of additions to those pages without needing to completely override the default pages.

A couple of examples of things you could do with this would be to add Javascript to invoke Google Analytics to record stats about logins, or to add a message to the page in case network delays cause this page to be displayed to the user long enough that the user wonders what is happening next.

The particular bindings impacted by this are the SAML1 and SAML2 POST bindings, and the SAML2 Artifact and SimpleSign bindings.

The two additions you can make to the default Velocity template are to add HTML markup (actually, Velocity Template Language, which can be a mix of standard HTML markup and Velocity statements) to the Head section of that web page, and/or to add HTML(VTL) markup to the Body section of that web page. You do that by creating one or both of the following files:

• add-html-head-content.vm
• add-html-body-content.vm
  

Those files then need to be added to the IdP's distribution directory, placed into the:

• src/main/webapp/WEB-INF/classes/templates/

directory (you'll need to create one or two of those last subdirectories.) And then you need to "re-install" the IdP again, just making sure (of course) not to overwrite the existing configuration files (if any).

Examples

Using "add-html-head-content.vm"

 One reason you might want to add additional content to the Head section of the POST response page would be if you wanted to use something like Google Analytics (GA) to generate statistics about the usage of your Identity Provider, GA can provide the ability to generate useful statistics of how many logins are processed by your IdP, by SP etc. (Just keep in mind that GA will write out various cookies to the user's browser, and you probably want to read up about those cookies, how they are used, and what the default lifetime is for each. By including the appropriate directives, you can control the lifetime and usage of those cookies, at least to some extent.)

Here is sample content you could have for the "add-html-head-content.vm" file that would send info to GA every time your IdP POSTed a response to the user's browser:

##
## Velocity Template for sending information to Google Analytics
##
<script type="text/javascript">
 function htmlDecode(input){
   var e = document.createElement('div');
   e.innerHTML = input;
   return e.childNodes.length === 0 ? "" : e.childNodes[0].nodeValue;
 }


 var _gaq = _gaq || [];
 _gaq.push(['_setAccount', 'UA-your_key_here']);
 _gaq.push(['_trackPageview']);
## Cookie session timeout in milliseconds
 _gaq.push(['_setSessionCookieTimeout', 120000]);
 var decodedaction =  htmlDecode('${action}');
## Get the SAML Binding type
 
 _gaq.push(['_trackEvent', 'SSOpage', '${SAMLBinding}', decodedaction]);


 (function() {
   var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
   ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
   var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
 })();


</script>

Using "add-html-body-content.vm"

Here is a very simple example of sample content you could have for the "add-html-body-content.vm" file that would display a particular message to the user, which you might want to do in case network delays cause this page to be displayed to the user long enough that the user wonders what is happening next. Normally, this page is "auto-submitted" quickly enough that the user never really sees it. But if that doesn't happen, you may decide to craft a message to display to the user.

##
## Velocity Template for adding a message to the BODY of the response page
##


<strong> This form will autopost if you have JavaScript on,
         but sometimes there can be slight delay. </strong>

An example Velocity template into which the above is being inserted

The standard Velocity templates for these POST web pages are found in OpenSAML. (You could find them if you unpacked the OpenSAML jar.) The templates impacted by these "add head" and "add body" files were listed above. The following is the contents (from the OpenSAML jar included with Shib IdP 2.4) of the "saml2-post-binding.vm" Velocity template, which is, of course, the template used when sending a response to an SP's SAML2 POST endpoint. This provides the context for where the "add-html-head-content.vm" and "add-html-body-content.vm" is being inserted in the overall web page.

##
## Velocity Template for SAML 2 HTTP-POST binding
##
## Velocity context may contain the following properties
## action - String - the action URL for the form
## binding - String - the SAML binding type in use
## RelayState - String - the relay state for the message
## SAMLRequest - String - the Base64 encoded SAML Request
## SAMLResponse - String - the Base64 encoded SAML Response


<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
    <head>
    #parse ( "/templates/add-html-head-content.vm" )
    </head>
    <body onload="document.forms[0].submit()">
        <noscript>
            <p>
                <strong>Note:</strong> Since your browser does not support JavaScript,
                you must press the Continue button once to proceed.
            </p>
        </noscript>
        
        <form action="${action}" method="post">
            <div>
                #if($RelayState)<input type="hidden" name="RelayState" value="${RelayState}"/>#end
                
                #if($SAMLRequest)<input type="hidden" name="SAMLRequest" value="${SAMLRequest}"/>#end
                
                #if($SAMLResponse)<input type="hidden" name="SAMLResponse" value="${SAMLResponse}"/>#end
                
            </div>
            <noscript>
                <div>
                    <input type="submit" value="Continue"/>
                </div>
            </noscript>
        </form>
        #parse ( "/templates/add-html-body-content.vm" )
    </body>
</html>