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