| /* |
| * 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.jsecurity.authc; |
| |
| import org.jsecurity.subject.PrincipalCollection; |
| |
| /** |
| * <code>AuthenticationInfo</code> represents a Subject's (aka user's) stored account information relevant to the |
| * authentication/log-in process only. |
| * <p/> |
| * It is important to understand the differnce between this interface and the |
| * {@link AuthenticationToken AuthenticationToken} interface. <code>AuthenticationInfo</code> implementations |
| * represent already-verified and stored account data, whereas an <code>AuthenticationToken</code> represents data |
| * submitted for any given login attempt (which may or may not successfully match the verified and stored account |
| * <code>AuthenticationInfo</code>). |
| * <p/> |
| * Because the act of authentication (log-in) is orthoganal to authorization (access control), this interface is |
| * intended to represent only the account data needed by JSecurity during an authentication attempt. JSecurity also |
| * has a parallel {@link org.jsecurity.authz.AuthorizationInfo AuthorizationInfo} interface for use during the |
| * authorization process that references access control data such as roles and permissions. |
| * <p/> |
| * But because many if not most {@link org.jsecurity.realm.Realm Realm}s store both sets of data for a Subject, it might be |
| * convenient for a <code>Realm</code> implementation to utilize an implementation of the {@link Account Account} |
| * interface instead, which is a convenience interface that combines both <code>AuthenticationInfo</code> and |
| * <code>AuthorizationInfo</code>. Whether you choose to implement these two interfaces separately or implement the one |
| * <code>Account</code> interface for a given <code>Realm</code> is entirely based on your application's needs or your |
| * preferences. |
| * |
| * <p><b>Pleae note:</b> Since JSecurity sometimes logs authentication operations, please ensure your AuthenticationInfo's |
| * <code>toString()</code> implementation does <em>not</em> print out account credentials (password, etc), as these might be viewable to |
| * someone reading your logs. This is good practice anyway, and account credentials should rarely (if ever) be printed |
| * out for any reason. If you're using JSecurity's default implementations of this interface, they only ever print the |
| * account {@link #getPrincipals() principals}, so you do not need to do anything additional.</p> |
| * |
| * @author Jeremy Haile |
| * @author Les Hazlewood |
| * @see org.jsecurity.authz.AuthorizationInfo AuthorizationInfo |
| * @see Account |
| * @since 0.9 |
| */ |
| public interface AuthenticationInfo { |
| |
| /** |
| * Returns all principals associated with the corresponding Subject. Each principal is an identifying piece of |
| * information useful to the application such as a username, or user id, a given name, etc - anything useful |
| * to the application to identify the current <code>Subject</code>. |
| * <p/> |
| * At least one of these attributes should be the account's 'primary' identifier, such as a username or unique |
| * user id. By convention, usually the first principal (that is, <code>getPrincipals().iterator().next()</code>) is the |
| * 'primary' one. |
| * <p/> |
| * The returned PrincipalCollection should <em>not</em> contain any credentials used to verify principals, such |
| * as passwords, private keys, etc. Those should be instead returned by {@link #getCredentials() getCredentials()}. |
| * |
| * @return all principals associated with the corresponding Subject. |
| */ |
| PrincipalCollection getPrincipals(); |
| |
| /** |
| * Returns the credentials associated with the corresponding Subject. A credential verifies one or more of the |
| * {@link #getPrincipals() principals} associated with the Subject, such as a password or private key. Credentials |
| * are used by JSecurity particularly during the authentication process to ensure that submitted credentials |
| * during a login attempt match exactly the credentials here in the <code>AuthenticationInfo</code> instance. |
| * |
| * @return the credentials associated with the corresponding Subject. |
| */ |
| Object getCredentials(); |
| |
| } |