LoginContext xref

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