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.mgt.SecurityManager; 20 21 import hunt.shiro.Exceptions; 22 import hunt.shiro.authc.AuthenticationToken; 23 import hunt.shiro.authc.Authenticator; 24 import hunt.shiro.authz.Authorizer; 25 import hunt.shiro.session.mgt.SessionManager; 26 import hunt.shiro.subject.Subject; 27 import hunt.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 hunt.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 hunt.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 hunt.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 hunt.shiro.mgt.DefaultSecurityManager 55 */ 56 interface SecurityManager : Authenticator, Authorizer, SessionManager { 57 58 /** 59 * Logs in the specified Subject using the given {@code authenticationToken}, returning an updated Subject 60 * instance reflecting the authenticated state if successful or throwing {@code AuthenticationException} if it is 61 * not. 62 * <p/> 63 * Note that most application developers should probably not call this method directly unless they have a good 64 * reason for doing so. The preferred way to log in a Subject is to call 65 * <code>subject.{@link hunt.shiro.subject.Subject#login login(authenticationToken)}</code> (usually after 66 * acquiring the Subject by calling {@link hunt.shiro.SecurityUtils#getSubject() SecurityUtils.getSubject()}). 67 * <p/> 68 * Framework developers on the other hand might find calling this method directly useful in certain cases. 69 * 70 * @param subject the subject against which the authentication attempt will occur 71 * @param authenticationToken the token representing the Subject's principal(s) and credential(s) 72 * @return the subject instance reflecting the authenticated state after a successful attempt 73 * @throws AuthenticationException if the login attempt failed. 74 */ 75 Subject login(Subject subject, AuthenticationToken authenticationToken); 76 77 /** 78 * Logs out the specified Subject from the system. 79 * <p/> 80 * Note that most application developers should not call this method unless they have a good reason for doing 81 * so. The preferred way to logout a Subject is to call 82 * <code>{@link hunt.shiro.subject.Subject#logout Subject.logout()}</code>, not the 83 * {@code SecurityManager} directly. 84 * <p/> 85 * Framework developers on the other hand might find calling this method directly useful in certain cases. 86 * 87 * @param subject the subject to log out. 88 */ 89 void logout(Subject subject); 90 91 /** 92 * Creates a {@code Subject} instance reflecting the specified contextual data. 93 * <p/> 94 * The context can be anything needed by this {@code SecurityManager} to construct a {@code Subject} instance. 95 * Most Shiro end-users will never call this method - it exists primarily for 96 * framework development and to support any underlying custom {@link SubjectFactory SubjectFactory} implementations 97 * that may be used by the {@code SecurityManager}. 98 * <h4>Usage</h4> 99 * After calling this method, the returned instance is <em>not</em> bound to the application for further use. 100 * Callers are expected to know that {@code Subject} instances have local scope only and any 101 * other further use beyond the calling method must be managed explicitly. 102 * 103 * @param context any data needed to direct how the Subject should be constructed. 104 * @return the {@code Subject} instance reflecting the specified initialization data. 105 * @see SubjectFactory#createSubject(SubjectContext) 106 * @see Subject.Builder 107 */ 108 Subject createSubject(SubjectContext context); 109 110 }