LoginModule


1   /*
2    * @(#)LoginModule.java 1.53 04/05/05
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.security.auth.spi;
9   
10  import javax.security.auth.Subject  ;
11  import javax.security.auth.AuthPermission  ;
12  import javax.security.auth.callback.*;
13  import javax.security.auth.login.*;
14  import java.util.Map  ;
15  
16  /**
17   * <p> <code>LoginModule</code> describes the interface
18   * implemented by authentication technology providers.  LoginModules
19   * are plugged in under applications to provide a particular type of
20   * authentication.
21   *
22   * <p> While applications write to the <code>LoginContext</code> API,
23   * authentication technology providers implement the
24   * <code>LoginModule</code> interface.
25   * A <code>Configuration</code> specifies the LoginModule(s)
26   * to be used with a particular login application.  Therefore different
27   * LoginModules can be plugged in under the application without
28   * requiring any modifications to the application itself.
29   *
30   * <p> The <code>LoginContext</code> is responsible for reading the
31   * <code>Configuration</code> and instantiating the appropriate
32   * LoginModules.  Each <code>LoginModule</code> is initialized with
33   * a <code>Subject</code>, a <code>CallbackHandler</code>, shared
34   * <code>LoginModule</code> state, and LoginModule-specific options.
35   * 
36   * The <code>Subject</code> represents the
37   * <code>Subject</code> currently being authenticated and is updated
38   * with relevant Credentials if authentication succeeds.
39   * LoginModules use the <code>CallbackHandler</code> to
40   * communicate with users.  The <code>CallbackHandler</code> may be
41   * used to prompt for usernames and passwords, for example.
42   * Note that the <code>CallbackHandler</code> may be null.  LoginModules
43   * which absolutely require a <code>CallbackHandler</code> to authenticate
44   * the <code>Subject</code> may throw a <code>LoginException</code>.
45   * LoginModules optionally use the shared state to share information
46   * or data among themselves.
47   *
48   * <p> The LoginModule-specific options represent the options
49   * configured for this <code>LoginModule</code> by an administrator or user
50   * in the login <code>Configuration</code>.
51   * The options are defined by the <code>LoginModule</code> itself
52   * and control the behavior within it.  For example, a
53   * <code>LoginModule</code> may define options to support debugging/testing
54   * capabilities.  Options are defined using a key-value syntax,
55   * such as <i>debug=true</i>.  The <code>LoginModule</code>
56   * stores the options as a <code>Map</code> so that the values may
57   * be retrieved using the key.  Note that there is no limit to the number
58   * of options a <code>LoginModule</code> chooses to define.
59   *
60   * <p> The calling application sees the authentication process as a single
61   * operation.  However, the authentication process within the
62   * <code>LoginModule</code> proceeds in two distinct phases.
63   * In the first phase, the LoginModule's
64   * <code>login</code> method gets invoked by the LoginContext's
65   * <code>login</code> method.  The <code>login</code>
66   * method for the <code>LoginModule</code> then performs
67   * the actual authentication (prompt for and verify a password for example)
68   * and saves its authentication status as private state
69   * information.  Once finished, the LoginModule's <code>login</code>
70   * method either returns <code>true</code> (if it succeeded) or
71   * <code>false</code> (if it should be ignored), or throws a
72   * <code>LoginException</code> to specify a failure.
73   * In the failure case, the <code>LoginModule</code> must not retry the
74   * authentication or introduce delays.  The responsibility of such tasks
75   * belongs to the application.  If the application attempts to retry
76   * the authentication, the LoginModule's <code>login</code> method will be
77   * called again.
78   *
79   * <p> In the second phase, if the LoginContext's overall authentication
80   * succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL
81   * LoginModules succeeded), then the <code>commit</code>
82   * method for the <code>LoginModule</code> gets invoked.
83   * The <code>commit</code> method for a <code>LoginModule</code> checks its
84   * privately saved state to see if its own authentication succeeded.
85   * If the overall <code>LoginContext</code> authentication succeeded
86   * and the LoginModule's own authentication succeeded, then the
87   * <code>commit</code> method associates the relevant
88   * Principals (authenticated identities) and Credentials (authentication data
89   * such as cryptographic keys) with the <code>Subject</code>
90   * located within the <code>LoginModule</code>.
91   *
92   * <p> If the LoginContext's overall authentication failed (the relevant
93   * REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules did not succeed),
94   * then the <code>abort</code> method for each <code>LoginModule</code>
95   * gets invoked.  In this case, the <code>LoginModule</code> removes/destroys
96   * any authentication state originally saved.
97   *
98   * <p> Logging out a <code>Subject</code> involves only one phase.
99   * The <code>LoginContext</code> invokes the LoginModule's <code>logout</code>
100  * method.  The <code>logout</code> method for the <code>LoginModule</code>
101  * then performs the logout procedures, such as removing Principals or
102  * Credentials from the <code>Subject</code> or logging session information.
103  *
104  * <p> A <code>LoginModule</code> implementation must have a constructor with
105  * no arguments.  This allows classes which load the <code>LoginModule</code>
106  * to instantiate it.
107  *
108  * @version 1.53, 05/05/04
109  * @see javax.security.auth.login.LoginContext
110  * @see javax.security.auth.login.Configuration
111  */
112 public interface LoginModule {
113 
114     /**
115      * Initialize this LoginModule.
116      *
117      * <p> This method is called by the <code>LoginContext</code>
118      * after this <code>LoginModule</code> has been instantiated.
119      * The purpose of this method is to initialize this
120      * <code>LoginModule</code> with the relevant information.
121      * If this <code>LoginModule</code> does not understand
122      * any of the data stored in <code>sharedState</code> or
123      * <code>options</code> parameters, they can be ignored.
124      *
125      * <p>
126      *
127      * @param subject the <code>Subject</code> to be authenticated. <p>
128      *
129      * @param callbackHandler a <code>CallbackHandler</code> for communicating
130      *          with the end user (prompting for usernames and
131      *          passwords, for example). <p>
132      *
133      * @param sharedState state shared with other configured LoginModules. <p>
134      *
135      * @param options options specified in the login
136      *          <code>Configuration</code> for this particular
137      *          <code>LoginModule</code>.
138      */
139     void initialize(Subject   subject, CallbackHandler callbackHandler,
140             Map  <String  ,?> sharedState,
141             Map  <String  ,?> options);
142 
143     /**
144      * Method to authenticate a <code>Subject</code> (phase 1).
145      *
146      * <p> The implementation of this method authenticates
147      * a <code>Subject</code>.  For example, it may prompt for
148      * <code>Subject</code> information such
149      * as a username and password and then attempt to verify the password.
150      * This method saves the result of the authentication attempt
151      * as private state within the LoginModule.
152      *
153      * <p>
154      *
155      * @exception LoginException if the authentication fails
156      *
157      * @return true if the authentication succeeded, or false if this
158      *          <code>LoginModule</code> should be ignored.
159      */
160     boolean login() throws LoginException;
161 
162     /**
163      * Method to commit the authentication process (phase 2).
164      *
165      * <p> This method is called if the LoginContext's
166      * overall authentication succeeded
167      * (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules
168      * succeeded).
169      *
170      * <p> If this LoginModule's own authentication attempt
171      * succeeded (checked by retrieving the private state saved by the
172      * <code>login</code> method), then this method associates relevant
173      * Principals and Credentials with the <code>Subject</code> located in the
174      * <code>LoginModule</code>.  If this LoginModule's own
175      * authentication attempted failed, then this method removes/destroys
176      * any state that was originally saved.
177      *
178      * <p>
179      *
180      * @exception LoginException if the commit fails
181      *
182      * @return true if this method succeeded, or false if this
183      *          <code>LoginModule</code> should be ignored.
184      */
185     boolean commit() throws LoginException;
186 
187     /**
188      * Method to abort the authentication process (phase 2).
189      *
190      * <p> This method is called if the LoginContext's
191      * overall authentication failed.
192      * (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules
193      * did not succeed).
194      *
195      * <p> If this LoginModule's own authentication attempt
196      * succeeded (checked by retrieving the private state saved by the
197      * <code>login</code> method), then this method cleans up any state
198      * that was originally saved.
199      *
200      * <p>
201      *
202      * @exception LoginException if the abort fails
203      *
204      * @return true if this method succeeded, or false if this
205      *          <code>LoginModule</code> should be ignored.
206      */
207     boolean abort() throws LoginException;
208 
209     /**
210      * Method which logs out a <code>Subject</code>.  
211      *
212      * <p>An implementation of this method might remove/destroy a Subject's
213      * Principals and Credentials.
214      *
215      * <p>
216      *
217      * @exception LoginException if the logout fails
218      *
219      * @return true if this method succeeded, or false if this
220      *          <code>LoginModule</code> should be ignored.
221      */
222     boolean logout() throws LoginException;
223 }
224
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags