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