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 */
019package org.apache.shiro.authc;
020
021import 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 interface 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 */
060public 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}