Adding links to the OpenIAM Login Screen

I recently came across a really useful, but undocumented feature of OpenIAM that allows you to add custom links to the OpenIAM Login screen. The main use-case for this would be to direct people to a support portal or contact page if they need help. In my example below, I've added a Home link that could take the user back to the company's website.

For this guide, I'm using OpenIAM 4.2.1.3 Enterprise Edition, however you should be able to follow along with other versions. I originally implemented this in 4.2.1.2, so does work in other versions. Adding a custom link is fairly simple and only takes a couple of steps. First we will update a groovy script, and secondly tell OpenIAM to use this script. Let's get started.

Add Links to Groovy Script

The first step is to add the additional links we want to show to a built-in groovy script. Let's start by loading up the Groovy Manager.

Login to your webconsole

Click on the Administration Menu

Click on Groovy Manager

Load the script /selfservice/CustomLoginPageDisplayHandler.groovy. This file should already exist, but if you cannot find it, don't worry. You can use my code to create it.

Update the script with the following content:

package selfservice

import org.apache.commons.logging.Log
import org.apache.commons.logging.LogFactory
import org.openiam.ui.login.DefaultLoginPageDisplayHandler
import org.openiam.ui.model.Hyperlink

class CustomLoginPageDisplayHandler extends DefaultLoginPageDisplayHandler {

  private static final Log log = LogFactory.getLog("CustomLoginPageDisplayHandler")

 	public CustomLoginPageDisplayHandler() {
		log.debug("CustomLoginPageDisplayHandler() called")
	}
	
	@Override
	public List<Hyperlink> getAdditionalHyperlinks() {
	    log.debug("getAdditionalHyperlinks() called")
	    Hyperlink homeLink = new Hyperlink()
	    homeLink.setHref('https://neilherbert.uk/')
	    homeLink.setText('Home')
	    log.debug(homeLink)
        return [homeLink] as List
	}
}

Let's explore what changes I've made. You'll notice that there are some additional imports, I like to include logging in my scripts. This makes it much easier to troubleshoot as you can see where the scripts have failed. I plan to write-up about logging with OpenIAM at some point soon.

The getAdditionalHyperlinks() method is responsible for providing the custom links for the login screen and must return a List of Hyperlink objects.

In my example I'm only adding one additional link. I'm creating a new Hyperlink object and using some setters setHref() to set the link and setText() to set the link text. Once that has been created I'm returning the new Hyperlink object as a list.

Once you've added your link(s), save the script, if the file doesn't already exist save it as /selfservice/CustomLoginPageDisplayHandler.groovy.

Change System Configuration

Now we've updated our groovy script, we need to tell OpenIAM to use this script.

Click on the Administration Menu.

Go to System Configuration.

Click on the UI tab.

Scroll all the way to the bottom of the UI tab page until you find Extra Links on Login page groovy handler.

Enter /selfservice/CustomLoginPageDisplayHandler.groovy into this field and press Save.

The page will scroll to the top and show a green success message saying that everything has been saved. If you get a red error saying Internal Error, try saving again until you see the green success message.

That's everything! It will take a couple of minutes before the login screen shows the additional links as the system configuration is cached and needs to be updated.