hunt.shiro.authc.AuthenticationInfo source code

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 module hunt.shiro.authc.AuthenticationInfo;
21 
22 import hunt.shiro.subject.PrincipalCollection;
23 
24 import hunt.util.Common;
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 hunt.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 hunt.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>Please 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 hunt.shiro.authz.AuthorizationInfo AuthorizationInfo
55  * @see Account
56  */
57 interface AuthenticationInfo {
58 
59     /**
60      * Returns all principals associated with the corresponding Subject.  Each principal is an identifying piece of
61      * information useful to the application such as a username, or user id, a given name, etc - anything useful
62      * to the application to identify the current <code>Subject</code>.
63      * <p/>
64      * The returned PrincipalCollection should <em>not</em> contain any credentials used to verify principals, such
65      * as passwords, private keys, etc.  Those should be instead returned by {@link #getCredentials() getCredentials()}.
66      *
67      * @return all principals associated with the corresponding Subject.
68      */
69     PrincipalCollection getPrincipals();
70 
71     /**
72      * Returns the credentials associated with the corresponding Subject.  A credential verifies one or more of the
73      * {@link #getPrincipals() principals} associated with the Subject, such as a password or private key.  Credentials
74      * are used by Shiro particularly during the authentication process to ensure that submitted credentials
75      * during a login attempt match exactly the credentials here in the <code>AuthenticationInfo</code> instance.
76      *
77      * @return the credentials associated with the corresponding Subject.
78      */
79     Object getCredentials();
80 
81 }