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.AuthenticationToken;
23 import org.apache.shiro.authc.Authenticator;
24 import org.apache.shiro.authz.Authorizer;
25 import org.apache.shiro.session.mgt.SessionManager;
26 import org.apache.shiro.subject.Subject;
27 import org.apache.shiro.subject.SubjectContext;
28
29
30 /**
31 * A {@code SecurityManager} executes all security operations for <em>all</em> Subjects (aka users) across a
32 * single application.
33 * <p/>
34 * The interface itself primarily exists as a convenience - it extends the {@link org.apache.shiro.authc.Authenticator},
35 * {@link Authorizer}, and {@link SessionManager} interfaces, thereby consolidating
36 * these behaviors into a single point of reference. For most Shiro usages, this simplifies configuration and
37 * tends to be a more convenient approach than referencing {@code Authenticator}, {@code Authorizer}, and
38 * {@code SessionManager} instances separately; instead one only needs to interact with a single
39 * {@code SecurityManager} instance.
40 * <p/>
41 * In addition to the above three interfaces, this interface provides a number of methods supporting
42 * {@link Subject} behavior. A {@link org.apache.shiro.subject.Subject Subject} executes
43 * authentication, authorization, and session operations for a <em>single</em> user, and as such can only be
44 * managed by {@code A SecurityManager} which is aware of all three functions. The three parent interfaces on the
45 * other hand do not 'know' about {@code Subject}s to ensure a clean separation of concerns.
46 * <p/>
47 * <b>Usage Note</b>: In actuality the large majority of application programmers won't interact with a SecurityManager
48 * very often, if at all. <em>Most</em> application programmers only care about security operations for the currently
49 * executing user, usually attained by calling
50 * {@link org.apache.shiro.SecurityUtils#getSubject() SecurityUtils.getSubject()}.
51 * <p/>
52 * Framework developers on the other hand might find working with an actual SecurityManager useful.
53 *
54 * @see org.apache.shiro.mgt.DefaultSecurityManager
55 * @since 0.2
56 */
57 public interface SecurityManager extends Authenticator, Authorizer, SessionManager {
58
59 /**
60 * Logs in the specified Subject using the given {@code authenticationToken}, returning an updated Subject
61 * instance reflecting the authenticated state if successful or throwing {@code AuthenticationException} if it is
62 * not.
63 * <p/>
64 * Note that most application developers should probably not call this method directly unless they have a good
65 * reason for doing so. The preferred way to log in a Subject is to call
66 * <code>subject.{@link org.apache.shiro.subject.Subject#login login(authenticationToken)}</code> (usually after
67 * acquiring the Subject by calling {@link org.apache.shiro.SecurityUtils#getSubject() SecurityUtils.getSubject()}).
68 * <p/>
69 * Framework developers on the other hand might find calling this method directly useful in certain cases.
70 *
71 * @param subject the subject against which the authentication attempt will occur
72 * @param authenticationToken the token representing the Subject's principal(s) and credential(s)
73 * @return the subject instance reflecting the authenticated state after a successful attempt
74 * @throws AuthenticationException if the login attempt failed.
75 * @since 1.0
76 */
77 Subject login(Subject subject, AuthenticationToken authenticationToken) throws AuthenticationException;
78
79 /**
80 * Logs out the specified Subject from the system.
81 * <p/>
82 * Note that most application developers should not call this method unless they have a good reason for doing
83 * so. The preferred way to logout a Subject is to call
84 * <code>{@link org.apache.shiro.subject.Subject#logout Subject.logout()}</code>, not the
85 * {@code SecurityManager} directly.
86 * <p/>
87 * Framework developers on the other hand might find calling this method directly useful in certain cases.
88 *
89 * @param subject the subject to log out.
90 * @since 1.0
91 */
92 void logout(Subject subject);
93
94 /**
95 * Creates a {@code Subject} instance reflecting the specified contextual data.
96 * <p/>
97 * The context can be anything needed by this {@code SecurityManager} to construct a {@code Subject} instance.
98 * Most Shiro end-users will never call this method - it exists primarily for
99 * framework development and to support any underlying custom {@link SubjectFactory SubjectFactory} implementations
100 * that may be used by the {@code SecurityManager}.
101 * <h4>Usage</h4>
102 * After calling this method, the returned instance is <em>not</em> bound to the application for further use.
103 * Callers are expected to know that {@code Subject} instances have local scope only and any
104 * other further use beyond the calling method must be managed explicitly.
105 *
106 * @param context any data needed to direct how the Subject should be constructed.
107 * @return the {@code Subject} instance reflecting the specified initialization data.
108 * @see SubjectFactory#createSubject(SubjectContext)
109 * @see Subject.Builder
110 * @since 1.0
111 */
112 Subject createSubject(SubjectContext context);
113
114 }