Customizing the Username/Password Login Page
Finding, Updating, and Deploying the Login Page
The login page is a JavaServer Pages (JSP) and before attempting to edit the page you should be familiar with at least to basics of JSPs. Go out to the web and read a few tutorials (e.g. one, two, three).
To make changes to the login page and deploy them:
- Edit src/main/webapp/login.jsp within your IdP distribution package
- Run the IdP install script
- Restart your Servlet container
While nearly everything on the login page can be customized a few pieces must always be there:
- The form element with an action element value of
j_usernameinput field must be used for the username.
j_passwordinput field must be used for the user's password.
These elements can be moved around in the page, but the input fields must be located within the form.
As of IdP release 2.1.3 information regarding the current login process is more easily available. This information can be gotten through the use of the HttpServletHelper.
Almost all of the
HttpServletHelper methods require a
ServletContext as a parameter. This is available as the standard JSP variable
The most useful object available via this Helper is the LoginContext and its SAML protocol specific subclasses ShibbolethSSOLoginContext (if it's a SAML 1 request) or a SAML2LoginContext (if it's a SAML 2 request).
The login context will give you access to information such as the entity ID of the relying party (the service provider), the requested authentication methods, the authentication method the IdP is attempting to perform, whether the authentication is a forced and/or passive authentication, etc.
So, to get the
LoginContext you would do the following:
You could then use the
LoginContext like this:
Relying Party Metadata
Another useful set of information is the EntityDescriptor metadata for the relying party. This can include information such as human readable names and descriptions, informational URLs, etc. To get to the metadata for the relying party you would do the following:
Handling Login Errors
One significant drawback to the use of JAAS as the authentication provider within the IdP is that it does not bubble up very useful authentication errors. It simply indicates whether the authentication failed or succeeded. You can determine if an authentication attempt failed by checking that the request attribute
LoginHandler.AUTHENTICATION_EXCEPTION_KEY is not null.
Direct Login Page Access
Another common error comes from the misuse of the IdP. The login page can not be accessed directly, it can only be accessed after the IdP has done some initial processing of a valid authentication request. However, some users will mistakenly access the login page because they bookmarked it, found it in their browser's history, or by means of the back button. The best way to detect this is to look for the presence of the
LoginContext and, if not available, display an appropriate error message.
Preventing Display Of Login Page in a Frame
X-FRAME-OPTIONS header. This header can be set as follows (make sure you insert it as the very first line):