001 /*
002 * Copyright 1998-2004 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.security.auth.spi;
027
028 import javax.security.auth.Subject;
029 import javax.security.auth.AuthPermission;
030 import javax.security.auth.callback.*;
031 import javax.security.auth.login.*;
032 import java.util.Map;
033
034 /**
035 * <p> <code>LoginModule</code> describes the interface
036 * implemented by authentication technology providers. LoginModules
037 * are plugged in under applications to provide a particular type of
038 * authentication.
039 *
040 * <p> While applications write to the <code>LoginContext</code> API,
041 * authentication technology providers implement the
042 * <code>LoginModule</code> interface.
043 * A <code>Configuration</code> specifies the LoginModule(s)
044 * to be used with a particular login application. Therefore different
045 * LoginModules can be plugged in under the application without
046 * requiring any modifications to the application itself.
047 *
048 * <p> The <code>LoginContext</code> is responsible for reading the
049 * <code>Configuration</code> and instantiating the appropriate
050 * LoginModules. Each <code>LoginModule</code> is initialized with
051 * a <code>Subject</code>, a <code>CallbackHandler</code>, shared
052 * <code>LoginModule</code> state, and LoginModule-specific options.
053 *
054 * The <code>Subject</code> represents the
055 * <code>Subject</code> currently being authenticated and is updated
056 * with relevant Credentials if authentication succeeds.
057 * LoginModules use the <code>CallbackHandler</code> to
058 * communicate with users. The <code>CallbackHandler</code> may be
059 * used to prompt for usernames and passwords, for example.
060 * Note that the <code>CallbackHandler</code> may be null. LoginModules
061 * which absolutely require a <code>CallbackHandler</code> to authenticate
062 * the <code>Subject</code> may throw a <code>LoginException</code>.
063 * LoginModules optionally use the shared state to share information
064 * or data among themselves.
065 *
066 * <p> The LoginModule-specific options represent the options
067 * configured for this <code>LoginModule</code> by an administrator or user
068 * in the login <code>Configuration</code>.
069 * The options are defined by the <code>LoginModule</code> itself
070 * and control the behavior within it. For example, a
071 * <code>LoginModule</code> may define options to support debugging/testing
072 * capabilities. Options are defined using a key-value syntax,
073 * such as <i>debug=true</i>. The <code>LoginModule</code>
074 * stores the options as a <code>Map</code> so that the values may
075 * be retrieved using the key. Note that there is no limit to the number
076 * of options a <code>LoginModule</code> chooses to define.
077 *
078 * <p> The calling application sees the authentication process as a single
079 * operation. However, the authentication process within the
080 * <code>LoginModule</code> proceeds in two distinct phases.
081 * In the first phase, the LoginModule's
082 * <code>login</code> method gets invoked by the LoginContext's
083 * <code>login</code> method. The <code>login</code>
084 * method for the <code>LoginModule</code> then performs
085 * the actual authentication (prompt for and verify a password for example)
086 * and saves its authentication status as private state
087 * information. Once finished, the LoginModule's <code>login</code>
088 * method either returns <code>true</code> (if it succeeded) or
089 * <code>false</code> (if it should be ignored), or throws a
090 * <code>LoginException</code> to specify a failure.
091 * In the failure case, the <code>LoginModule</code> must not retry the
092 * authentication or introduce delays. The responsibility of such tasks
093 * belongs to the application. If the application attempts to retry
094 * the authentication, the LoginModule's <code>login</code> method will be
095 * called again.
096 *
097 * <p> In the second phase, if the LoginContext's overall authentication
098 * succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL
099 * LoginModules succeeded), then the <code>commit</code>
100 * method for the <code>LoginModule</code> gets invoked.
101 * The <code>commit</code> method for a <code>LoginModule</code> checks its
102 * privately saved state to see if its own authentication succeeded.
103 * If the overall <code>LoginContext</code> authentication succeeded
104 * and the LoginModule's own authentication succeeded, then the
105 * <code>commit</code> method associates the relevant
106 * Principals (authenticated identities) and Credentials (authentication data
107 * such as cryptographic keys) with the <code>Subject</code>
108 * located within the <code>LoginModule</code>.
109 *
110 * <p> If the LoginContext's overall authentication failed (the relevant
111 * REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules did not succeed),
112 * then the <code>abort</code> method for each <code>LoginModule</code>
113 * gets invoked. In this case, the <code>LoginModule</code> removes/destroys
114 * any authentication state originally saved.
115 *
116 * <p> Logging out a <code>Subject</code> involves only one phase.
117 * The <code>LoginContext</code> invokes the LoginModule's <code>logout</code>
118 * method. The <code>logout</code> method for the <code>LoginModule</code>
119 * then performs the logout procedures, such as removing Principals or
120 * Credentials from the <code>Subject</code> or logging session information.
121 *
122 * <p> A <code>LoginModule</code> implementation must have a constructor with
123 * no arguments. This allows classes which load the <code>LoginModule</code>
124 * to instantiate it.
125 *
126 * @version 1.60, 05/05/07
127 * @see javax.security.auth.login.LoginContext
128 * @see javax.security.auth.login.Configuration
129 */
130 public interface LoginModule {
131
132 /**
133 * Initialize this LoginModule.
134 *
135 * <p> This method is called by the <code>LoginContext</code>
136 * after this <code>LoginModule</code> has been instantiated.
137 * The purpose of this method is to initialize this
138 * <code>LoginModule</code> with the relevant information.
139 * If this <code>LoginModule</code> does not understand
140 * any of the data stored in <code>sharedState</code> or
141 * <code>options</code> parameters, they can be ignored.
142 *
143 * <p>
144 *
145 * @param subject the <code>Subject</code> to be authenticated. <p>
146 *
147 * @param callbackHandler a <code>CallbackHandler</code> for communicating
148 * with the end user (prompting for usernames and
149 * passwords, for example). <p>
150 *
151 * @param sharedState state shared with other configured LoginModules. <p>
152 *
153 * @param options options specified in the login
154 * <code>Configuration</code> for this particular
155 * <code>LoginModule</code>.
156 */
157 void initialize(Subject subject, CallbackHandler callbackHandler,
158 Map<String, ?> sharedState, Map<String, ?> options);
159
160 /**
161 * Method to authenticate a <code>Subject</code> (phase 1).
162 *
163 * <p> The implementation of this method authenticates
164 * a <code>Subject</code>. For example, it may prompt for
165 * <code>Subject</code> information such
166 * as a username and password and then attempt to verify the password.
167 * This method saves the result of the authentication attempt
168 * as private state within the LoginModule.
169 *
170 * <p>
171 *
172 * @exception LoginException if the authentication fails
173 *
174 * @return true if the authentication succeeded, or false if this
175 * <code>LoginModule</code> should be ignored.
176 */
177 boolean login() throws LoginException;
178
179 /**
180 * Method to commit the authentication process (phase 2).
181 *
182 * <p> This method is called if the LoginContext's
183 * overall authentication succeeded
184 * (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules
185 * succeeded).
186 *
187 * <p> If this LoginModule's own authentication attempt
188 * succeeded (checked by retrieving the private state saved by the
189 * <code>login</code> method), then this method associates relevant
190 * Principals and Credentials with the <code>Subject</code> located in the
191 * <code>LoginModule</code>. If this LoginModule's own
192 * authentication attempted failed, then this method removes/destroys
193 * any state that was originally saved.
194 *
195 * <p>
196 *
197 * @exception LoginException if the commit fails
198 *
199 * @return true if this method succeeded, or false if this
200 * <code>LoginModule</code> should be ignored.
201 */
202 boolean commit() throws LoginException;
203
204 /**
205 * Method to abort the authentication process (phase 2).
206 *
207 * <p> This method is called if the LoginContext's
208 * overall authentication failed.
209 * (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules
210 * did not succeed).
211 *
212 * <p> If this LoginModule's own authentication attempt
213 * succeeded (checked by retrieving the private state saved by the
214 * <code>login</code> method), then this method cleans up any state
215 * that was originally saved.
216 *
217 * <p>
218 *
219 * @exception LoginException if the abort fails
220 *
221 * @return true if this method succeeded, or false if this
222 * <code>LoginModule</code> should be ignored.
223 */
224 boolean abort() throws LoginException;
225
226 /**
227 * Method which logs out a <code>Subject</code>.
228 *
229 * <p>An implementation of this method might remove/destroy a Subject's
230 * Principals and Credentials.
231 *
232 * <p>
233 *
234 * @exception LoginException if the logout fails
235 *
236 * @return true if this method succeeded, or false if this
237 * <code>LoginModule</code> should be ignored.
238 */
239 boolean logout() throws LoginException;
240 }
|