001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *     http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    package org.apache.shiro.authc;
020    
021    /**
022     * An Authenticator is responsible for authenticating accounts in an application.  It
023     * is one of the primary entry points into the Shiro API.
024     * <p/>
025     * Although not a requirement, there is usually a single 'master' Authenticator configured for
026     * an application.  Enabling Pluggable Authentication Module (PAM) behavior
027     * (Two Phase Commit, etc.) is usually achieved by the single {@code Authenticator} coordinating
028     * and interacting with an application-configured set of {@link org.apache.shiro.realm.Realm Realm}s.
029     * <p/>
030     * Note that most Shiro users will not interact with an {@code Authenticator} instance directly.
031     * Shiro's default architecture is based on an overall {@code SecurityManager} which typically
032     * wraps an {@code Authenticator} instance.
033     *
034     * @author Les Hazlewood
035     * @author Jeremy Haile
036     * @see org.apache.shiro.mgt.SecurityManager
037     * @see AbstractAuthenticator AbstractAuthenticator
038     * @see org.apache.shiro.authc.pam.ModularRealmAuthenticator ModularRealmAuthenticator
039     * @since 0.1
040     */
041    public interface Authenticator {
042    
043        /**
044         * Authenticates a user based on the submitted {@code AuthenticationToken}.
045         * <p/>
046         * If the authentication is successful, an {@link AuthenticationInfo} instance is returned that represents the
047         * user's account data relevant to Shiro.  This returned object is generally used in turn to construct a
048         * {@code Subject} representing a more complete security-specific 'view' of an account that also allows access to
049         * a {@code Session}.
050         *
051         * @param authenticationToken any representation of a user's principals and credentials submitted during an
052         *                            authentication attempt.
053         * @return the AuthenticationInfo representing the authenticating user's account data.
054         * @throws AuthenticationException if there is any problem during the authentication process.
055         *                                 See the specific exceptions listed below to as examples of what could happen
056         *                                 in order to accurately handle these problems and to notify the user in an
057         *                                 appropriate manner why the authentication attempt failed.  Realize an
058         *                                 implementation of this interface may or may not throw those listed or may
059         *                                 throw other AuthenticationExceptions, but the list shows the most common ones.
060         * @see ExpiredCredentialsException
061         * @see IncorrectCredentialsException
062         * @see ExcessiveAttemptsException
063         * @see LockedAccountException
064         * @see ConcurrentAccessException
065         * @see UnknownAccountException
066         */
067        public AuthenticationInfo authenticate(AuthenticationToken authenticationToken)
068                throws AuthenticationException;
069    }