Servlet security methods
The authenticate, login, logout, getRemoteUser, isUserInRole and getAuthType servlet security methods are methods of the javax.servlet.http.HttpServletRequest interface.
authenticate
The authenticate, login and logout servlet security methods are in Java™ Servlet 3.0.
The authenticate method authenticates a user by using the WebSphere® Application Server container login mechanism configured for the servlet context.
boolean authenticate(HttpServletResponse response))
- response
- The HttpServletResponse associated with the HttpServletRequest.
The authenticate method returns true when authentication has been established or authentication is successful.
The authenticate method returns false if authentication is incomplete and the underlying login mechanism has committed, in the response, the message and HTTP status code to be returned to the user.
A java.io.IOException occurs if an error occurs while writing the response.
A ServletException occurs if the authentication failed, and the caller is responsible for handling the error (for example, the underlying login mechanism did not establish the message and the HTTP status code to be returned to the user).
- WebSphere Application Server returns
HTTP 401
code to a client. - The method depends on the WebSphere Application Server container login mechanism that is configured for the servlet context. For example, if you have a form login defined for this servlet, it prompts for a user name and password. The client sends the user ID and password to WebSphere Application Server for authentication.
- The authenticate method always returns false if global security and application security settings are not enabled.
Boolean authResultTrue = req.authenticate(response);
if (!authResultTrue) {
return;
} else {
// Use the new invocation subject to call other services.
}
login
The login method authenticates a user to the WebSphere Application Server with a user ID and password. If authentication is successful, it creates a user subject on the thread and Lightweight Third Party Authentication (LTPA) cookies (if single sign-on (SSO) is enabled).
login(java.lang.String username, java.lang.String password)
- username
- The string value that corresponds to the login identifier of the user.
- password
- The password of the user.
A ServletException occurs if the configured login mechanism does not support username and password authentication, if an identity had already been authenticated (prior to the call to login), or if validation of the provided username and password fails.
You can set the security custom property com.ibm.websphere.security.webAlwaysLogin to true and it will authenticate to the WebSphere application with the username and password, even if it is already authenticated. For more information about modifying security custom properties, read the Modifying an existing custom property in a global security configuration or in a security domain configuration topic.
The login method always uses the user ID and password to authenticate to the WebSphere application server and even the SSO information that is present in the HttpServletRequest.
Because the authenticate and login methods set the invocation subject to the new subject, the RunAs defined by the run-As attribute in deployment descriptor, security annotation or dynamic annotation is ignored.
If global security and application security settings are not enabled, then logon is a no-op.
logout
- Clears the LTPA cookies if SSO is enabled
- Invalidates the HTTP session
- Removes the user from the authentication cache
- Removes the user subject from the thread
- Clears the caller and invocation subjects
- Sets the authentication type to null
After logging out, access to a protected web resource requires re-authentication and the getUserPrincipal, getRemoteUser and getAuthType methods return null.
logout()
A ServletException occurs if the logout fails.
Audit event types for the authenticate, login and logout methods
To audit authenticate, login and logout methods, you must create or extend some audit event type files. These event type are not part of the default event type files.
Method | Audit event name | Audit outcome of the event |
---|---|---|
authenticate/login | SECURITY_AUTHN | SUCCESS and or FAILURE |
logout | SECURITY_AUTHN_TERMINATE | SUCCESS |
logout | SECURITY_AUTHN_TERMINATE | FAILURE |
isUserInRole
isUserInRole
returns
false.getRemoteUser
The getRemoteUser method returns the login of the user that makes the request if the user has been authenticated. If the user has not been authenticated, the getRemoteUser method returns null.
getAuthType
The getAuthType method returns the name of the authentication scheme that is used to protect the servlet. If the servlet is not protected, the getAuthType method returns null.
- FORM
- when form-based authentication is used
- BASIC
- when basic authentication is used.
- CLIENT_CERT
- when client certificate authentication is used.
- If application security is enabled and a servlet is protected, then the getRemoteUser method returns the login and the getAuthType method returns the configured authentication scheme.
- If application security is not enabled, both methods return null.