The first user interface layer of the flow is actually HTTP Basic authentication; if a header with credentials is supplied, the credentials are tested immediately with no prompting. If that step fails, or no credentials are supplied, then a view is rendered unless the request is for passive authentication or part of a non-browser profile. Views are handled by Spring Web Flow, so support various technologies, but Velocity and JSP are supported by default and the examples are all based on Velocity. | Warning |
|---|
Be aware that the default view templates and configuration of classified messages (see next later section on Errors and Warnings) results in a system that will report context-sensitive errors to the user, such as whether the password was invalid or the username was mis-entered. This is appropriate for most organizations to reduce help desk calls caused by simple user error, but some organizations keep usernames a secret and may wish to adjust the configuration to collapse all error reporting and avoid leaking information about whether usernames are valid or not. |
Example Velocity User InterfaceThe example Velocity templates views/login.vm and views/login-error.vm illustrate generally how to populate the form, and how to detect and respond to error conditions. Internationalization is performed through the use of Spring message properties (which can be overridden via the top-level messages folder). Information on Spring internationalization is near the end of this section of the Spring documentation. When rendering Velocity views, several variables are available to aid per-relying party customization. Spring form generation macros such as #springMessage and #springMessageText are available to Velocity templates. You can freely comment out or remove the "Do Not Cache" support of course, or use Javascript to automate it for certain address ranges. Advanced Error Handling ExampleThe error message classification feature allows error messages to be mapped into grouped "classes" of errors that can be used in the view to report the results of a failed login. The main value of this feature is in supporting chains of multiple validators because the system will accumulate all of the classified errors that occur so that a precedence of error types can be applied to decide what to report to the user. A working example of this: views/login-error.vm| Code Block |
|---|
| ## Velocity Template for login error message production, included by login.vm
##
## authenticationErrorContext - context containing error data, if available
##
#if ($authenticationErrorContext && $authenticationErrorContext.getClassifiedErrors().size() > 0 && $authenticationErrorContext.getClassifiedErrors().iterator().next() != "ReselectFlow")
## This handles errors that are classified by the message maps in the config.
#if ($authenticationErrorContext.getClassifiedErrors().contains("InvalidPassword"))
#set ($eventId = "InvalidPassword")
#elseif ($authenticationErrorContext.getClassifiedErrors().contains("AccountLocked"))
#set ($eventId = "AccountLocked")
#elseif ($authenticationErrorContext.getClassifiedErrors().contains("AccountDisabled"))
#set ($eventId = "AccountDisabled")
#elseif ($authenticationErrorContext.getClassifiedErrors().contains("ExpiredPassword"))
#set ($eventId = "ExpiredPassword")
#elseif ($authenticationErrorContext.getClassifiedErrors().contains("UnknownUsername"))
#set ($eventId = "UnknownUsername")
#end
#elseif ($authenticationErrorContext && $authenticationErrorContext.getExceptions().size() > 0)
## This handles login exceptions that are left unclassified.
#set ($loginException = $authenticationErrorContext.getExceptions().get(0))
#if ($loginException.getMessage())
#set ($message = "Login Failure: $loginException.getMessage()")
#else
#set ($message = "Unidentified error")
#end
#end
#if ($eventId || $message)
<div class="error notification">
#if ($eventId == "AccountLocked")
## your code here
#elseif ($eventId == "AccountDisabled")
## your code here
#elseif ($eventId == "ExpiredPassword")
## your code here
#elseif ($eventId == "InvalidPassword")
## your code here
#elseif ($eventId == "UnknownUsername")
## your code here
#elseif ($message)
## your code here
#end
</div>
#end |
JSP User InterfaceThe use of JSP is not advised, but is supported. To do so, views/login.vm must be removed or renamed and the IdP restarted, or it will take precedence. Views in JSP should be created in edit-webapp/WEB-INF/jsp (and the warfile should be recreated with bin/build.sh or bin/build.bat and the container restarted). The old V2 Taglibs are supported for JSP for now, but we have plans to deprecate them in the future. |