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 */
019package 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 * @see org.apache.shiro.mgt.SecurityManager
035 * @see AbstractAuthenticator AbstractAuthenticator
036 * @see org.apache.shiro.authc.pam.ModularRealmAuthenticator ModularRealmAuthenticator
037 * @since 0.1
038 */
039public interface Authenticator {
040
041    /**
042     * Authenticates a user based on the submitted {@code AuthenticationToken}.
043     * <p/>
044     * If the authentication is successful, an {@link AuthenticationInfo} instance is returned that represents the
045     * user's account data relevant to Shiro.  This returned object is generally used in turn to construct a
046     * {@code Subject} representing a more complete security-specific 'view' of an account that also allows access to
047     * a {@code Session}.
048     *
049     * @param authenticationToken any representation of a user's principals and credentials submitted during an
050     *                            authentication attempt.
051     * @return the AuthenticationInfo representing the authenticating user's account data.
052     * @throws AuthenticationException if there is any problem during the authentication process.
053     *                                 See the specific exceptions listed below to as examples of what could happen
054     *                                 in order to accurately handle these problems and to notify the user in an
055     *                                 appropriate manner why the authentication attempt failed.  Realize an
056     *                                 implementation of this interface may or may not throw those listed or may
057     *                                 throw other AuthenticationExceptions, but the list shows the most common ones.
058     * @see ExpiredCredentialsException
059     * @see IncorrectCredentialsException
060     * @see ExcessiveAttemptsException
061     * @see LockedAccountException
062     * @see ConcurrentAccessException
063     * @see UnknownAccountException
064     */
065    AuthenticationInfo authenticate(AuthenticationToken authenticationToken)
066            throws AuthenticationException;
067}