View Javadoc

1   /* 
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * 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  package org.apache.jetspeed.security.spi;
18  
19  import java.util.Collection;
20  
21  import org.apache.jetspeed.security.SecurityException;
22  import org.apache.jetspeed.security.om.InternalCredential;
23  import org.apache.jetspeed.security.om.InternalUserPrincipal;
24  
25  /***
26   * <p>
27   * Callback component interface used by {@link org.apache.jetspeed.security.spi.impl.DefaultCredentialHandler DefaultCredentialHandler} 
28   * allowing injecting custom logic on certain events of the {@link InternalCredential}.
29   * </p>
30   * 
31   * @author <a href="mailto:ate@apache.org">Ate Douma</a>
32   * @version $Id: InternalPasswordCredentialInterceptor.java 291016 2005-09-22 21:19:36Z ate $
33   */
34  public interface InternalPasswordCredentialInterceptor
35  {
36      /***
37       * <p>
38       * Invoked after a password credential is loaded from the persistent store.</p>
39       * <p>
40       * If true is returned the credential is expected to be updated and its changes will be stored again.</p>
41       * <p>
42       * A thrown SecurityException will be logged as an error and result in the credential to be ignored 
43       * as if not existing (like for authentication).</p>
44       * 
45       * @param pcProvider provides callback access to for instance the configured {@link CredentialPasswordEncoder} and
46       * {@link CredentialPasswordValidator}
47       * @param userName the name of the principal to which the credential belongs
48       * @param credential the credential just loaded from the persistent store
49       * @return true if the credential is updated
50       * @throws SecurityException
51       * @see org.apache.jetspeed.security.spi.impl.DefaultCredentialHandler#getPasswordCredential(InternalUserPrincipal, String)
52       * @see org.apache.jetspeed.security.spi.impl.DefaultCredentialHandler#setPasswordExpiration(String, java.sql.Date)
53       */
54      boolean afterLoad(PasswordCredentialProvider pcProvider, String userName, InternalCredential credential) throws SecurityException;
55  
56      /***
57       * <p>
58       * Invoked during authentication after the provided password is compared against the one retrieved from
59       * the InternalCredential.</p>
60       * <p>
61       * If true is returned, the credential is expected to be updated and its {@link InternalCredential#isEnabled() enabled}
62       * and {@link InternalCredential#isExpired() expired} flags will checked if the credential is (still) valid.</p>
63       * <p>
64       * Note: the enabled and expired flags are <em>only</em> checked if this method returns true.</p>
65       * <p>
66       * A thrown SecurityException will be passed on to the authentication requestor.</p>
67       *  
68       * @param internalUser the user to which the credential belongs
69       * @param userName the name of the principal to which the credential belongs
70       * @param credential the credential of the user
71       * @param authenticated true if the provided password matches the value of the credential
72       * @return true if the credential is updated
73       * @throws SecurityException
74       * @see org.apache.jetspeed.security.spi.impl.DefaultCredentialHandler#authenticate(String, String)
75       */
76      boolean afterAuthenticated(InternalUserPrincipal internalUser, String userName, InternalCredential credential, boolean authenticated) throws SecurityException;
77  
78      /***
79       * <p>
80       * Invoked when the first password credential is to be saved for a user.</p>
81       * <p>
82       * This callback method can be used to set default values like the {@link InternalCredential#getExpirationDate() expiration date}.</p>
83       * <p>
84       * A thrown SecurityException is passed on to the new password requestor.</p>
85       * 
86       * @param internalUser the user to which the credential belongs
87       * @param credentials the collection of credentials which will set on the user after (already contains the new credential)
88       * @param userName the name of the principal to which the credential belongs
89       * @param credential the credential of the user
90       * @param password the new password value (already set on the new credential)
91       * @throws SecurityException
92       * @see org.apache.jetspeed.security.spi.impl.DefaultCredentialHandler#setPassword(String, String, String)
93       */
94      void beforeCreate(InternalUserPrincipal internalUser, Collection credentials, String userName, InternalCredential credential, String password) throws SecurityException;
95  
96      /***
97       * <p>
98       * Invoked when a new password value is to be saved for a user.</p>
99       * <p>
100      * The new password value is <em>not</em> yet set on the provided credential when this callback is invoked. This allows
101      * custom history maintenance and/or auditing to be performed.</p>
102      * <p>
103      * The provided authenticated flag can be used to differentiate between a new password value set directly by a user
104      * itself or through an administrative interface.</p>
105      * <p>
106      * After this callback is invoked, the specified password value will be set, as well as a reset of the
107      * {@link InternalCredential#isUpdateRequired() updateRequired} flag, before the credential is saved.</p>
108      * <p>
109      * A thrown SecurityException is passed on to the set password requestor.</p>
110      * 
111      * @param internalUser the user to which the credential belongs
112      * @param credentials the collection of credentials which will set on the user after (already contains the new credential)
113      * @param userName the name of the principal to which the credential belongs
114      * @param credential the credential of the user
115      * @param password the new password value (already set on the new credential)
116      * @param authenticated true if the new password value is provided by the user directly
117      * @throws SecurityException
118      * @see org.apache.jetspeed.security.spi.impl.DefaultCredentialHandler#setPassword(String, String, String)
119      */
120     void beforeSetPassword(InternalUserPrincipal internalUser, Collection credentials, String userName, InternalCredential credential, String password, boolean authenticated) throws SecurityException;
121 }