+

Search Tips   |   Advanced Search

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 new for Java Servlet 3.0 in this release of WebSphere Application Server.

The authenticate method authenticates a user using the WAS 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).

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

Important: Verify 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 article.

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.

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.

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


logout

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

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, 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

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


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 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:

  • Developing with programmatic security APIs for web applications
  • Auditing the security infrastructure
  • Authenticating users
  • Modifying an existing custom property in a global security configuration or in a security domain configuration