JndiLoginModule (Java SE 26 & JDK 26)
Description: declaration: module: jdk.security.auth, package: com.sun.security.auth.module, class: JndiLoginModule
Keywords: com.sun.security.auth.module.JndiLoginModule class

# Class JndiLoginModule

java.lang.Object
com.sun.security.auth.module.JndiLoginModule

All Implemented Interfaces:
  `LoginModule`

public class JndiLoginModule extends Object implements LoginModule
The module prompts for a username and password and then verifies the password against the password stored in a directory service configured under JNDI.

This `LoginModule` interoperates with any conformant JNDI service provider. To direct this `LoginModule` to use a specific JNDI service provider, two options must be specified in the login `Configuration` for this `LoginModule`.

         user.provider.url=name_service_url
         group.provider.url=name_service_url

name_service_url specifies the directory service and path where this `LoginModule` can access the relevant user and group information. Because this `LoginModule` only performs one-level searches to find the relevant user information, the `URL` must point to a directory one level above where the user and group information is stored in the directory service. For example, to instruct this `LoginModule` to contact a NIS server, the following URLs must be specified:

       user.provider.url="nis://NISServerHostName/NISDomain/user"
       group.provider.url="nis://NISServerHostName/NISDomain/system/group"

NISServerHostName specifies the server host name of the NIS server (for example, nis.sun.com, and NISDomain specifies the domain for that NIS server (for example, jaas.sun.com. To contact an LDAP server, the following URLs must be specified:

       user.provider.url="ldap://LDAPServerHostName/LDAPName"
       group.provider.url="ldap://LDAPServerHostName/LDAPName"

LDAPServerHostName specifies the server host name of the LDAP server, which may include a port number (for example, ldap.sun.com:389), and LDAPName specifies the entry name in the LDAP directory (for example, ou=People,o=Sun,c=US and ou=Groups,o=Sun,c=US for user and group information, respectively).

The format in which the user's information must be stored in the directory service is specified in RFC 2307. Specifically, this `LoginModule` will search for the user's entry in the directory service using the user's uid attribute, where uid=username. If the search succeeds, this `LoginModule` will then obtain the user's encrypted password from the retrieved entry using the userPassword attribute. This `LoginModule` assumes that the password is stored as a byte array, which when converted to a `String`, has the following format:

         "{crypt}encrypted_password"

The LDAP directory server must be configured to permit read access to the userPassword attribute. If the user entered a valid username and password, this `LoginModule` associates a `UnixPrincipal`, `UnixNumericUserPrincipal`, and the relevant UnixNumericGroupPrincipals with the `Subject`.

This LoginModule also recognizes the following `Configuration` options:

       debug          if, true, debug messages are output to System.out.

       useFirstPass   if, true, this LoginModule retrieves the
                      username and password from the module's shared state,
                      using "javax.security.auth.login.name" and
                      "javax.security.auth.login.password" as the respective
                      keys.  The retrieved values are used for authentication.
                      If authentication fails, no attempt for a retry is made,
                      and the failure is reported back to the calling
                      application.

       tryFirstPass   if, true, this LoginModule retrieves the
                      the username and password from the module's shared state,
                      using "javax.security.auth.login.name" and
                      "javax.security.auth.login.password" as the respective
                      keys.  The retrieved values are used for authentication.
                      If authentication fails, the module uses the
                      CallbackHandler to retrieve a new username and password,
                      and another attempt to authenticate is made.
                      If the authentication fails, the failure is reported
                      back to the calling application.

       storePass      if, true, this LoginModule stores the username and password
                      obtained from the CallbackHandler in the module's
                      shared state, using "javax.security.auth.login.name" and
                      "javax.security.auth.login.password" as the respective
                      keys.  This is not performed if existing values already
                      exist for the username and password in the shared state,
                      or if authentication fails.

       clearPass     if, true, this LoginModule clears the
                     username and password stored in the module's shared state
                     after both phases of authentication (login and commit)
                     have completed.

Since:
  1.4

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `final String`
  `GROUP_PROVIDER`
  Directory service/path where this module can access the relevant group information.
  `final String`
  `USER_PROVIDER`
  Directory service/path where this module can access the relevant user information.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `JndiLoginModule()`
  Creates a `JndiLoginModule`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `abort()`
  This method is called if the LoginContext's overall authentication failed.
  `boolean`
  `commit()`
  Abstract method to commit the authentication process (phase 2).
  `void`
  `initialize(Subject subject, CallbackHandler callbackHandler, Map<String,?> sharedState, Map<String,?> options)`
  Initialize this `LoginModule`.
  `boolean`
  `login()`
  Prompt for username and password.
  `boolean`
  `logout()`
  Logout a user.

  ### Methods declared in class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  Creates and returns a copy of this object.
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `int`
  `hashCode()`
  Returns a hash code value for this object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `String`
  `toString()`
  Returns a string representation of the object.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

- ## Field Details

  - ### USER_PROVIDER

    public final String USER_PROVIDER
    Directory service/path where this module can access the relevant user information.
    See Also:
      - Constant Field Values

  - ### GROUP_PROVIDER

    public final String GROUP_PROVIDER
    Directory service/path where this module can access the relevant group information.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### JndiLoginModule

    public JndiLoginModule()
    Creates a `JndiLoginModule`.

- ## Method Details

  - ### initialize

    public void initialize(Subject subject, CallbackHandler callbackHandler, Map<String,?> sharedState, Map<String,?> options)
    Initialize this `LoginModule`.
    Specified by:
      `initialize` in interface `LoginModule`
    Parameters:
      `subject` - the `Subject` to be authenticated.
      `callbackHandler` - a `CallbackHandler` for communicating with the end user (prompting for usernames and passwords, for example).
      `sharedState` - shared `LoginModule` state.
      `options` - options specified in the login `Configuration` for this particular `LoginModule`.

  - ### login

    public boolean login() throws LoginException
    Prompt for username and password. Verify the password against the relevant name service.
    Specified by:
      `login` in interface `LoginModule`
    Returns:
      true always, since this `LoginModule` should not be ignored.
    Throws:
      `FailedLoginException` - if the authentication fails.
      `LoginException` - if this `LoginModule` is unable to perform the authentication.

  - ### commit

    public boolean commit() throws LoginException
    Abstract method to commit the authentication process (phase 2).

    This method is called if the LoginContext's overall authentication succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules succeeded).

    If this LoginModule's own authentication attempt succeeded (checked by retrieving the private state saved by the `login` method), then this method associates a `UnixPrincipal` with the `Subject` located in the `LoginModule`. If this LoginModule's own authentication attempted failed, then this method removes any state that was originally saved.

    Specified by:
      `commit` in interface `LoginModule`
    Returns:
      true if this LoginModule's own login and commit attempts succeeded, or false otherwise.
    Throws:
      `LoginException` - if the commit fails

  - ### abort

    public boolean abort() throws LoginException
    This method is called if the LoginContext's overall authentication failed. (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules did not succeed).

    If this LoginModule's own authentication attempt succeeded (checked by retrieving the private state saved by the `login` and `commit` methods), then this method cleans up any state that was originally saved.

    Specified by:
      `abort` in interface `LoginModule`
    Returns:
      false if this LoginModule's own login and/or commit attempts failed, and true otherwise.
    Throws:
      `LoginException` - if the abort fails.

  - ### logout

    public boolean logout() throws LoginException
    Logout a user.

    This method removes the Principals that were added by the `commit` method.

    Specified by:
      `logout` in interface `LoginModule`
    Returns:
      true in all cases since this `LoginModule` should not be ignored.
    Throws:
      `LoginException` - if the logout fails.