org.appng.core.service

## Class LdapService

- java.lang.Object
- - org.appng.core.service.LdapService

-     public class LdapService
      extends Object

  Service providing methods to login `Subject`s based on the LDAP-configuration of a `Site`. The following site-properties need to be configured properly:
  - "ldapDisabled"
  - "ldapDomain"
  - "ldapGroupBaseDn"
  - "ldapHost"
  - "ldapIdAttribute"
  - "ldapPassword"
  - "ldapPrincipalScheme"
  - "ldapStartTls"
  - "ldapUser"
  - "ldapUserBaseDn"
  Author:
    Matthias Müller, Dirk Heuvels

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `LDAP_DISABLED` Whether authentication via LDAP is disabled
    `static String` | `LDAP_DOMAIN` The domain for the LDAP authentication
    `static String` | `LDAP_GROUP_BASE_DN` The base-DN for LDAP-groups
    `static String` | `LDAP_HOST` The LDAP host
    `static String` | `LDAP_ID_ATTRIBUTE` The name of the LDAP-attribute containing the user-id used for authentication
    `static String` | `LDAP_PASSWORD` Password of the LDAP service-user
    `static String` | `LDAP_PRINCIPAL_SCHEME` How the LDAP principal is derived from a given username when logging in (DN, SAM, UPN)
    `static String` | `LDAP_START_TLS` Whether to use STARTTLS for the LDAP connection
    `static String` | `LDAP_USER` The name of the LDAP service-user
    `static String` | `LDAP_USER_BASE_DN` The base-DN for LDAP-users

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LdapService()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `List<SubjectImpl>` | `getMembersOfGroup(Site site, String groupName)` Fetches the members of a given group and returns them as a List of `SubjectImpl` objects.
    `List<String>` | `loginGroup(Site site, String username, char[] password, SubjectImpl subject, List<String> groupNames)` Tries to login the user as a member of at least one of the given groups.
    `boolean` | `loginUser(Site site, String username, char[] password)` Tries to login the user with the given username and password.
    `void` | `setLdapCtxFactory(String ldapCtxFactory)` Set another factory class to be used as JNDI parameter `Context.INITIAL_CONTEXT_FACTORY`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### LDAP_DISABLED

          public static final String LDAP_DISABLED

      Whether authentication via LDAP is disabled
      See Also:
        Constant Field Values

    - #### LDAP_DOMAIN

          public static final String LDAP_DOMAIN

      The domain for the LDAP authentication
      See Also:
        Constant Field Values

    - #### LDAP_GROUP_BASE_DN

          public static final String LDAP_GROUP_BASE_DN

      The base-DN for LDAP-groups
      See Also:
        Constant Field Values

    - #### LDAP_HOST

          public static final String LDAP_HOST

      The LDAP host
      See Also:
        Constant Field Values

    - #### LDAP_ID_ATTRIBUTE

          public static final String LDAP_ID_ATTRIBUTE

      The name of the LDAP-attribute containing the user-id used for authentication
      See Also:
        Constant Field Values

    - #### LDAP_PASSWORD

          public static final String LDAP_PASSWORD

      Password of the LDAP service-user
      See Also:
        Constant Field Values

    - #### LDAP_PRINCIPAL_SCHEME

          public static final String LDAP_PRINCIPAL_SCHEME

      How the LDAP principal is derived from a given username when logging in (DN, SAM, UPN)
      See Also:
        Constant Field Values

    - #### LDAP_START_TLS

          public static final String LDAP_START_TLS

      Whether to use STARTTLS for the LDAP connection
      See Also:
        Constant Field Values

    - #### LDAP_USER

          public static final String LDAP_USER

      The name of the LDAP service-user
      See Also:
        Constant Field Values

    - #### LDAP_USER_BASE_DN

          public static final String LDAP_USER_BASE_DN

      The base-DN for LDAP-users
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### LdapService

          public LdapService()

  - ### Method Detail

    - #### setLdapCtxFactory

          public void setLdapCtxFactory(String ldapCtxFactory)

      Set another factory class to be used as JNDI parameter `Context.INITIAL_CONTEXT_FACTORY`. This is primarily useful for unit testing. The default value is `com.sun.jndi.ldap.LdapCtxFactory`.
      Parameters:
        `ldapCtxFactory` - an alternative context factory class to be used.

    - #### loginUser

          public boolean loginUser(Site site,
                                   String username,
                                   char[] password)

      Tries to login the user with the given username and password.
      Parameters:
        `site` - the `Site` the user wants to login at
        `username` - The plain name of the user without base-DN. This name will be mapped to an LDAP principal according to the value of "ldapPrincipalScheme".
        - "DN": results in `"ldapIdAttribute"=username,"ldapUserBaseDn"` (this should work with any LDAP server)
        - "UPN": results in `username@"ldapDomain"` (probably most common name format to log on to Active Directory, @see MSDN on LDAP simple authentication)
        - "SAM": results in `"ldapDomain"\username` (name format including sAMAccountName and NetBios name to logon to active Directory)
        `password` - the password of the user
      Returns:
        `true` if the user could be successfully logged in, `null` otherwise

    - #### loginGroup

          public List<String> loginGroup(Site site,
                                         String username,
                                         char[] password,
                                         SubjectImpl subject,
                                         List<String> groupNames)

      Tries to login the user as a member of at least one of the given groups. Therefore two steps are necessary. First, the login of the user with the given password must be successful. Second, the user must be a member of at least one group.
      Note that to determine the memberships a service user with credentials taken from "ldapUser" and "ldapPassword", will be used. This username may be specified as Distinguished Name (DN) e.g. "cn=Service User, dc=mycompany, dc=com". If this is the case, it will be used as LDAP principal without mapping. If it is not a DN, it will be mapped as described in `loginUser(Site, String, char[])`.
      Parameters:
        `site` - the `Site` the user wants to login at
        `username` - the name of the user
        `password` - the password of the user
        `subject` - a `SubjectImpl` where the name and real name are set, in case the user belongs to at least one of the given groups
        `groupNames` - a list containing the names of all groups to check group membership for (without base-DN, this is set in the site-property "ldapGroupBaseDn")
      Returns:
        the names of all groups that the user is a member of (may be empty)

    - #### getMembersOfGroup

          public List<SubjectImpl> getMembersOfGroup(Site site,
                                                     String groupName)

      Fetches the members of a given group and returns them as a List of `SubjectImpl` objects. Members are LDAP Objects in the `member` attribute(s) of `"ldapIdAttribute"=groupName,"ldapGroupBaseDn"`.
      Parameters:
        `site` - the `Site` in which the application using this group is running
        `groupName` - the name of the group whose members should be fetched
      Returns:
        the members of the groupName (may be empty)

Copyright © 2011–2023 aiticon GmbH. All rights reserved.