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 * @author Les Hazlewood
056 * @see RememberMeAuthenticationToken
057 * @see HostAuthenticationToken
058 * @see UsernamePasswordToken
059 * @since 0.1
060 */
061 public interface AuthenticationToken extends Serializable {
062
063 /**
064 * Returns the account identity submitted during the authentication process.
065 * <p/>
066 * <p>Most application authentications are username/password based and have this
067 * object represent a username. If this is the case for your application,
068 * take a look at the {@link UsernamePasswordToken UsernamePasswordToken}, as it is probably
069 * sufficient for your use.
070 * <p/>
071 * <p>Ultimately, the object returned is application specific and can represent
072 * any account identity (user id, X.509 certificate, etc).
073 *
074 * @return the account identity submitted during the authentication process.
075 * @see UsernamePasswordToken
076 */
077 Object getPrincipal();
078
079 /**
080 * Returns the credentials submitted by the user during the authentication process that verifies
081 * the submitted {@link #getPrincipal() account identity}.
082 * <p/>
083 * <p>Most application authentications are username/password based and have this object
084 * represent a submitted password. If this is the case for your application,
085 * take a look at the {@link UsernamePasswordToken UsernamePasswordToken}, as it is probably
086 * sufficient for your use.
087 * <p/>
088 * <p>Ultimately, the credentials Object returned is application specific and can represent
089 * any credential mechanism.
090 *
091 * @return the credential submitted by the user during the authentication process.
092 */
093 Object getCredentials();
094
095 }