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 }