ServerAuthContext


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  package com.sun.enterprise.security.jauth;
25  
26  /**
27   * This ServerAuthContext class manages AuthModules that may be used
28   * to validate client requests.  A caller typically uses this class
29   * in the following manner:
30   *
31   * <ol>
32   * <li> Retrieve an instance of this class via AuthConfig.getServerAuthContext.
33   * <li> Receive initial client request and pass it to <i>validateRequest</i>.
34   *      <br>
35   *  Configured plug-in modules validate credentials present in request
36   *  (for example, decrypt and verify a signature).
37   *  If credentials valid and sufficient, return.
38   *  Otherwise throw an AuthException.
39   * <li> Authentication complete.
40   *      <br>
41   *      Perform authorization check on authenticated identity and,
42   *  if successful, dispatch to requested service application.
43   * <li> Service application finished.
44   * <li> Invoke <i>secureResponse</i>.
45   *      <br>
46   *  Configured modules secure response (sign and encrypt it, for example).
47   * <li> Send final response to client.
48   * <li> The <i>disposeSubject</i> method may be invoked it necessary
49   *  to clean up any authentication state in the Subject.
50   * </ol>
51   *
52   * <p> An instance may reuse module instances it previous created.
53   * As a result a single module instance may be used to process
54   * different requests from different clients.
55   * It is the module implementation's responsibility to properly
56   * store and restore any state necessary to associate new requests
57   * with previous responses.  A module that does not need to do so
58   * may remain completely stateless.
59   *
60   * <p> Instances of this class have custom logic to determine
61   * what modules to invoke, and in what order.  In addition,
62   * this custom logic may control whether subsequent modules are invoked
63   * based on the success or failure of previously invoked modules.
64   *
65   * <p> The caller is responsible for passing in a state Map
66   * that can be used by underlying modules to save state across
67   * a sequence of calls from <code>validateRequest</code>
68   * to <code>secureResponse</code> to <code>disposeSubject</code>.
69   * The same Map instance must be passed to all methods in the call sequence.
70   * Furthermore, each call sequence should be passed its own unique
71   * shared state Map instance.
72   *
73   * @version %I%, %G%
74   * @see AuthConfig
75   * @see SOAPAuthParam
76   */
77  public interface ServerAuthContext {
78  
79      /**
80       * Authenticate a client request.
81       * (decrypt the message and verify a signature, for exmaple).
82       *
83       * <p> This method invokes configured modules to authenticate the request.
84       *
85       * @param param an authentication parameter that encapsulates the
86       *          client request and server response objects.
87       *
88       * @param subject the subject may be used by configured modules
89       *      to store and Principals and credentials validated
90       *      in the request.
91       *
92       * @param sharedState a Map for modules to save state across
93       *          a sequence of calls from <code>validateRequest</code>
94       *          to <code>secureResponse</code> to <code>disposeSubject</code>.
95       *
96       * @exception PendingException if the operation is pending
97       *      (for example, when a module issues a challenge).
98       *      The module must have updated the response object
99       *      in the AuthParam input parameter.
100      *
101      * @exception FailureException if the authentication failed.
102      *      The module must have updated the response object
103      *      in the AuthParam input parameter.
104      *
105      * @exception AuthException if the operation failed.
106      */
107     void validateRequest(AuthParam param,
108             javax.security.auth.Subject   subject,
109             java.util.Map   sharedState)
110         throws AuthException;
111 
112     /**
113      * Secure the response to the client
114      * (sign and encrypt the response, for example).
115      *
116      * <p> This method invokes configured modules to secure the response.
117      *
118      * @param param an authentication parameter that encapsulates the
119      *          client request and server response objects
120      *
121      * @param subject the subject may be used by configured modules
122      *      to obtain credentials needed to secure the response, or null.
123      *      If null, the module may use a CallbackHandler to obtain
124      *      the necessary information.
125      *
126      * @param sharedState a Map for modules to save state across
127      *          a sequence of calls from <code>validateRequest</code>
128      *          to <code>secureResponse</code> to <code>disposeSubject</code>.
129      *
130      * @exception AuthException if the operation failed.
131      */
132     void secureResponse(AuthParam param,
133             javax.security.auth.Subject   subject,
134             java.util.Map   sharedState)
135         throws AuthException;
136 
137     /**
138      * Dispose of the Subject
139      * (remove Principals or credentials from the Subject object
140      * that were stored during <code>validateRequest</code>).
141      *
142      * <p> This method invokes configured modules to dispose the Subject.
143      *
144      * @param subject the subject to be disposed.
145      *
146      * @param sharedState a Map for modules to save state across
147      *          a sequence of calls from <code>validateRequest</code>
148      *          to <code>secureResponse</code> to <code>disposeSubject</code>.
149      *
150      * @exception AuthException if the operation failed.
151      */
152     void disposeSubject(javax.security.auth.Subject   subject,
153             java.util.Map   sharedState)
154         throws AuthException;
155 
156     /**
157      * modules manage sessions
158      * used by calling container to determine if it should delegate session 
159      * management (including the mapping of requests to authentication
160      * results established from previous requests) to the underlying 
161      * authentication modules of the context. 
162      * <p>
163      * When this method returns true,
164      * the container should call validate on every request, and as such
165      * may depend on the invoked modules to determine when a request 
166      * pertains to an existing authentication session.
167      * <p> 
168      * When this method returns false,
169      * the container may employ is own session management functionality, and 
170      * may use this functionality to recognize when an exiting request 
171      * is to be interpretted in the context of an existing authentication
172      * session. 
173      *
174      * @return true if the context should be allowed to manage sessions, and
175      * false if session management (if it is to occur) must be performed by 
176      * the container.
177      *
178      * @exception AuthException if the operation failed.
179      */
180     boolean managesSessions(java.util.Map   sharedState)
181         throws AuthException;
182 
183 }
184
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags