View Javadoc

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 }