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 module hunt.shiro.authc.Authenticator; 20 21 import hunt.shiro.authc.AuthenticationInfo; 22 import hunt.shiro.authc.AuthenticationToken; 23 24 /** 25 * An Authenticator is responsible for authenticating accounts in an application. It 26 * is one of the primary entry points into the Shiro API. 27 * <p/> 28 * Although not a requirement, there is usually a single 'master' Authenticator configured for 29 * an application. Enabling Pluggable Authentication Module (PAM) behavior 30 * (Two Phase Commit, etc.) is usually achieved by the single {@code Authenticator} coordinating 31 * and interacting with an application-configured set of {@link hunt.shiro.realm.Realm Realm}s. 32 * <p/> 33 * Note that most Shiro users will not interact with an {@code Authenticator} instance directly. 34 * Shiro's default architecture is based on an overall {@code SecurityManager} which typically 35 * wraps an {@code Authenticator} instance. 36 * 37 * @see hunt.shiro.mgt.SecurityManager 38 * @see AbstractAuthenticator AbstractAuthenticator 39 * @see hunt.shiro.authc.pam.ModularRealmAuthenticator ModularRealmAuthenticator 40 */ 41 interface Authenticator { 42 43 /** 44 * Authenticates a user based on the submitted {@code AuthenticationToken}. 45 * <p/> 46 * If the authentication is successful, an {@link AuthenticationInfo} instance is returned that represents the 47 * user's account data relevant to Shiro. This returned object is generally used in turn to construct a 48 * {@code Subject} representing a more complete security-specific 'view' of an account that also allows access to 49 * a {@code Session}. 50 * 51 * @param authenticationToken any representation of a user's principals and credentials submitted during an 52 * authentication attempt. 53 * @return the AuthenticationInfo representing the authenticating user's account data. 54 * @throws AuthenticationException if there is any problem during the authentication process. 55 * See the specific exceptions listed below to as examples of what could happen 56 * in order to accurately handle these problems and to notify the user in an 57 * appropriate manner why the authentication attempt failed. Realize an 58 * implementation of this interface may or may not throw those listed or may 59 * throw other AuthenticationExceptions, but the list shows the most common ones. 60 * @see ExpiredCredentialsException 61 * @see IncorrectCredentialsException 62 * @see ExcessiveAttemptsException 63 * @see LockedAccountException 64 * @see ConcurrentAccessException 65 * @see UnknownAccountException 66 */ 67 AuthenticationInfo authenticate(AuthenticationToken authenticationToken); 68 }