View Javadoc

1   /* Copyright 2004, 2005 Acegi Technology Pty Limited
2    *
3    * Licensed under the Apache License, Version 2.0 (the "License");
4    * you may not use this file except in compliance with the License.
5    * You may obtain a copy of the License at
6    *
7    *     http://www.apache.org/licenses/LICENSE-2.0
8    *
9    * Unless required by applicable law or agreed to in writing, software
10   * distributed under the License is distributed on an "AS IS" BASIS,
11   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12   * See the License for the specific language governing permissions and
13   * limitations under the License.
14   */
15  
16  package org.acegisecurity;
17  
18  /***
19   * Creates a new temporary {@link Authentication} object for the current secure
20   * object invocation only.
21   * 
22   * <p>
23   * This interface permits implementations to replace the
24   * <code>Authentication</code> object that applies to the current secure
25   * object invocation only. The {@link
26   * org.acegisecurity.intercept.AbstractSecurityInterceptor} will replace
27   * the <code>Authentication</code> object held in the
28   * {@link org.acegisecurity.context.SecurityContext SecurityContext}
29   * for the duration of  the secure object callback only, returning it to
30   * the original <code>Authentication</code> object when the callback ends.
31   * </p>
32   * 
33   * <p>
34   * This is provided so that systems with two layers of objects can be
35   * established. One layer is public facing and has normal secure methods with
36   * the granted authorities expected to be held by external callers. The other
37   * layer is private, and is only expected to be called by objects within the
38   * public facing layer. The objects in this private layer still need security
39   * (otherwise they would be public methods) and they also need security in
40   * such a manner that prevents them being called directly by external callers.
41   * The objects in the private layer would be configured to require granted
42   * authorities never granted to external callers. The
43   * <code>RunAsManager</code> interface provides a mechanism to elevate
44   * security in this manner.
45   * </p>
46   * 
47   * <p>
48   * It is expected implementations will provide a corresponding concrete
49   * <code>Authentication</code> and <code>AuthenticationProvider</code> so that
50   * the replacement <code>Authentication</code> object can be authenticated.
51   * Some form of security will need to be implemented to ensure the
52   * <code>AuthenticationProvider</code> only accepts
53   * <code>Authentication</code> objects created by an authorized concrete
54   * implementation of <code>RunAsManager</code>.
55   * </p>
56   *
57   * @author Ben Alex
58   * @version $Id: RunAsManager.java,v 1.7 2005/11/17 00:55:49 benalex Exp $
59   */
60  public interface RunAsManager {
61      //~ Methods ================================================================
62  
63      /***
64       * Returns a replacement <code>Authentication</code> object for the current
65       * secure object invocation, or <code>null</code> if replacement not
66       * required.
67       *
68       * @param authentication the caller invoking the secure object
69       * @param object the secured object being called
70       * @param config the configuration attributes associated with the secure
71       *        object being invoked
72       *
73       * @return a replacement object to be used for duration of the secure
74       *         object invocation, or <code>null</code> if the
75       *         <code>Authentication</code> should be left as is
76       */
77      public Authentication buildRunAs(Authentication authentication,
78          Object object, ConfigAttributeDefinition config);
79  
80      /***
81       * Indicates whether this <code>RunAsManager</code> is able to process the
82       * passed <code>ConfigAttribute</code>.
83       * 
84       * <p>
85       * This allows the <code>AbstractSecurityInterceptor</code> to check every
86       * configuration attribute can be consumed by the configured
87       * <code>AccessDecisionManager</code> and/or <code>RunAsManager</code>
88       * and/or <code>AfterInvocationManager</code>.
89       * </p>
90       *
91       * @param attribute a configuration attribute that has been configured
92       *        against the <code>AbstractSecurityInterceptor</code>
93       *
94       * @return <code>true</code> if this <code>RunAsManager</code> can support
95       *         the passed configuration attribute
96       */
97      public boolean supports(ConfigAttribute attribute);
98  
99      /***
100      * Indicates whether the <code>RunAsManager</code> implementation is able
101      * to provide run-as replacement for the indicated secure object type.
102      *
103      * @param clazz the class that is being queried
104      *
105      * @return true if the implementation can process the indicated class
106      */
107     public boolean supports(Class clazz);
108 }