001/* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 */ 019package org.apache.shiro.mgt; 020 021import org.apache.shiro.authc.AuthenticationException; 022import org.apache.shiro.authc.AuthenticationToken; 023import org.apache.shiro.authc.Authenticator; 024import org.apache.shiro.authz.Authorizer; 025import org.apache.shiro.session.mgt.SessionManager; 026import org.apache.shiro.subject.Subject; 027import org.apache.shiro.subject.SubjectContext; 028 029 030/** 031 * A {@code SecurityManager} executes all security operations for <em>all</em> Subjects (aka users) across a 032 * single application. 033 * <p/> 034 * The interface itself primarily exists as a convenience - it extends the {@link org.apache.shiro.authc.Authenticator}, 035 * {@link Authorizer}, and {@link SessionManager} interfaces, thereby consolidating 036 * these behaviors into a single point of reference. For most Shiro usages, this simplifies configuration and 037 * tends to be a more convenient approach than referencing {@code Authenticator}, {@code Authorizer}, and 038 * {@code SessionManager} instances separately; instead one only needs to interact with a single 039 * {@code SecurityManager} instance. 040 * <p/> 041 * In addition to the above three interfaces, this interface provides a number of methods supporting 042 * {@link Subject} behavior. A {@link org.apache.shiro.subject.Subject Subject} executes 043 * authentication, authorization, and session operations for a <em>single</em> user, and as such can only be 044 * managed by {@code A SecurityManager} which is aware of all three functions. The three parent interfaces on the 045 * other hand do not 'know' about {@code Subject}s to ensure a clean separation of concerns. 046 * <p/> 047 * <b>Usage Note</b>: In actuality the large majority of application programmers won't interact with a SecurityManager 048 * very often, if at all. <em>Most</em> application programmers only care about security operations for the currently 049 * executing user, usually attained by calling 050 * {@link org.apache.shiro.SecurityUtils#getSubject() SecurityUtils.getSubject()}. 051 * <p/> 052 * Framework developers on the other hand might find working with an actual SecurityManager useful. 053 * 054 * @see org.apache.shiro.mgt.DefaultSecurityManager 055 * @since 0.2 056 */ 057public interface SecurityManager extends Authenticator, Authorizer, SessionManager { 058 059 /** 060 * Logs in the specified Subject using the given {@code authenticationToken}, returning an updated Subject 061 * instance reflecting the authenticated state if successful or throwing {@code AuthenticationException} if it is 062 * not. 063 * <p/> 064 * Note that most application developers should probably not call this method directly unless they have a good 065 * reason for doing so. The preferred way to log in a Subject is to call 066 * <code>subject.{@link org.apache.shiro.subject.Subject#login login(authenticationToken)}</code> (usually after 067 * acquiring the Subject by calling {@link org.apache.shiro.SecurityUtils#getSubject() SecurityUtils.getSubject()}). 068 * <p/> 069 * Framework developers on the other hand might find calling this method directly useful in certain cases. 070 * 071 * @param subject the subject against which the authentication attempt will occur 072 * @param authenticationToken the token representing the Subject's principal(s) and credential(s) 073 * @return the subject instance reflecting the authenticated state after a successful attempt 074 * @throws AuthenticationException if the login attempt failed. 075 * @since 1.0 076 */ 077 Subject login(Subject subject, AuthenticationToken authenticationToken) throws AuthenticationException; 078 079 /** 080 * Logs out the specified Subject from the system. 081 * <p/> 082 * Note that most application developers should not call this method unless they have a good reason for doing 083 * so. The preferred way to logout a Subject is to call 084 * <code>{@link org.apache.shiro.subject.Subject#logout Subject.logout()}</code>, not the 085 * {@code SecurityManager} directly. 086 * <p/> 087 * Framework developers on the other hand might find calling this method directly useful in certain cases. 088 * 089 * @param subject the subject to log out. 090 * @since 1.0 091 */ 092 void logout(Subject subject); 093 094 /** 095 * Creates a {@code Subject} instance reflecting the specified contextual data. 096 * <p/> 097 * The context can be anything needed by this {@code SecurityManager} to construct a {@code Subject} instance. 098 * Most Shiro end-users will never call this method - it exists primarily for 099 * 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}