View Javadoc

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