jespa.http

Class DuoHttpSecurityService

java.lang.Object

jespa.http.HttpSecurityService

jespa.http.DuoHttpSecurityService

Direct Known Subclasses:

DuoHttpSecurityFilter

public class DuoHttpSecurityService
extends HttpSecurityService

This class combines the SSO capability builtin to Windows clients joined to a Windows domain with the Duo 2FA functionality from duosecurity.com using the Duo Universal Prompt Java Client (duo_universal_java).

This class is fully re-entrant such that any number of DuoHttpSecurityService instances with different configurations can be created and used concurrently such as to differentially process requests of user-agents based on cookies, tokens, IP masks or similar.

Note: Even though this class has a doFilter method with the same signature as javax.servlet.Filter.doFilter, this class does not implement the Filter interface. The same method signature was used only to make it easy to implement a custom Filter if desired.

Requirements

If a SecurityProvider that implements Windows builtin SSO is used, a Windows Computer account must be created by an Administrator in Active Directory as described in the Installation section of the Jespa Operator's Manual. See the HttpSecurityService (HSS) documentation for details about all non-Duo specific functionality.

A Duo admin account on duosecurity.com must create a Web SDK application under Dashboard > Applications. The resulting Client ID, Client Secret and API hostname are supplied to this class as properties.

The following is an example of how Duo properties might appear in a properties file specified using the properties.path HSS property:

