Javadoc cleanup
[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.io.Serializable;
20 import java.util.ArrayList;
21 import java.util.List;
22 import java.util.Map;
23 import java.util.concurrent.ConcurrentHashMap;
24
25 import org.joda.time.DateTime;
26
27 /**
28  * Login context created by a profile handler and interpreted by the authentication package.
29  * 
30  * Two properties are tracked by default:
31  * 
32  * <code>forceAuth</code> - Should user authentication be forced. <code>passiveAuth</code> - Should user
33  * authentication not control the UI.
34  * 
35  * A Map&lt;String, Object&gt; is provided to store other properties. Alternatively, a profile handler may create a
36  * subclass of LoginContext with extra fields.
37  * 
38  * LoginContexts should be created by a profile handler when authentication is needed. Once control has returned to the
39  * profile handler, it should remove the LoginContext from the HttpSession.
40  * 
41  * The {@link AuthenticationEngine} or an {@link LoginHandler} should set the
42  * {@link LoginContext#setAuthenticationAttempted()}, {@link LoginContext#setPrincipalAuthenticated(boolean)},
43  * {@link LoginContext#setAuthenticationFailure(AuthenticationException)},
44  * {@link LoginContext#setAuthenticationDuration(long)}, {@link LoginContext#setAuthenticationInstant(DateTime)}
45  * appropriately.
46  */
47 public class LoginContext implements Serializable {
48
49     /** the key in a HttpSession where login contexts are stored. */
50     public static final String LOGIN_CONTEXT_KEY = "shib2.logincontext";
51
52     /** Serial version UID. */
53     private static final long serialVersionUID = -8764003758734956911L;
54
55     /** Entity ID of the relying party. */
56     private String relyingPartyId;
57
58     /** Should user authentication be forced. */
59     private boolean forceAuth;
60
61     /** Must authentication not interact with the UI. */
62     private boolean passiveAuth;
63
64     /** a catch-all map for other properties. */
65     private Map<String, Serializable> propsMap = new ConcurrentHashMap<String, Serializable>();
66
67     /** The ProfileHandler URL. */
68     private String profileHandlerURL;
69
70     /** The authentication engine's URL. */
71     private String authnEngineURL;
72
73     /** has authentication been attempted yet. */
74     private boolean authnAttempted;
75
76     /** The id of the authenticated user. */
77     private String principalName;
78
79     /** Did authentication succeed? */
80     private boolean principalAuthenticated;
81
82     /** Exception that occured during authentication. */
83     private AuthenticationException authnException;
84
85     /** The instant of authentication. */
86     private DateTime authnInstant;
87
88     /** The duration of authentication. */
89     private long authnDuration;
90
91     /** The method used to authenticate the user. */
92     private String authnMethod;
93
94     /** The session id. */
95     private String sessionID;
96
97     /** List of request authentication methods. */
98     private ArrayList<String> requestAuthenticationMethods;
99
100     /** Creates a new instance of LoginContext. */
101     public LoginContext() {
102         requestAuthenticationMethods = new ArrayList<String>();
103     }
104
105     /**
106      * Creates a new instance of LoginContext.
107      * 
108      * @param force if the authentication manager must re-authenticate the user.
109      * @param passive if the authentication manager must not interact with the users UI.
110      */
111     public LoginContext(boolean force, boolean passive) {
112         forceAuth = force;
113         passiveAuth = passive;
114         requestAuthenticationMethods = new ArrayList<String>();
115     }
116
117     /**
118      * Gets the entity ID of the relying party.
119      * 
120      * @return entity ID of the relying party
121      */
122     public String getRelyingPartyId() {
123         return relyingPartyId;
124     }
125
126     /**
127      * Gets the entity ID of the relying party.
128      * 
129      * @param id entity ID of the relying party
130      */
131     public void setRelyingParty(String id) {
132         relyingPartyId = id;
133     }
134
135     /**
136      * Returns if authentication must be forced.
137      * 
138      * @return <code>true</code> if the authentication manager must re-authenticate the user.
139      */
140     public boolean isForceAuthRequired() {
141         return forceAuth;
142     }
143
144     /**
145      * Returns if authentication must be passive.
146      * 
147      * @return <code>true</code> if the authentication manager must not interact with the users UI.
148      */
149     public boolean isPassiveAuthRequired() {
150         return passiveAuth;
151     }
152
153     /**
154      * Sets if authentication must be forced.
155      * 
156      * @param force if the authentication manager must re-authenticate the user.
157      */
158     public void setForceAuthRequired(boolean force) {
159         forceAuth = force;
160     }
161
162     /**
163      * Sets if authentication must be passive.
164      * 
165      * @param passive if the authentication manager must not interact with the users UI.
166      */
167     public void setPassiveAuthRequired(boolean passive) {
168         passiveAuth = passive;
169     }
170
171     /**
172      * Get an optional property object.
173      * 
174      * @param key The key in the properties Map.
175      * 
176      * @return The object, or <code>null</code> is no object exists for the key.
177      */
178     public Object getProperty(String key) {
179         return propsMap.get(key);
180     }
181
182     /**
183      * Sets an optional property object.
184      * 
185      * If an object is already associated with key, it will be overwritten.
186      * 
187      * @param key The key to set.
188      * @param obj The object to associate with key.
189      */
190     public void setProperty(String key, final Serializable obj) {
191         propsMap.put(key, obj);
192     }
193
194     /**
195      * Sets if authentication succeeded.
196      * 
197      * @param authnOK if authentication succeeded;
198      */
199     public void setPrincipalAuthenticated(boolean authnOK) {
200         this.principalAuthenticated = authnOK;
201     }
202
203     /**
204      * Returns if authentication succeeded.
205      * 
206      * @return <code>true</code> is the user was successfully authenticated.
207      */
208     public boolean isPrincipalAuthenticated() {
209         return principalAuthenticated;
210     }
211
212     /**
213      * Sets the error that occurred during authentication.
214      * 
215      * @param error error that occurred during authentication
216      */
217     public void setAuthenticationFailure(AuthenticationException error) {
218         authnException = error;
219     }
220
221     /**
222      * Gets the error that occurred during authentication.
223      * 
224      * @return error that occurred during authentication
225      */
226     public AuthenticationException getAuthenticationFailure() {
227         return authnException;
228     }
229
230     /**
231      * Set if authentication has been attempted.
232      * 
233      * This method should be called by an {@link LoginHandler} while processing a request.
234      */
235     public void setAuthenticationAttempted() {
236         authnAttempted = true;
237     }
238
239     /**
240      * Returns if authentication has been attempted for this user.
241      * 
242      * @return if authentication has been attempted for this user
243      */
244     public boolean getAuthenticationAttempted() {
245         return authnAttempted;
246     }
247
248     /**
249      * Sets the ID of the authenticated user.
250      * 
251      * @param id The userid.
252      */
253     public void setPrincipalName(String id) {
254         principalName = id;
255     }
256
257     /**
258      * Returns the ID of the authenticated user.
259      * 
260      * @return the ID of the user, or <code>null</code> if authentication failed.
261      */
262     public String getPrincipalName() {
263         return principalName;
264     }
265
266     /**
267      * Gets the ProfileHandler URL.
268      * 
269      * @return the URL of the profile handler that is invoking the Authentication Manager.
270      */
271     public String getProfileHandlerURL() {
272         return profileHandlerURL;
273     }
274
275     /**
276      * Sets the ProfileHandler URL.
277      * 
278      * @param url The URL of the profile handler that invoked the AuthenticationManager/
279      */
280     public void setProfileHandlerURL(String url) {
281         profileHandlerURL = url;
282     }
283
284     /**
285      * Gets the authentication engine's URL.
286      * 
287      * @return the URL of the authentication engine
288      */
289     public String getAuthenticationEngineURL() {
290         return authnEngineURL;
291     }
292
293     /**
294      * Sets the authentication engine's URL.
295      * 
296      * @param url the URL of the authentication engine
297      */
298     public void setAuthenticationEngineURL(String url) {
299         authnEngineURL = url;
300     }
301
302     /**
303      * Gets the authentication instant.
304      * 
305      * @return The instant of authentication, or <code>null</code> if none was set.
306      */
307     public DateTime getAuthenticationInstant() {
308         return authnInstant;
309     }
310
311     /**
312      * Sets the authentication instant.
313      * 
314      * @param instant The instant of authentication.
315      */
316     public void setAuthenticationInstant(final DateTime instant) {
317         authnInstant = instant;
318     }
319
320     /**
321      * Gets the duration of authentication.
322      * 
323      * @return The duration of authentication, or zero if none was set.
324      */
325     public long getAuthenticationDuration() {
326         return authnDuration;
327     }
328
329     /**
330      * Sets the duration of authentication.
331      * 
332      * @param duration The duration of authentication.
333      */
334     public void setAuthenticationDuration(long duration) {
335         authnDuration = duration;
336     }
337
338     /**
339      * Gets the method used to authenticate the user.
340      * 
341      * @return The method used to authenticate the user.
342      */
343     public String getAuthenticationMethod() {
344         return authnMethod;
345     }
346
347     /**
348      * Sets the method used to authenticate the user.
349      * 
350      * @param method The method used to authenticate the user.
351      */
352     public void setAuthenticationMethod(String method) {
353         authnMethod = method;
354     }
355
356     /**
357      * Gets the {@link edu.internet2.middleware.shibboleth.idp.session.Session} ID.
358      * 
359      * @return the Session id
360      */
361     public String getSessionID() {
362         return sessionID;
363     }
364
365     /**
366      * Sets the {@link edu.internet2.middleware.shibboleth.idp.session.Session} ID.
367      * 
368      * @param id the Session ID
369      */
370     public void setSessionID(String id) {
371         sessionID = id;
372     }
373
374     /**
375      * Return the acceptable authentication handler URIs, in preference order, for authenticating this user. If no
376      * authentication methods are preferred the resultant list will be empty.
377      * 
378      * @return an list of authentication method identifiers
379      */
380     public List<String> getRequestedAuthenticationMethods() {
381         return requestAuthenticationMethods;
382     }
383 }