View Javadoc

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