View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.shiro.authc;
20  
21  import java.io.Serializable;
22  
23  /**
24   * <p>An <tt>AuthenticationToken</tt> is a consolidation of an account's principals and supporting
25   * credentials submitted by a user during an authentication attempt.
26   * <p/>
27   * <p>The token is submitted to an {@link Authenticator Authenticator} via the
28   * {@link Authenticator#authenticate(AuthenticationToken) authenticate(token)} method.  The
29   * Authenticator then executes the authentication/log-in process.
30   * <p/>
31   * <p>Common implementations of an <tt>AuthenticationToken</tt> would have username/password
32   * pairs, X.509 Certificate, PGP key, or anything else you can think of.  The token can be
33   * anything needed by an {@link Authenticator} to authenticate properly.
34   * <p/>
35   * <p>Because applications represent user data and credentials in different ways, implementations
36   * of this interface are application-specific.  You are free to acquire a user's principals and
37   * credentials however you wish (e.g. web form, Swing form, fingerprint identification, etc) and
38   * then submit them to the Shiro framework in the form of an implementation of this
39   * interface.
40   * <p/>
41   * <p>If your application's authentication process is  username/password based
42   * (like most), instead of implementing this interface yourself, take a look at the
43   * {@link UsernamePasswordToken UsernamePasswordToken} class, as it is probably sufficient for your needs.
44   * <p/>
45   * <p>RememberMe services are enabled for a token if they implement a sub-interface of this one, called
46   * {@link RememberMeAuthenticationToken RememberMeAuthenticationToken}.  Implement that interface if you need
47   * RememberMe services (the <tt>UsernamePasswordToken</tt> already implements this interface).
48   * <p/>
49   * <p>If you are familiar with JAAS, an <tt>AuthenticationToken</tt> replaces the concept of a
50   * {@link javax.security.auth.callback.Callback}, and  defines meaningful behavior
51   * (<tt>Callback</tt> is just a marker interface, and of little use).  We
52   * also think the name <em>AuthenticationToken</em> more accurately reflects its true purpose
53   * in a login framework, whereas <em>Callback</em> is less obvious.
54   *
55   * @see RememberMeAuthenticationToken
56   * @see HostAuthenticationToken
57   * @see UsernamePasswordToken
58   * @since 0.1
59   */
60  public interface AuthenticationToken extends Serializable {
61  
62      /**
63       * Returns the account identity submitted during the authentication process.
64       * <p/>
65       * <p>Most application authentications are username/password based and have this
66       * object represent a username.  If this is the case for your application,
67       * take a look at the {@link UsernamePasswordToken UsernamePasswordToken}, as it is probably
68       * sufficient for your use.
69       * <p/>
70       * <p>Ultimately, the object returned is application specific and can represent
71       * any account identity (user id, X.509 certificate, etc).
72       *
73       * @return the account identity submitted during the authentication process.
74       * @see UsernamePasswordToken
75       */
76      Object getPrincipal();
77  
78      /**
79       * Returns the credentials submitted by the user during the authentication process that verifies
80       * the submitted {@link #getPrincipal() account identity}.
81       * <p/>
82       * <p>Most application authentications are username/password based and have this object
83       * represent a submitted password.  If this is the case for your application,
84       * take a look at the {@link UsernamePasswordToken UsernamePasswordToken}, as it is probably
85       * sufficient for your use.
86       * <p/>
87       * <p>Ultimately, the credentials Object returned is application specific and can represent
88       * any credential mechanism.
89       *
90       * @return the credential submitted by the user during the authentication process.
91       */
92      Object getCredentials();
93  
94  }