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.mgt;
20
21 import org.apache.shiro.authc.AuthenticationException;
22 import org.apache.shiro.authc.AuthenticationInfo;
23 import org.apache.shiro.authc.AuthenticationToken;
24 import org.apache.shiro.subject.PrincipalCollection;
25 import org.apache.shiro.subject.Subject;
26 import org.apache.shiro.subject.SubjectContext;
27
28 /**
29 * A RememberMeManager is responsible for remembering a Subject's identity across that Subject's sessions with
30 * the application.
31 *
32 * @since 0.9
33 */
34 public interface RememberMeManager {
35
36 /**
37 * Based on the specified subject context map being used to build a Subject instance, returns any previously
38 * remembered principals for the subject for automatic identity association (aka 'Remember Me').
39 * <p/>
40 * The context map is usually populated by a {@link Subject.Builder} implementation.
41 * See the {@link SubjectFactory} class constants for Shiro's known map keys.
42 *
43 * @param subjectContext the contextual data, usually provided by a {@link Subject.Builder} implementation, that
44 * is being used to construct a {@link Subject} instance.
45 * @return he remembered principals or {@code null} if none could be acquired.
46 * @since 1.0
47 */
48 PrincipalCollection getRememberedPrincipals(SubjectContext subjectContext);
49
50 /**
51 * Forgets any remembered identity corresponding to the subject context map being used to build a subject instance.
52 * <p/>
53 * The context map is usually populated by a {@link Subject.Builder} implementation.
54 * See the {@link SubjectFactory} class constants for Shiro's known map keys.
55 *
56 * @param subjectContext the contextual data, usually provided by a {@link Subject.Builder} implementation, that
57 * is being used to construct a {@link Subject} instance.
58 * @since 1.0
59 */
60 void forgetIdentity(SubjectContext subjectContext);
61
62 /**
63 * Reacts to a successful authentication attempt, typically saving the principals to be retrieved ('remembered')
64 * for future system access.
65 *
66 * @param subject the subject that executed a successful authentication attempt
67 * @param token the authentication token submitted resulting in a successful authentication attempt
68 * @param info the authenticationInfo returned as a result of the successful authentication attempt
69 * @since 1.0
70 */
71 void onSuccessfulLogin(Subject subject, AuthenticationToken token, AuthenticationInfo info);
72
73 /**
74 * Reacts to a failed authentication attempt, typically by forgetting any previously remembered principals for the
75 * Subject.
76 *
77 * @param subject the subject that executed the failed authentication attempt
78 * @param token the authentication token submitted resulting in the failed authentication attempt
79 * @param ae the authentication exception thrown as a result of the failed authentication attempt
80 * @since 1.0
81 */
82 void onFailedLogin(Subject subject, AuthenticationToken token, AuthenticationException ae);
83
84 /**
85 * Reacts to a Subject logging out of the application, typically by forgetting any previously remembered
86 * principals for the Subject.
87 *
88 * @param subject the subject logging out.
89 * @since 1.0
90 */
91 void onLogout(Subject subject);
92 }