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