com.trendmicro.grid.acl.l0
Interface PublicAuthenticationService

All Superinterfaces:

Service

@PublicRequestContext
@WebServlet(value="/ws/level-0/authentication")
public interface PublicAuthenticationService
extends Service

Service interface allowing users to authenticate their session.

Version:

1.0

Author:

Juergen_Kellerer, 2010-04-26

Method Summary

boolean	authenticate(String username, String password) Authenticates the user's session using password auth.
UUID	authenticateAndGetApiKey(String username, char[] password, Set<String> requiredRoles) Combines authentication and api key retrieval into a single call to avoid that a caller needs to keep track of the session.
UUID	getApiKey(Set<String> requiredRoles) Returns the current API key that allows login and session less access to protected services that fall under the roles that were specified with the call, or 'null' if no API key is available that satisfies this requirement.
String	getUserDisplayName() Returns the display name of the authenticated user.
Set<String>	getUserRoles() Returns the assigned roles of the authenticated user.
boolean	isAuthenticated() Returns true if the user's session is authenticated.
boolean	logout() Logs the authenticated user out and returns true on success.

Method Detail

isAuthenticated

boolean isAuthenticated()

Returns true if the user's session is authenticated.

Returns:

true if the user's session is authenticated.

authenticate

boolean authenticate(String username,
                     String password)
                     throws IllegalRequestException

Authenticates the user's session using password auth.

Parameters:

username - The name of the user to authenticate.

password - The corresponding password.

Returns:

true if the users session is authenticated.

Throws:

IllegalRequestException - In case of this method is called from a non-confidential (non-secured) connection.

logout

boolean logout()

Logs the authenticated user out and returns true on success.

Returns:

true if the user is logged out after calling this method.

getApiKey

UUID getApiKey(Set<String> requiredRoles)
               throws IllegalRequestException

Returns the current API key that allows login and session less access to protected services that fall under the roles that were specified with the call, or 'null' if no API key is available that satisfies this requirement.

API keys are in general shared among callers to allow external proxies to cache the results of a call to any of the methods in ACL while still providing protection from un-controlled external usage as long as SSL is enabled. A client should remember the API key between calls to avoid having to call this method too often (e.g. using a statically shared portion of RAM or persisting it to disk with encryption applied)

When using the API key with any of the service endpoints (see ApiKeyHandlingFilter) the methods can be accessed in exactly the same way as if a user would first authenticate a session and then call the desired method in the same session (assuming that the users privilege covers the required roles). Using API keys simplifies calls and client implementations as the keys can be added to endpoint URLs which do then no longer need additional auth or session handling when being used.

The method may return different API keys depending on the roles granted to the requesting user and the roles given with the call. This is to avoid that un-privileged users can access something they shouldn't. API keys may further expire (default validity ~ 1 week) to reduce the risk of unprivileged access coming from lost API keys (under normal circumstances they shouldn't get lost). If an API key expired a subsequent call to a protected method will behave in exactly the same way as if the user was not authenticated. The default operation of a client should be to request a new API key and replace the one it had used before.

Parameters:

requiredRoles - The roles that must be available when using the given API key.

Returns:

The API key that allows password and session less access to protected methods that fall under the given set of roles.

Throws:

IllegalRequestException - In case of this method is called from a non-confidential (non-secured) connection.

authenticateAndGetApiKey

UUID authenticateAndGetApiKey(String username,
                              char[] password,
                              Set<String> requiredRoles)
                              throws IllegalRequestException

Combines authentication and api key retrieval into a single call to avoid that a caller needs to keep track of the session.

Parameters:

requiredRoles - The roles that must be available when using the given API key.

username - The name of the user to authenticate.

password - The corresponding password.

Returns:

The API key that allows password and session less access to protected methods that fall under the given set of roles or 'null' if no API key is available that satisfies this requirement or if the authentication failed.

Throws:

IllegalRequestException - In case of this method is called from a non-confidential (non-secured) connection.

getUserDisplayName

String getUserDisplayName()

Returns the display name of the authenticated user.

Returns:

the display name of the authenticated user or 'null' if the user is not authenticated.

getUserRoles

Set<String> getUserRoles()

Returns the assigned roles of the authenticated user.

Returns:

the assigned roles of the authenticated user or an empty list if the user is not authenticated.