| /* |
| * 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.ki.authc; |
| |
| import java.io.Serializable; |
| |
| /** |
| * <p>An <tt>AuthenticationToken</tt> is a consolidation of an account's principals and supporting |
| * credentials submitted by a user during an authentication attempt. |
| * |
| * <p>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. |
| * |
| * <p>Common implementations of an <tt>AuthenticationToken</tt> 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. |
| * |
| * <p>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 Ki framework in the form of an implementation of this |
| * interface. |
| * |
| * <p>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. |
| * |
| * <p>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 <tt>UsernamePasswordToken</tt> already implements this interface). |
| * |
| * <p>If you are familiar with JAAS, an <tt>AuthenticationToken</tt> replaces the concept of a |
| * {@link javax.security.auth.callback.Callback}, and defines meaningful behavior |
| * (<tt>Callback</tt> is just a marker interface, and of little use). We |
| * also think the name <em>AuthenticationToken</em> more accurately reflects its true purpose |
| * in a login framework, whereas <em>Callback</em> is less obvious. |
| * |
| * @author Les Hazlewood |
| * @see RememberMeAuthenticationToken |
| * @see InetAuthenticationToken |
| * @see UsernamePasswordToken |
| * @since 0.1 |
| */ |
| public interface AuthenticationToken extends Serializable { |
| |
| /** |
| * Returns the account identity submitted during the authentication process. |
| * |
| * <p>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. |
| * |
| * <p>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}. |
| * |
| * <p>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. |
| * |
| * <p>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(); |
| |
| } |