1   package com.trendmicro.grid.acl.l0;
2   
3   import com.trendmicro.grid.acl.PublicRequestContext;
4   import com.trendmicro.grid.acl.Service;
5   
6   import javax.jws.WebMethod;
7   import javax.jws.WebParam;
8   import javax.jws.WebResult;
9   import javax.jws.WebService;
10  import javax.servlet.annotation.WebServlet;
11  import java.util.Set;
12  import java.util.UUID;
13  
14  /**
15   * Service interface allowing users to authenticate their session.
16   *
17   * @author Juergen_Kellerer, 2010-04-26
18   * @version 1.0
19   */
20  @PublicRequestContext
21  @WebServlet("/ws/level-0/authentication")
22  @WebService(targetNamespace = Level0Constants.NAMESPACE)
23  public interface PublicAuthenticationService extends Service {
24  	/**
25  	 * Returns true if the user's session is authenticated.
26  	 *
27  	 * @return true if the user's session is authenticated.
28  	 */
29  	@WebMethod
30  	@WebResult(name = "authenticated")
31  	boolean isAuthenticated();
32  
33  	/**
34  	 * Authenticates the user's session using password auth.
35  	 *
36  	 * @param username The name of the user to authenticate.
37  	 * @param password The corresponding password.
38  	 * @return true if the users session is authenticated.
39  	 * @throws IllegalRequestException In case of this method is called from a non-confidential (non-secured) connection.
40  	 */
41  	@WebMethod
42  	@WebResult(name = "authenticated")
43  	boolean authenticate(
44  			@WebParam(name = "username") String username,
45  			@WebParam(name = "password") String password) throws IllegalRequestException;
46  
47  	/**
48  	 * Logs the authenticated user out and returns true on success.
49  	 *
50  	 * @return true if the user is logged out after calling this method.
51  	 */
52  	@WebMethod
53  	@WebResult(name = "loggedOut")
54  	boolean logout();
55  
56  	/**
57  	 * Returns the current API key that allows login and session less access to protected services that fall under the roles that
58  	 * were specified with the call, or 'null' if no API key is available that satisfies this requirement.
59  	 * <p/>
60  	 * 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
61  	 * while still providing protection from un-controlled external usage as long as SSL is enabled. A client should remember the API key
62  	 * between calls to avoid having to call this method too often (e.g. using a statically shared portion of RAM or persisting it to
63  	 * disk with encryption applied)
64  	 * <p/>
65  	 * When using the API key with any of the service endpoints (see {@link com.trendmicro.grid.acl.ApiKeyHandlingFilter}) the methods
66  	 * 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
67  	 * session (assuming that the users privilege covers the required roles). Using API keys simplifies calls and client implementations
68  	 * as the keys can be added to endpoint URLs which do then no longer need additional auth or session handling when being used.
69  	 * <p/>
70  	 * The method may return different API keys depending on the roles granted to the requesting user and the roles given with the call.
71  	 * This is to avoid that un-privileged users can access something they shouldn't. API keys may further expire (default validity
72  	 * ~ 1 week) to reduce the risk of unprivileged access coming from lost API keys (under normal circumstances they shouldn't get lost).
73  	 * 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
74  	 * authenticated. The default operation of a client should be to request a new API key and replace the one it had used before.
75  	 *
76  	 * @param requiredRoles The roles that must be available when using the given API key.
77  	 * @return The API key that allows password and session less access to protected methods that fall under the given set of roles.
78  	 * @throws IllegalRequestException In case of this method is called from a non-confidential (non-secured) connection.
79  	 */
80  	@WebMethod
81  	@WebResult(name = "apiKey")
82  	UUID getApiKey(@WebParam(name = "requiredRoles") Set<String> requiredRoles) throws IllegalRequestException;
83  
84  	/**
85  	 * Combines authentication and api key retrieval into a single call to avoid that a caller needs to keep track of the session.
86  	 *
87  	 * @param requiredRoles The roles that must be available when using the given API key.
88  	 * @param username      The name of the user to authenticate.
89  	 * @param password      The corresponding password.
90  	 * @return The API key that allows password and session less access to protected methods that fall under the given set of roles or
91  	 *         'null' if no API key is available that satisfies this requirement or if the authentication failed.
92  	 * @throws IllegalRequestException In case of this method is called from a non-confidential (non-secured) connection.
93  	 */
94  	@WebMethod
95  	@WebResult(name = "apiKey")
96  	UUID authenticateAndGetApiKey(@WebParam(name = "username") String username,
97  	                              @WebParam(name = "password") char[] password,
98  	                              @WebParam(name = "requiredRoles") Set<String> requiredRoles) throws IllegalRequestException;
99  
100 	/**
101 	 * Returns the display name of the authenticated user.
102 	 *
103 	 * @return the display name of the authenticated user or 'null' if the user is not authenticated.
104 	 */
105 	@WebMethod
106 	@WebResult(name = "userDisplayName")
107 	String getUserDisplayName();
108 
109 	/**
110 	 * Returns the assigned roles of the authenticated user.
111 	 *
112 	 * @return the assigned roles of the authenticated user or an empty list if the user is not authenticated.
113 	 */
114 	@WebMethod
115 	@WebResult(name = "roleAssignment")
116 	Set<String> getUserRoles();
117 }