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