reformat using eclipse's autoformatter. now if i could only make eclipse's indentatio...
[java-idp.git] / src / edu / internet2 / middleware / shibboleth / idp / authn / LoginContext.java
1 /*
2  * Copyright [2006] [University Corporation for Advanced Internet Development, Inc.]
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package edu.internet2.middleware.shibboleth.idp.authn;
18
19 import java.util.Map;
20 import java.util.concurrent.ConcurrentHashMap;
21
22 import org.joda.time.DateTime;
23
24 /**
25  * Login context created by a profile handler and interpreted by the
26  * authentication package.
27  * 
28  * Two properties are tracked by default:
29  * 
30  * <code>forceAuth</code> - Should user authentiation be forced.
31  * <code>passiveAuth</code> - Should user authentication not control the UI.
32  * 
33  * A Map&lt;String, Object&gt; is provided to store other properties.
34  * Alternatively, a profile handler may create a subclass of LoginContext with
35  * extra fields.
36  * 
37  * LoginContexts should be created by a profile handler when authentication is
38  * needed. Once control has returned to the profile handler, it should remove
39  * the LoginContext from the HttpSession.
40  * 
41  * The {@link AuthenticationManager} or an {@link AuthenticationHandler} should
42  * set the {@link LoginContext#setAuthenticationAttempted()},
43  * {@link LoginContext#setAuthnOK(boolean)},
44  * {@link LoginContext#setAuthnFailure(String)},
45  * {@link LoginContext#{setAuthenticationDuration(long)}
46  * {@link LoginContext#setAuthenticationInstant(DateTime)} appropriately.
47  * 
48  */
49 public class LoginContext {
50
51         /** the key in a HttpSession where login contexts are stored */
52         public static final String LOGIN_CONTEXT_KEY = "shib2.logincontext";
53
54         /** Should user authentication be forced */
55         protected boolean forceAuth = false;
56
57         /** Must authentication not interact with the UI */
58         protected boolean passiveAuth = false;
59
60         /** a catch-all map for other properties */
61         protected Map<String, Object> propsMap = new ConcurrentHashMap<String, Object>();;
62
63         /** The ProfileHandler URL */
64         protected String profileHandlerURL;
65
66         /** The AuthenticationManager's URL */
67         protected String authnManagerURL;
68
69         /** has authentication been attempted yet */
70         protected boolean authnAttempted = false;
71
72         /** The id of the authenticated user */
73         protected String userID;
74
75         /** Did authentication succceed? */
76         protected boolean authenticationOK;
77
78         /** Optional failure message */
79         protected String authnFailureMessage;
80
81         /** The instant of authentication */
82         protected DateTime authnInstant;
83
84         /** The duration of authentication */
85         protected long authnDuration;
86
87         /** The method used to authenticate the user */
88         protected String authnMethod;
89
90         /** The session id */
91         protected String sessionID;
92
93         /** Creates a new instance of LoginContext */
94         public LoginContext() {
95         }
96
97         /**
98          * Creates a new instance of LoginContext
99          * 
100          * @param forceAuth
101          *            if the authentication manager must reauth the user.
102          * @param passiveAuth
103          *            if the authentication manager must not interact with the users
104          *            UI.
105          */
106         public LoginContext(boolean forceAuth, boolean passiveAuth) {
107
108                 forceAuth = forceAuth;
109                 passiveAuth = passiveAuth;
110         }
111
112         /**
113          * Returns if authentication must be forced.
114          * 
115          * @return <code>true</code> if the authentication manager must reauth the
116          *         user.
117          */
118         public boolean getForceAuth() {
119                 return forceAuth;
120         }
121
122         /**
123          * Returns if authentication must be passive.
124          * 
125          * @return <code>true</code> if the authentication manager must not
126          *         interact with the users UI.
127          */
128         public boolean getPassiveAuth() {
129                 return passiveAuth;
130         }
131
132         /**
133          * Sets if authentication must be forced.
134          * 
135          * @param forceAuth
136          *            if the authentication manager must reauth the user.
137          */
138         public void setForceAuth(boolean forceAuth) {
139                 this.forceAuth = forceAuth;
140         }
141
142         /**
143          * Sets if authentication must be passive.
144          * 
145          * @param passiveAuth
146          *            if the authentication manager must not interact with the users
147          *            UI.
148          */
149         public void setPassiveAuth(boolean passiveAuth) {
150                 this.passiveAuth = passiveAuth;
151         }
152
153         /**
154          * Get an optional property object.
155          * 
156          * @param key
157          *            The key in the properites Map.
158          * 
159          * @return The object, or <code>null</code> is no object exists for the
160          *         key.
161          */
162         public Object getProperty(String key) {
163                 return propsMap.get(key);
164         }
165
166         /**
167          * Sets an optional property object.
168          * 
169          * If an object is already associated with key, it will be overwritten.
170          * 
171          * @param key
172          *            The key to set.
173          * @param obj
174          *            The object to associate with key.
175          */
176         public void setProperty(String key, final Object obj) {
177                 propsMap.put(key, obj);
178         }
179
180         /**
181          * Sets if authentication succeeded.
182          * 
183          * @param authnOK
184          *            if authentication succeeded;
185          */
186         public void setAuthenticationOK(boolean authnOK) {
187                 this.authenticationOK = authnOK;
188         }
189
190         /**
191          * Returns if authentication succeeded.
192          * 
193          * @return <code>true</code> is the user was successfully authenticated.
194          */
195         public boolean getAuthenticationOK() {
196                 return authenticationOK;
197         }
198
199         /**
200          * Sets the optional authentication failure message.
201          * 
202          * @param failureMessage
203          *            A description of why authN failed.
204          */
205         public void setAuthenticationFailureMessage(String failureMessage) {
206                 authnFailureMessage = failureMessage;
207         }
208
209         /**
210          * Returns the optional authentication failure message.
211          * 
212          * @return The failure message, or <code>null</code> is none was set.
213          */
214         public String getAuthenticationFailureMessage() {
215                 return authnFailureMessage;
216         }
217
218         /**
219          * Set if authentication has been attempted.
220          * 
221          * This method should be called by an {@link AuthenticationHandler} while
222          * processing a request.
223          */
224         public void setAuthenticationAttempted() {
225                 authnAttempted = true;
226         }
227
228         /**
229          * Returns if authentication has been attempted for this user.
230          */
231         public boolean getAuthenticationAttempted() {
232                 return authnAttempted;
233         }
234
235         /**
236          * Sets the ID of the authenticated user.
237          * 
238          * @param userID
239          *            The userid.
240          */
241         public void setUserID(String userID) {
242                 this.userID = userID;
243         }
244
245         /**
246          * Returns the ID of the authenticated user.
247          * 
248          * @return the ID of the user, or <code>null</code> if authentication
249          *         failed.
250          */
251         public String getUserID() {
252                 return userID;
253         }
254
255         /**
256          * Gets the ProfileHandler URL.
257          * 
258          * @return the URL of the profile handler that is invoking the
259          *         Authentication Manager.
260          */
261         public String getProfileHandlerURL() {
262                 return profileHandlerURL;
263         }
264
265         /**
266          * Sets the ProfileHandler URL.
267          * 
268          * @param profileHandlerURL
269          *            The URL of the profile handler that invoked the
270          *            AuthenticationManager/
271          */
272         public void setProfileHandlerURL(String profileHandlerURL) {
273                 this.profileHandlerURL = profileHandlerURL;
274         }
275
276         /**
277          * Gets the AuthenticationManager URL.
278          * 
279          * @return the URL of the AuthenticationManager.
280          */
281         public String getAuthenticationManagerURL() {
282                 return authnManagerURL;
283         }
284
285         /**
286          * Sets the AuthenticationManager's URL.
287          * 
288          * @param authnManagerURL
289          *            the URL of the AuthenticationManager.
290          */
291         public void setAuthenticationManagerURL(String authnManagerURL) {
292                 this.authnManagerURL = authnManagerURL;
293         }
294
295         /**
296          * Gets the authentication instant.
297          * 
298          * @return The instant of authentication, or <code>null</code> if none was
299          *         set.
300          */
301         public DateTime getAuthenticationInstant() {
302                 return authnInstant;
303         }
304
305         /**
306          * Sets the authentication instant.
307          * 
308          * @param authnInstant
309          *            The instant of authentication.
310          */
311         public void setAuthenticationInstant(final DateTime authnInstant) {
312                 this.authnInstant = authnInstant;
313         }
314
315         /**
316          * Gets the duration of authentication.
317          * 
318          * @return The duration of authentication, or zero if none was set.
319          */
320         public long getAuthenticationDuration() {
321                 return authnDuration;
322         }
323
324         /**
325          * Sets the duration of authentication.
326          * 
327          * @param authnDuration
328          *            The duration of authentication.
329          */
330         public void setAuthenticationDuration(long authnDuration) {
331                 this.authnDuration = authnDuration;
332         }
333
334         /**
335          * Gets the method used to authenticate the user.
336          * 
337          * @return The method used to authenticate the user.
338          */
339         public String getAuthenticationMethod() {
340                 return authnMethod;
341         }
342
343         /**
344          * Sets the method used to authenticate the user.
345          * 
346          * @param authnMethod
347          *            The method used to authenticate the user.
348          */
349         public void setAuthenticationMethod(String authnMethod) {
350                 this.authnMethod = authnMethod;
351         }
352
353         /**
354          * Gets the {@link Session} ID
355          * 
356          * @return the Session id.
357          */
358         public String getSessionID() {
359                 return sessionID;
360         }
361
362         /**
363          * Sets the {@link Session} ID
364          * 
365          * @param sessionID
366          *            the Session ID
367          */
368         public void setSessionID(String sessionID) {
369                 this.sessionID = sessionID;
370         }
371
372         /**
373          * Return the acceptable authentication handler URIs for authenticating this
374          * user. If no authentication methods are preferred, this method will return
375          * <code>null</code>.
376          * 
377          * @return an array of URIs, or <code>null</code>.
378          */
379         public String[] getRequestedAuthenticationMethods() {
380
381                 return null;
382         }
383 }