1 /*
2 * This software was designed and created by Jason Carroll.
3 * Copyright (c) 2002, 2003, 2004 Jason Carroll.
4 * The author can be reached at jcarroll@cowsultants.com
5 * ITracker website: http://www.cowsultants.com
6 * ITracker forums: http://www.cowsultants.com/phpBB/index.php
7 *
8 * This program is free software; you can redistribute it and/or modify
9 * it only under the terms of the GNU General License as published by
10 * the Free Software Foundation; either version 2 of the License, or
11 * (at your option) any later version.
12 *
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General License for more details.
17 */
18
19 package org.itracker.services.authentication;
20
21 import org.itracker.model.Permission;
22 import org.itracker.model.PermissionType;
23 import org.itracker.model.User;
24 import org.itracker.services.exceptions.AuthenticatorException;
25
26 import java.util.List;
27 import java.util.Map;
28
29 /**
30 * This interface should be implemented to provide a new authentication module for
31 * ITracker. It provides service to check if a user can be authenticated
32 * during a login, and also whether a user self registration is allowed. A new
33 * instance of this object is created for each check.
34 *
35 * @see org.itracker.core.AuthenticationConstants
36 */
37 public interface PluggableAuthenticator {
38
39 /**
40 * This method should be implemented to determine if a user login is successful. The method
41 * should return a valid User object.
42 *
43 * @param login the login the user/client provided
44 * @param authentication the user's authentication information, if known
45 * @param authType the type of authentication information being provided
46 * @param reqSource the source of the request (eg web, api)
47 * @return a User if the login is successful
48 * @throws AuthenticatorException an exception if the login is unsuccessful, or an error occurs
49 */
50 User checkLogin(String login, Object authentication, int authType, int reqSource) throws AuthenticatorException;
51
52 /**
53 * This method should return all the permissions a user has in the authentication system. This
54 * list may then be augmented based on other attributes of the user, or project level options.
55 *
56 * @param user a User object that contains the user to retrieve permissions for
57 * @param reqSource the source of the request (eg web, api)
58 * @return an array of PermissionModels
59 * @throws AuthenticatorException an error occurs
60 */
61 List<Permission> getUserPermissions(User user, int reqSource) throws AuthenticatorException;
62
63 /**
64 * This method should return an array of users that have certain permissions in the
65 * authentication system. This list must always include all super users, even if they
66 * do not explicitly have the required permission.
67 *
68 * @param projectId id of the project on which the users return have permissions
69 * @param permissionTypes types of permissions required
70 * @param requireAll true is the user must possess any of the permissions, false if only one is required
71 * @param activeOnly true if only users listed as active should be returned
72 * @param reqSource the source of the request (eg web, api)
73 * @return an array of UserModels
74 * @throws AuthenticatorException an error occurs
75 */
76 List<User> getUsersWithProjectPermission(Integer projectId,
77 PermissionType[] permissionTypes, boolean requireAll,
78 boolean activeOnly, int reqSource)
79 throws AuthenticatorException;
80
81 /**
82 * This method should return an array of users that have certain permissions in the
83 * authentication system. This list must always include all super users, even if they
84 * do not explicitly have the required permission.
85 *
86 * @param projectId id of the project on which the users return have permissions
87 * @param permissionTypes types of permissions required
88 * @param requireAll true is the user must possess any of the permissions, false if only one is required
89 * @param activeOnly true if only users listed as active should be returned
90 * @param reqSource the source of the request (eg web, api)
91 * @return an array of UserModels
92 * @throws AuthenticatorException an error occurs
93 */
94 @Deprecated
95 List<User> getUsersWithProjectPermission(Integer projectId,
96 int[] permissionTypes, boolean requireAll,
97 boolean activeOnly, int reqSource)
98 throws AuthenticatorException;
99
100 /**
101 * This method should be implemented to determine if a user is authorized to self register.
102 *
103 * @param user a User object that contains the data the user submitted
104 * @param authentication the user's authentication information, if known
105 * @param authType the type of authentication information being provided
106 * @param reqSource the source of the request (eg web, api)
107 * @return a boolean whether the user should be allowed to register
108 * @throws AuthenticatorException an exception if an error occurs
109 */
110 boolean allowRegistration(User user, Object authentication, int authType, int reqSource) throws AuthenticatorException;
111
112 /**
113 * This method should be implemented to determine if a new user profile should be allowed
114 * to be created. This applies to both self registration and also new users created by
115 * a super user on the system. If this method would always return false, then some other
116 * mechanism must be provided for new users to be created in the system.
117 *
118 * @param user a User object that contains the data for the new user. If null,
119 * then the request is being made for an unknown future user. For example,
120 * the system may request this with an null user if it needs to know if the system
121 * should even present the option to create a new user
122 * @param authentication the user's authentication information, if known
123 * @param authType the type of authentication information being provided
124 * @param reqSource the source of the request (eg web, api)
125 * @return a boolean whether new profile creation is allowed
126 * @throws AuthenticatorException an exception if an error occurs
127 */
128 boolean allowProfileCreation(User user, Object authentication, int authType, int reqSource) throws AuthenticatorException;
129
130 /**
131 * This method should be implemented to determine if the particular user is
132 * allowed to perform profile updates on the system. This method is used in
133 * conjunction with allowPasswordUpdates, allowPreferenceUpdates, and
134 * allowPermissionUpdates to determine what parts of the user's information
135 * is allowed to be updated through ITracker.
136 *
137 * @param user a User object that contains the data the user submitted
138 * @param authentication the user's authentication information, if known
139 * @param authType the type of authentication information being provided
140 * @param reqSource the source of the request (eg web, api)
141 * @return a boolean whether the user's core profile information can be updated
142 * @throws AuthenticatorException an exception if an error occurs
143 * @see PluggableAuthenticator#allowPasswordUpdates
144 * @see PluggableAuthenticator#allowPermissionUpdates
145 * @see PluggableAuthenticator#allowPreferenceUpdates
146 */
147 boolean allowProfileUpdates(User user, Object authentication, int authType, int reqSource) throws AuthenticatorException;
148
149 /**
150 * This method should be implemented to determine if the particular user is allowed to perform
151 * password updates on the system. This method is used in conjunction with allowProfileUpdates,
152 * allowPermissionUpdates, and allowPreferenceUpdates to determine what parts of the user's
153 * information is allowed to be updated through ITracker.
154 *
155 * @param user a User object that contains the current user data
156 * @param authentication the user's authentication information, if known
157 * @param authType the type of authentication information being provided
158 * @param reqSource the source of the request (eg web, api)
159 * @return a boolean whether the user's core profile information can be updated
160 * @throws AuthenticatorException an exception if an error occurs
161 * @see PluggableAuthenticator#allowProfileUpdates
162 * @see PluggableAuthenticator#allowPermissionUpdates
163 * @see PluggableAuthenticator#allowPreferenceUpdates
164 */
165 boolean allowPasswordUpdates(User user, Object authentication, int authType, int reqSource) throws AuthenticatorException;
166
167 /**
168 * This method should be implemented to determine if the particular user is allowed to perform
169 * permissions updates on the system. This method is used in conjunction with allowProfileUpdates,
170 * allowPasswordUpdates, and allowPreferenceUpdates to determine what parts of the user's
171 * information is allowed to be updated through ITracker. If the user model is null, then the
172 * request is being made for multiple users, for example on the edit project page, and is being applied
173 * on a generic basis, that is are permission updates allowed at all on the system.
174 *
175 * @param user a User object that contains the current user data, or null if multiple users
176 * @param authentication the user's authentication information, if known
177 * @param authType the type of authentication information being provided
178 * @param reqSource the source of the request (eg web, api)
179 * @return a boolean whether the user's core profile information can be updated
180 * @throws AuthenticatorException an exception if an error occurs
181 * @see PluggableAuthenticator#allowProfileUpdates
182 * @see PluggableAuthenticator#allowPasswordUpdates
183 * @see PluggableAuthenticator#allowPreferenceUpdates
184 */
185 boolean allowPermissionUpdates(User user, Object authentication, int authType, int reqSource) throws AuthenticatorException;
186
187 /**
188 * This method should be implemented to determine if the particular user is allowed to perform
189 * preferences updates on the system. This method is used in conjunction with allowProfileUpdates,
190 * allowPasswordUpdates, and allowPermissionUpdate to determine what parts of the user's
191 * information is allowed to be updated through ITracker.
192 *
193 * @param user a User object that contains the current user data
194 * @param authentication the user's authentication information, if known
195 * @param authType the type of authentication information being provided
196 * @param reqSource the source of the request (eg web, api)
197 * @return a boolean whether the user's core profile information can be updated
198 * @throws AuthenticatorException an exception if an error occurs
199 * @see PluggableAuthenticator#allowProfileUpdates
200 * @see PluggableAuthenticator#allowPasswordUpdates
201 * @see PluggableAuthenticator#allowPermissionUpdates
202 */
203 boolean allowPreferenceUpdates(User user, Object authentication, int authType, int reqSource) throws AuthenticatorException;
204
205 /**
206 * This method should be implemented to perform any updates that are necessary in the authentication
207 * system to support a new user. Any updates needed to the data supplied should be made in the supplied
208 * User. The system will then update the information in the ITracker datastore. Only changes to the
209 * core profile information and password are made here. Any permission information for the new user
210 * would be done through an updateProfile call.
211 *
212 * @param user a User object that contains the newly created profile
213 * @param authentication the user's authentication information, if known
214 * @param authType the type of authentication information being provided
215 * @param reqSource the source of the request (eg web, api)
216 * @return true if changes were made
217 * @throws AuthenticatorException an error occurs
218 * @see PluggableAuthenticator#updateProfile
219 */
220 boolean createProfile(User user, Object authentication, int authType, int reqSource) throws AuthenticatorException;
221
222 /**
223 * This method should be implemented to perform any updates that are necessary in the authentication
224 * system to support the updated user information. This action will be called any time there are any
225 * updates to a user including core profile information, password information, permission information
226 * or preference changes. Any changes should be made directly to user model supplied to the method.
227 *
228 * @param user a User object that contains the updated profile
229 * @param updateType the type of information that is being updated
230 * @param authentication the user's authentication information, if known
231 * @param authType the type of authentication information being provided
232 * @param reqSource the source of the request (eg web, api)
233 * @return true if changes were made
234 * @throws AuthenticatorException an exception if the login is unsuccessful, or an error occurs
235 */
236 boolean updateProfile(User user, int updateType, Object authentication, int authType, int reqSource) throws AuthenticatorException;
237
238 /**
239 * This method should be implemented to setup any needed components. It is called
240 * Every time a new check is performed but could be used to store static information
241 * that is not changed.
242 *
243 * @param value A HashMap that contains some default information. The current calls
244 * pass a UserService bean as userService, and an ConfigurationService
245 * bean as configurationService
246 */
247 void initialize(Map<?, ?> value);
248
249 }