001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.jetspeed.security.spi;
018:
019: import java.util.Collection;
020:
021: import org.apache.jetspeed.security.SecurityException;
022: import org.apache.jetspeed.security.om.InternalCredential;
023: import org.apache.jetspeed.security.om.InternalUserPrincipal;
024:
025: /**
026: * <p>
027: * Callback component interface used by {@link org.apache.jetspeed.security.spi.impl.DefaultCredentialHandler DefaultCredentialHandler}
028: * allowing injecting custom logic on certain events of the {@link InternalCredential}.
029: * </p>
030: *
031: * @author <a href="mailto:ate@apache.org">Ate Douma</a>
032: * @version $Id: InternalPasswordCredentialInterceptor.java 291016 2005-09-22 21:19:36Z ate $
033: */
034: public interface InternalPasswordCredentialInterceptor {
035: /**
036: * <p>
037: * Invoked after a password credential is loaded from the persistent store.</p>
038: * <p>
039: * If true is returned the credential is expected to be updated and its changes will be stored again.</p>
040: * <p>
041: * A thrown SecurityException will be logged as an error and result in the credential to be ignored
042: * as if not existing (like for authentication).</p>
043: *
044: * @param pcProvider provides callback access to for instance the configured {@link CredentialPasswordEncoder} and
045: * {@link CredentialPasswordValidator}
046: * @param userName the name of the principal to which the credential belongs
047: * @param credential the credential just loaded from the persistent store
048: * @return true if the credential is updated
049: * @throws SecurityException
050: * @see org.apache.jetspeed.security.spi.impl.DefaultCredentialHandler#getPasswordCredential(InternalUserPrincipal, String)
051: * @see org.apache.jetspeed.security.spi.impl.DefaultCredentialHandler#setPasswordExpiration(String, java.sql.Date)
052: */
053: boolean afterLoad(PasswordCredentialProvider pcProvider,
054: String userName, InternalCredential credential)
055: throws SecurityException;
056:
057: /**
058: * <p>
059: * Invoked during authentication after the provided password is compared against the one retrieved from
060: * the InternalCredential.</p>
061: * <p>
062: * If true is returned, the credential is expected to be updated and its {@link InternalCredential#isEnabled() enabled}
063: * and {@link InternalCredential#isExpired() expired} flags will checked if the credential is (still) valid.</p>
064: * <p>
065: * Note: the enabled and expired flags are <em>only</em> checked if this method returns true.</p>
066: * <p>
067: * A thrown SecurityException will be passed on to the authentication requestor.</p>
068: *
069: * @param internalUser the user to which the credential belongs
070: * @param userName the name of the principal to which the credential belongs
071: * @param credential the credential of the user
072: * @param authenticated true if the provided password matches the value of the credential
073: * @return true if the credential is updated
074: * @throws SecurityException
075: * @see org.apache.jetspeed.security.spi.impl.DefaultCredentialHandler#authenticate(String, String)
076: */
077: boolean afterAuthenticated(InternalUserPrincipal internalUser,
078: String userName, InternalCredential credential,
079: boolean authenticated) throws SecurityException;
080:
081: /**
082: * <p>
083: * Invoked when the first password credential is to be saved for a user.</p>
084: * <p>
085: * This callback method can be used to set default values like the {@link InternalCredential#getExpirationDate() expiration date}.</p>
086: * <p>
087: * A thrown SecurityException is passed on to the new password requestor.</p>
088: *
089: * @param internalUser the user to which the credential belongs
090: * @param credentials the collection of credentials which will set on the user after (already contains the new credential)
091: * @param userName the name of the principal to which the credential belongs
092: * @param credential the credential of the user
093: * @param password the new password value (already set on the new credential)
094: * @throws SecurityException
095: * @see org.apache.jetspeed.security.spi.impl.DefaultCredentialHandler#setPassword(String, String, String)
096: */
097: void beforeCreate(InternalUserPrincipal internalUser,
098: Collection credentials, String userName,
099: InternalCredential credential, String password)
100: throws SecurityException;
101:
102: /**
103: * <p>
104: * Invoked when a new password value is to be saved for a user.</p>
105: * <p>
106: * The new password value is <em>not</em> yet set on the provided credential when this callback is invoked. This allows
107: * custom history maintenance and/or auditing to be performed.</p>
108: * <p>
109: * The provided authenticated flag can be used to differentiate between a new password value set directly by a user
110: * itself or through an administrative interface.</p>
111: * <p>
112: * After this callback is invoked, the specified password value will be set, as well as a reset of the
113: * {@link InternalCredential#isUpdateRequired() updateRequired} flag, before the credential is saved.</p>
114: * <p>
115: * A thrown SecurityException is passed on to the set password requestor.</p>
116: *
117: * @param internalUser the user to which the credential belongs
118: * @param credentials the collection of credentials which will set on the user after (already contains the new credential)
119: * @param userName the name of the principal to which the credential belongs
120: * @param credential the credential of the user
121: * @param password the new password value (already set on the new credential)
122: * @param authenticated true if the new password value is provided by the user directly
123: * @throws SecurityException
124: * @see org.apache.jetspeed.security.spi.impl.DefaultCredentialHandler#setPassword(String, String, String)
125: */
126: void beforeSetPassword(InternalUserPrincipal internalUser,
127: Collection credentials, String userName,
128: InternalCredential credential, String password,
129: boolean authenticated) throws SecurityException;
130: }
|