org.apache.shiro.authc.AuthenticationToken Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.shiro.authc;
import java.io.Serializable;
/**
* An AuthenticationToken is a consolidation of an account's principals and supporting
* credentials submitted by a user during an authentication attempt.
*
* The token is submitted to an {@link Authenticator Authenticator} via the
* {@link Authenticator#authenticate(AuthenticationToken) authenticate(token)} method. The
* Authenticator then executes the authentication/log-in process.
*
* Common implementations of an AuthenticationToken would have username/password
* pairs, X.509 Certificate, PGP key, or anything else you can think of. The token can be
* anything needed by an {@link Authenticator} to authenticate properly.
*
* Because applications represent user data and credentials in different ways, implementations
* of this interface are application-specific. You are free to acquire a user's principals and
* credentials however you wish (e.g. web form, Swing form, fingerprint identification, etc) and
* then submit them to the Shiro framework in the form of an implementation of this
* interface.
*
* If your application's authentication process is username/password based
* (like most), instead of implementing this interface yourself, take a look at the
* {@link UsernamePasswordToken UsernamePasswordToken} class, as it is probably sufficient for your needs.
*
* RememberMe services are enabled for a token if they implement a sub-interface of this one, called
* {@link RememberMeAuthenticationToken RememberMeAuthenticationToken}. Implement that interfac if you need
* RememberMe services (the UsernamePasswordToken already implements this interface).
*
* If you are familiar with JAAS, an AuthenticationToken replaces the concept of a
* {@link javax.security.auth.callback.Callback}, and defines meaningful behavior
* (Callback is just a marker interface, and of little use). We
* also think the name AuthenticationToken more accurately reflects its true purpose
* in a login framework, whereas Callback is less obvious.
*
* @see RememberMeAuthenticationToken
* @see HostAuthenticationToken
* @see UsernamePasswordToken
* @since 0.1
*/
public interface AuthenticationToken extends Serializable {
/**
* Returns the account identity submitted during the authentication process.
*
* Most application authentications are username/password based and have this
* object represent a username. If this is the case for your application,
* take a look at the {@link UsernamePasswordToken UsernamePasswordToken}, as it is probably
* sufficient for your use.
*
* Ultimately, the object returned is application specific and can represent
* any account identity (user id, X.509 certificate, etc).
*
* @return the account identity submitted during the authentication process.
* @see UsernamePasswordToken
*/
Object getPrincipal();
/**
* Returns the credentials submitted by the user during the authentication process that verifies
* the submitted {@link #getPrincipal() account identity}.
*
* Most application authentications are username/password based and have this object
* represent a submitted password. If this is the case for your application,
* take a look at the {@link UsernamePasswordToken UsernamePasswordToken}, as it is probably
* sufficient for your use.
*
* Ultimately, the credentials Object returned is application specific and can represent
* any credential mechanism.
*
* @return the credential submitted by the user during the authentication process.
*/
Object getCredentials();
}