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.

The syntax of the authenticate method is as follows:

boolean authenticate(HttpServletResponse response))

The previous example uses the following element:

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).

Avoid trouble: When the authenticate method is called, be aware of the following:

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.

Make sure that the authenticate method returns true before using the new subject to call another service. For example:

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).

The syntax of the login method is as follows:

login(java.lang.String username, java.lang.String password)

The previous example uses the following elements:

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.

Avoid trouble: The authenticate and login methods set the invocation subject to the new subject. If the caller subject is null, it then sets the caller subject to the new subject. If the caller subject is not null, then the caller subject is not set to the new subject.

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

The logout method logs the user out of the WebSphere Application Server and invalidates the HTTP session. During this process, WebSphere Application Server completes the following processes:

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.

The syntax of the logout method is as follows:

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.

Table 1. Audit event types for the authenticate, login, and logout methods .
The audit event types required for the authenticate, login, and logout methods are:
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

Avoid trouble: If global security and application security settings are not enabled, then logon is a no-op.

isUserInRole

(String role name): Returns true if the remote user is granted the specified security role. If the remote user is not granted the specified role, or if no user is authenticated, it returns false.

Avoid trouble: If global security and application security settings are not enabled, 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.

The authentication schemes used are:

FORM: when form-based authentication is used
BASIC: when basic authentication is used.
CLIENT_CERT: when client certificate authentication is used.

For both the getRemoteUser and getAuthType methods, the data that is returned depends upon whether security is enabled in the application server where the servlet is deployed. The following possibilities exist:

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.