001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *     http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    package org.apache.shiro.authc;
020    
021    import java.io.Serializable;
022    
023    /**
024     * <p>An <tt>AuthenticationToken</tt> is a consolidation of an account's principals and supporting
025     * credentials submitted by a user during an authentication attempt.
026     * <p/>
027     * <p>The token is submitted to an {@link Authenticator Authenticator} via the
028     * {@link Authenticator#authenticate(AuthenticationToken) authenticate(token)} method.  The
029     * Authenticator then executes the authentication/log-in process.
030     * <p/>
031     * <p>Common implementations of an <tt>AuthenticationToken</tt> would have username/password
032     * pairs, X.509 Certificate, PGP key, or anything else you can think of.  The token can be
033     * anything needed by an {@link Authenticator} to authenticate properly.
034     * <p/>
035     * <p>Because applications represent user data and credentials in different ways, implementations
036     * of this interface are application-specific.  You are free to acquire a user's principals and
037     * credentials however you wish (e.g. web form, Swing form, fingerprint identification, etc) and
038     * then submit them to the Shiro framework in the form of an implementation of this
039     * interface.
040     * <p/>
041     * <p>If your application's authentication process is  username/password based
042     * (like most), instead of implementing this interface yourself, take a look at the
043     * {@link UsernamePasswordToken UsernamePasswordToken} class, as it is probably sufficient for your needs.
044     * <p/>
045     * <p>RememberMe services are enabled for a token if they implement a sub-interface of this one, called
046     * {@link RememberMeAuthenticationToken RememberMeAuthenticationToken}.  Implement that interfac if you need
047     * RememberMe services (the <tt>UsernamePasswordToken</tt> already implements this interface).
048     * <p/>
049     * <p>If you are familiar with JAAS, an <tt>AuthenticationToken</tt> replaces the concept of a
050     * {@link javax.security.auth.callback.Callback}, and  defines meaningful behavior
051     * (<tt>Callback</tt> is just a marker interface, and of little use).  We
052     * also think the name <em>AuthenticationToken</em> more accurately reflects its true purpose
053     * in a login framework, whereas <em>Callback</em> is less obvious.
054     *
055     * @see RememberMeAuthenticationToken
056     * @see HostAuthenticationToken
057     * @see UsernamePasswordToken
058     * @since 0.1
059     */
060    public interface AuthenticationToken extends Serializable {
061    
062        /**
063         * Returns the account identity submitted during the authentication process.
064         * <p/>
065         * <p>Most application authentications are username/password based and have this
066         * object represent a username.  If this is the case for your application,
067         * take a look at the {@link UsernamePasswordToken UsernamePasswordToken}, as it is probably
068         * sufficient for your use.
069         * <p/>
070         * <p>Ultimately, the object returned is application specific and can represent
071         * any account identity (user id, X.509 certificate, etc).
072         *
073         * @return the account identity submitted during the authentication process.
074         * @see UsernamePasswordToken
075         */
076        Object getPrincipal();
077    
078        /**
079         * Returns the credentials submitted by the user during the authentication process that verifies
080         * the submitted {@link #getPrincipal() account identity}.
081         * <p/>
082         * <p>Most application authentications are username/password based and have this object
083         * represent a submitted password.  If this is the case for your application,
084         * take a look at the {@link UsernamePasswordToken UsernamePasswordToken}, as it is probably
085         * sufficient for your use.
086         * <p/>
087         * <p>Ultimately, the credentials Object returned is application specific and can represent
088         * any credential mechanism.
089         *
090         * @return the credential submitted by the user during the authentication process.
091         */
092        Object getCredentials();
093    
094    }