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)
Version 2.4 and later
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.
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:
Those files then need to be added to the IdP's distribution directory, placed into the:
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).
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:
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.
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.