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