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