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
20 package org.apache.shiro.authc;
21
22 import org.apache.shiro.subject.PrincipalCollection;
23
24 import java.io.Serializable;
25
26 /**
27 * <code>AuthenticationInfo</code> represents a Subject's (aka user's) stored account information relevant to the
28 * authentication/log-in process only.
29 * <p/>
30 * It is important to understand the difference between this interface and the
31 * {@link AuthenticationToken AuthenticationToken} interface. <code>AuthenticationInfo</code> implementations
32 * represent already-verified and stored account data, whereas an <code>AuthenticationToken</code> represents data
33 * submitted for any given login attempt (which may or may not successfully match the verified and stored account
34 * <code>AuthenticationInfo</code>).
35 * <p/>
36 * Because the act of authentication (log-in) is orthogonal to authorization (access control), this interface is
37 * intended to represent only the account data needed by Shiro during an authentication attempt. Shiro also
38 * has a parallel {@link org.apache.shiro.authz.AuthorizationInfo AuthorizationInfo} interface for use during the
39 * authorization process that references access control data such as roles and permissions.
40 * <p/>
41 * But because many if not most {@link org.apache.shiro.realm.Realm Realm}s store both sets of data for a Subject, it might be
42 * convenient for a <code>Realm</code> implementation to utilize an implementation of the {@link Account Account}
43 * interface instead, which is a convenience interface that combines both <code>AuthenticationInfo</code> and
44 * <code>AuthorizationInfo</code>. Whether you choose to implement these two interfaces separately or implement the one
45 * <code>Account</code> interface for a given <code>Realm</code> is entirely based on your application's needs or your
46 * preferences.
47 * <p/>
48 * <p><b>Pleae note:</b> Since Shiro sometimes logs authentication operations, please ensure your AuthenticationInfo's
49 * <code>toString()</code> implementation does <em>not</em> print out account credentials (password, etc), as these might be viewable to
50 * someone reading your logs. This is good practice anyway, and account credentials should rarely (if ever) be printed
51 * out for any reason. If you're using Shiro's default implementations of this interface, they only ever print the
52 * account {@link #getPrincipals() principals}, so you do not need to do anything additional.</p>
53 *
54 * @see org.apache.shiro.authz.AuthorizationInfo AuthorizationInfo
55 * @see Account
56 * @since 0.9
57 */
58 public interface AuthenticationInfo extends Serializable {
59
60 /**
61 * Returns all principals associated with the corresponding Subject. Each principal is an identifying piece of
62 * information useful to the application such as a username, or user id, a given name, etc - anything useful
63 * to the application to identify the current <code>Subject</code>.
64 * <p/>
65 * The returned PrincipalCollection should <em>not</em> contain any credentials used to verify principals, such
66 * as passwords, private keys, etc. Those should be instead returned by {@link #getCredentials() getCredentials()}.
67 *
68 * @return all principals associated with the corresponding Subject.
69 */
70 PrincipalCollection getPrincipals();
71
72 /**
73 * Returns the credentials associated with the corresponding Subject. A credential verifies one or more of the
74 * {@link #getPrincipals() principals} associated with the Subject, such as a password or private key. Credentials
75 * are used by Shiro particularly during the authentication process to ensure that submitted credentials
76 * during a login attempt match exactly the credentials here in the <code>AuthenticationInfo</code> instance.
77 *
78 * @return the credentials associated with the corresponding Subject.
79 */
80 Object getCredentials();
81
82 }