duo.clientId = DIRSJWINVALIDK72JSU2
duo.clientSecret = kSKf93kInValidPDfKNdI2lsLmVUiT90011sMCn
duo.api.host = api-1234abcd.duosecurity.com
duo.redirect.uri = https://apps1.busi.corp:8443/mctrl/duo-callback
duo.failmode = OPEN
duo.excludes = /api/v1/mctrl,/api/v1/bindings/*.sch

Example Duo Properties

Alternatively, these properties may be supplied as a simple Map to init(java.lang.String, javax.servlet.ServletContext, java.util.Map) (or using init() and then overriding some or all of those properties with properties from a file).

The fallback.location HSS property is required and should refer to a login form page that is also in the HSS excludes property list. See the HttpSecurityService API documentation and Jespa Operator's Manual for details.

The Jespa jar file, the duo_universal_java library jar file and the jar files the Duo client depends on must be added to the application lib directory (such as into WEB-INF/lib/). The duo_universal_java jar file and the jar files it depends on are most easily obtained using Maven.

Authentication Flow

When an end-user attempts to access any resource protected by the DuoHttpSecurityService, Windows built-in SSO will occur followed by the Duo second factor authentication as follows:

1. Windows Built-in SSO / Authentication
   1. If the end-user is logged into a Windows workstation or device with their Active Directory credentials, the user will be authenticated as they would using the regular HttpSecurityService (or HttpSecurityFilter). If the NtlmSecurityProvider is configured as the HSS security provider, and the user's browser is configured to perform SSO, the user should be transparently authenticated using the credentials used to log into their workstation / device for a completely password-free experience.
   2. if the end-user is not logged into their Active Directory domain or the browser is not configured to perform SSO , such as because the client OS is not Windows, the browser's builtin password dialog will prompt the user for credentials.
      1. If the end-user enters their correct Active Directory credentials, the Windows builtin authentication will occur as if SSO had occurred (such that NTLMSSP tokens are used and not plaintext).
      2. If the end-user cancels the browser's builtin password dialog, the end-user will be redirected to the location specified with the HSS fallback.location property. If the fallback.location is a conventional HTML form and HSS properties for explicit logins are supplied, the user may manually login by entering Active Directory credentials (although, as with any conventional HTML login form, passwords will exist in plaintext form on the server, albeit momentarily).
2. Duo Second Factor Authentication
   1. Only after the above described authentication has completed successfully, the user will be redirected to the Duo 2FA service by the Duo Universal Prompt Java Client (duo_universal_java).
   2. The user will perform whatever 2FA process is configured, such as selecting "Approve" on the Duo mobile app. If the user has not previously performed 2FA, they will be required to enroll which might include installing the Duo mobile app or performing some other initial procedure to complete the enrollment process.
      1. If 2FA is successful, the end-user will be redirected back to the application server with data sufficient to obtain a token. The token is stored in the users session to suppress further Duo 2FA. If the initial request of the end-user was a GET request, the DuoHttpSecurityService will redirect the end-user to that URL including any query string parameters. Otherwise, the user is redirected to the webapp context root.
      2. If 2FA is not successful, the user-agent will either be left at the Duo prompt with an error or redirected to the fallback.location.
   3. If an end-user requests a protected resource after the Duo token has expired, the token will be removed from the session and Duo 2FA will be re-initiated.

If an error occurs with Duo or Windows built-in SSO or other configured Jespa security provider, the Duo token and Jespa security provider state will be removed from the user's session and the user will be redirected to the fallback.location.

DuoHttpSecurityService Properties

Name	Description	Example
duo.clientId	The Client ID from the Web SDK application properties created in the Duo dashboard.	DIRSJWINVALIDK72JSU2
duo.clientSecret	The Client secret from the Web SDK application properties created in the Duo dashboard.	kSKf93kInValidPDfKNdI2lsLmVUiT90011sMCn
duo.api.host	The API hostname from the Web SDK application properties created in the Duo dashboard.	api-1234abcd.duosecurity.com
duo.redirect.uri	The URL that Duo should redirect user-agents back to after performing 2FA. This is just the URL to the webapp root of your application but it must be HTTPS and must end with "duo-callback".	https://apps1.busi.corp:8443/mctrl/duo-callback
duo.excludes	A comma separated list of DOS-style wildcard expressions for matching paths relative to the webapp base that should be excluded from Duo 2FA. This property may be used to effectively disable Duo for resources that are to be accessed by user-agents that cannot perform 2FA like service agents. Note: This property serves the same purpose as the HttpSecurityService excludes property but for Duo 2FA and not the first factor authentication performed by the HSS. The HSS excludes property is evaluated before this property. Duo will not be invoked if HSS authentication does not occur because an HSS excludes pattern matched the request path. Meaning it is not necessary to add expressions to duo.excludes if the paths they exclude are already excluded by HSS excludes.	/api/v1/mctrl,/api/v1/bindings/*.sch
duo.failmode	If set to "OPEN" and the Duo health-check step fails, such as because of a connectivity issue with Duo servers, user-agents will be permitted to access protected resources using only Windows builtin SSO and not Duo 2FA. The default value is "CLOSED" such that Duo 2FA is always required. If a fail-open condition occurs, the "jespa.duo.token" in the session will be set to the special DUO_TOKEN_FAILED_OPEN object.	CLOSED
duo.disabled	If set to true, 1 or yes, the Duo 2FA code will be completely disabled such that it will be equivalent to the regular HttpSecurityService.	false

This flow can be augmented to some extent by extending this class to create a custom handler or Filter that overrides various methods of this class and / or the parent HttpSecurityService.

Since:

jespa-1.2.8

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.Object	DUO_TOKEN_FAILED_OPEN Under normal operating conditions, HttpSession.getAttribute("jespa.duo.token") returns a com.duosecurity.model.Token object with detailed information about the Duo step including the end-user's mobile number and location.

Constructor Summary

Constructors

Constructor and Description
DuoHttpSecurityService()

Method Summary

Modifier and Type	Method and Description
void	doFilter(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, javax.servlet.FilterChain chain) This method overrides the parent doFilter method to invoke the Duo client only after a successful authentication by the parent HttpSecurityService.doFilter method.
void	init(java.lang.String name, javax.servlet.ServletContext servletContext, java.util.Map props) Initialize the DuoHttpSecurityService with explicitly supplied properties.
protected boolean	isDuoProtected(javax.servlet.http.HttpServletRequest request) Called by doFilter to determine if the request is for a protected resource which may only be accessed by an end-user that has successfully authenticated using Duo 2FA.
protected boolean	isLogout(javax.servlet.http.HttpServletRequest request) Called by the parent HttpSecurityService.doFilter method to determine if this is a request to "logout" the current authenticated user.
protected void	onDuoException(com.duosecurity.exception.DuoException de, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse rsp, SecurityProvider sp) Called when a DuoException occurs including but not limited to exceptions thrown by the duo_universal_java library.
protected java.lang.String	onDuoResult(com.duosecurity.model.Token token, boolean isAllow, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse rsp, SecurityProvider provider, java.lang.String entryUrl) This method is called when the Duo client processes 2FA but regardless of the result.
protected void	onException(SecurityProviderException spe, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse rsp, SecurityProvider sp) Called when a SecurityProviderException occurs within the HttpSecurityService.
protected void	onPropertiesUpdate(java.util.Map props) Called by the HttpSecurityService during initialization and when the file identified by the properties.path property has been modified (although not more than once within a 5 second period).

Methods inherited from class jespa.http.HttpSecurityService

destroy, getBindingsCertHashPolicy, getBindingsTargetSpnsPolicy, getConnectionId, getRequestCredential, getRequestPath, getServletContext, init, isAllowedAccess, isAnonymous, isProtected, matchWildcard, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DUO_TOKEN_FAILED_OPEN

public static final java.lang.Object DUO_TOKEN_FAILED_OPEN

Under normal operating conditions, HttpSession.getAttribute("jespa.duo.token") returns a com.duosecurity.model.Token object with detailed information about the Duo step including the end-user's mobile number and location. However, if the Duo health-check fails and the property duo.failmode = OPEN is set, the Duo Token will not be returned even if the authentication was successful. Instead, getAttribute will return the constant DuoHttoSecurityService.DUO_TOKEN_FAILED_OPEN.

If you write code that inspects the Duo Token, such as to initialize profile information of new users, and you want to the implementation to be able to fail open, you will need to check to see if the DUO_TOKEN_FAILED_OPEN value was returned and act accordingly (probably by throwing an Exception or returning an error). Such code might look like the following:

Token duoToken = (Token)ssn.getAttribute("jespa.duo.token");
if (duoToken == DuoHttpSecurityService.DUO_TOKEN_FAILED_OPEN) {
        throw new Exception("Failed to initialize profile: The Duo service is currently not available");
}

Handling a Duo service not available condition

Constructor Detail

DuoHttpSecurityService

public DuoHttpSecurityService()

Method Detail

init

public void init(java.lang.String name,
                 javax.servlet.ServletContext servletContext,
                 java.util.Map props)
          throws SecurityProviderException

Initialize the DuoHttpSecurityService with explicitly supplied properties. See the DuoHttpSecurityFilter for a code example that uses this method.

Overrides:

init in class HttpSecurityService

Parameters:

name - The name of this HttpSecurityService instance

servletContext - The ServletContext that is initializing this HttpSecurityService instance

props - The HttpSecurityService and SecurityProvider properties

Throws:

SecurityProviderException

onPropertiesUpdate

protected void onPropertiesUpdate(java.util.Map props)
                           throws SecurityProviderException

Called by the HttpSecurityService during initialization and when the file identified by the properties.path property has been modified (although not more than once within a 5 second period). This allows the properties file to be reloaded without reloading the webapp.

A method that overrides this must first call super.onPropertiesUpdate(props).

The default implementation of this method enumerates and isolates the "duo." prefixed properties, resets the duo.clientSecret to be an encrypted property (so that it is not leaked into log files) and resets other objects that depends on these properties such as the Duo client, the excludes list and more.

Overrides:

onPropertiesUpdate in class HttpSecurityService

Parameters:

props - The updated list of properties. The properties Map should not be modified.

Throws:

SecurityProviderException

onException

protected void onException(SecurityProviderException spe,
                           javax.servlet.http.HttpServletRequest req,
                           javax.servlet.http.HttpServletResponse rsp,
                           SecurityProvider sp)
                    throws SecurityProviderException

Called when a SecurityProviderException occurs within the HttpSecurityService. These exceptions should be exclusively related to the HSS security provider functionality (such as issues with the Windows built-in SSO functionality of the NtlmSecurityProvider). Duo related exceptions will invoke the onDuoException method.

The default implementation of this method sets the HttpSession attribute "jespa.message" to the exception message so that the page identified by the fallback.location can optionally retrieve it, remove it and display it to the end-user.

Overrides:

onException in class HttpSecurityService

Throws:

SecurityProviderException

onDuoException

protected void onDuoException(com.duosecurity.exception.DuoException de,
                              javax.servlet.http.HttpServletRequest req,
                              javax.servlet.http.HttpServletResponse rsp,
                              SecurityProvider sp)
                       throws SecurityProviderException

Called when a DuoException occurs including but not limited to exceptions thrown by the duo_universal_java library.

The default implementation of this method sets the HttpSession attribute "jespa.message" to the exception message so that the page identified by the fallback.location can optionally retrieve it, remove it and display it to the end-user.

Throws:

SecurityProviderException

onDuoResult

protected java.lang.String onDuoResult(com.duosecurity.model.Token token,
                                       boolean isAllow,
                                       javax.servlet.http.HttpServletRequest req,
                                       javax.servlet.http.HttpServletResponse rsp,
                                       SecurityProvider provider,
                                       java.lang.String entryUrl)
                                throws com.duosecurity.exception.DuoException

This method is called when the Duo client processes 2FA but regardless of the result. The isAllow parameter will be true only if Token.getAuth_result().getStatus() == "allow". This method may be overridden to implement custom Duo specific functionality when the Duo client completes such as storing information from the Token into a database or constructing a more complete security context with data from LDAP (see Account for an example).

The default implementation of this method simply returns the entryUrl parameter so that end-users will be redirected to the resource that was originally requested (unless that request was not GET in which case the entryUrl parameter and return value will be null).

If isAllow is not true, the return value is ignored and the end user will be redirected to the location indicated by the fallback.location property.

Parameters:

token - The duo_universal_java library Token resulting from 2FA with Duo service

isAllow - true only if the auth_result status is "allow"

req - The HttpServletRequest of the final redirect to the landing location. Note that this is not the entry request that triggered Duo 2FA.

rsp - The HttpServletResponse that will emit a minimal HTML page containing the JavaScript redirect URL to the landing location.

provider - The Jespa SecurityProvider representing the authenticated security context (such as the NtlmSecurityProvider).

entryUrl - The URL, including query string parameters, of the entry request that triggered Duo 2FA but will be null if the entry request was not a GET request.

Returns:

The "landing location" in the form of a URL string to which the now fully authenticated end user should be redirected. If null is retured, the landing location will be req.getContextPath() which is presumably the root of the application.

Throws:

com.duosecurity.exception.DuoException

isDuoProtected

protected boolean isDuoProtected(javax.servlet.http.HttpServletRequest request)
                          throws javax.servlet.ServletException

Called by doFilter to determine if the request is for a protected resource which may only be accessed by an end-user that has successfully authenticated using Duo 2FA. This method will not be called if the parent HttpSecurityService determined that the resource is not protected. If this method returns false, the client will not be redirected to the Duo 2FA service and the request will be allowed.

The default implementation of this method checks to see if duo.disabled = true or if the request path matches any expression in the duo.excludes list. If either case is true, false is returned to indicate that the resource is not protected from Duo 2FA.

Parameters:

request - the HttpServletRequest object passed to doFilter for the protected resource

Returns:

false if the request is not for a protected resource - otherwise true

Throws:

javax.servlet.ServletException

isLogout

protected boolean isLogout(javax.servlet.http.HttpServletRequest request)
                    throws javax.servlet.ServletException

Called by the parent HttpSecurityService.doFilter method to determine if this is a request to "logout" the current authenticated user.

The default implementation of this method just removes the jespa.duo.token object and returns the result of calling super.isLogout.

Overrides:

isLogout in class HttpSecurityService

Parameters:

request - the HttpServletRequest passed to doFilter

Returns:

true if the authenticated user should be logged out

Throws:

javax.servlet.ServletException

doFilter

public void doFilter(javax.servlet.ServletRequest request,
                     javax.servlet.ServletResponse response,
                     javax.servlet.FilterChain chain)
              throws java.io.IOException,
                     javax.servlet.ServletException

This method overrides the parent doFilter method to invoke the Duo client only after a successful authentication by the parent HttpSecurityService.doFilter method.

Note: Even though this method has the same signature as javax.servlet.Filter.doFilter, this class does not implement the Filter interface. The same method signature was used only to make it trivial to implement a Filter if desired.

Overrides:

doFilter in class HttpSecurityService

Parameters:

request - the HttpServletRequest being handled

response - the HttpServletResponse being handled

chain - the FilterChain to call if the client successfully traverses the HttpSecurityService's security controls

Throws:

java.io.IOException

javax.servlet.ServletException