Configuring Lightweight Directory Access Protocol in a federated repository configuration

Follow this topic to configure Lightweight Directory Access Protocol (LDAP) settings in a federated repository configuration.

Before you begin

You have chosen among various ways to configure LDAP:

[8.5.5.10 or later]You can test LDAP server connections and search filters before you configure them.

About this task

At this point, you are viewing the LDAP repository configuration page of the administrative console.

Procedure

  1. Enter a unique identifier for the repository in the Repository identifier field. This identifier uniquely identifies the repository within the cell, for example: LDAP1.
  2. Select the type of LDAP server that is used from the Directory type list.
    The type of LDAP server determines the default filters that are used by WebSphere® Application Server.

    IBM® Tivoli® Directory Server users can choose either IBM Tivoli Directory Server or SecureWay as the directory type. Use the IBM Tivoli Directory Server directory type for better performance. For a list of supported LDAP servers, see Using specific directory servers as the LDAP server.

  3. Enter the fully qualified host name of the primary LDAP server in the Primary host name field.
    You can enter either the IP address or the domain name system (DNS) name.
  4. Enter the server port of the LDAP directory in the Port field.
    The host name and the port number represent the realm for this LDAP server in a mixed version nodes cell. If servers in different cells are communicating with each other using Lightweight Third Party Authentication (LTPA) tokens, these realms must match exactly in all the cells.

    The default value is 389, which is not a Secure Sockets Layer (SSL) connection. Use port 636 for a Secure Sockets Layer (SSL) connection. For some LDAP servers, you can specify a different port for a non-SSL or SSL connection. If you do not know the port to use, contact your LDAP server administrator.

    If multiple WebSphere Application Servers are installed and configured to run in the same single sign-on domain, or if WebSphere Application Server interoperates with a previous version of WebSphere Application Server, then it is important that the port number match all configurations. For example, if the LDAP port is explicitly specified as 389 in a Version 5.x or 6.0.x configuration, and WebSphere Application Server at Version 6.1 is going to interoperate with the Version 5.x or 6.0.x server, then verify that port 389 is specified explicitly for the Version 6.1 server.

  5. Optional: Enter the host name of the failover LDAP server in the Failover host name field.
    You can specify a secondary directory server to be used in the event that your primary directory server becomes unavailable. After switching to a secondary directory server, LDAP repository attempts to reconnect to the primary directory server every 15 minutes.
  6. Optional: Enter the port of the failover LDAP server in the Port field and click Add.
    The default value is 389, which is not a Secure Sockets Layer (SSL) connection. Use port 636 for a Secure Sockets Layer (SSL) connection. For some LDAP servers, you can specify a different port for a non-SSL or SSL connection. If you do not know the port to use, contact your LDAP server administrator.
  7. Optional: Select the type of referral.
    A referral is an entity that is used to redirect a client request to another LDAP server. A referral contains the names and locations of other objects. It is sent by the server to indicate that the information that the client requested can be found at another location, possibly at another server or several servers. The default value is ignore.
    ignore
    Referrals are ignored.
    follow
    Referrals are followed automatically.
  8. Optional: Specify the type of support for repository change tracking. The profile manager refers to this value before passing on the request to the corresponding adapter. If the value is none, then that repository is not called to retrieve the changed entities.
    none
    Specifies there is no change tracking support for this repository.
    native
    Specifies that the repository's native change tracking mechanism is used by virtual member manager to return changed entities.
  9. Optional: Specify arbitrary name and value pairs of data as custom properties. The name is a property key and the value is a string value that can be used to set internal system configuration properties. Defining a new property enables you to configure a setting beyond that which is available in the administrative console.
  10. Optional: Configure the bind authentication mechanism.

    Configure one of the following bind authentication mechanisms so that the application server can bind to the LDAP directory service. One of these bind authentication mechanisms is required when anonymous binds are not implemented.

    • Configure the simple bind authentication mechanism.

      The application server uses simple bind authentication by default. For fix packs before fix pack 8.5.5.19, only simple bind authentication is supported.

      1. Enter the bind distinguished name in the Bind distinguished name field.

        An example of the bind distinguished name is cn=root

        If anonymous binds are not possible on the LDAP server to obtain user and group information or for write operations, the bind distinguished name is required. In most cases, bind distinguished name and bind password are needed. However, when anonymous bind can satisfy all of the required functions, bind distinguished name and bind password are not needed. If the LDAP server is set up to use anonymous binds, leave this field blank. If a name is not specified, the application server binds anonymously.

      2. Enter the password that corresponds to the bind DN in the Bind password field.
    • [8.5.5.19 or later]Configure the Kerberos bind authentication mechanism.
      1. Enter the principal name in the Kerberos principal name field, for example, user1 or user1@IBM.COM.
      2. Optional: Enter the path of the Kerberos credential cache.

        The Kerberos credential cache, or ccache file is also referred to as the Kerberos ticket cache.

      3. Optional: Enter the path of the Kerberos configuration file.
        The following information gives the default file name and location for the Kerberos configuration file:
        • [IBM i][z/OS][Linux][AIX][Solaris][HP-UX]/etc/krb5.conf
        • [Windows]C:\Windows\krb5.ini
        If no Kerberos configuration file is specified, the application server uses this default Kerberos configuration file at its default system location. The Kerberos configuration file is global for all Kerberos configurations, including Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) and Kerberos Authentication. For more information, see the topic about the Kerberos configuration file.
      4. Optional: Enter the path of the Kerberos keytab file. If the Kerberos ticket cache and the Kerberos keytab file are both specified, only the Kerberos ticket cache is used. The Kerberos keytab file is global for all Kerberos configurations, including SPNEGO and Kerberos authentication.
    Remember:
    To create LDAP queries or to browse, an LDAP client must bind to the LDAP server by using one of the following ways:
    • The distinguished name of an account.
    • [8.5.5.19 or later]The Kerberos principal name of an account.
    The account has the authority to search and read the values of LDAP attributes, such as user and group information. The LDAP administrator ensures that read access privileges are set for the distinguished name or the Kerberos principal name. Read access privileges allow access to the subtree of the base distinguished name and ensure that searches of user and group information are successful.

    The directory server provides an operational attribute in each directory entry (for example, the IBM Directory Server uses ibm-entryUuid as the operational attribute). The value of this attribute is a universally unique identifier (UUID), which is chosen automatically by the directory server when the entry is added, and is expected to be unique: no other entry with the same or different name would have this same value. Directory clients can use this attribute to distinguish objects that are identified by a distinguished name or to locate an object after the object is renamed.

    Important: Ensure that the bind credentials have the authority to read this attribute.
  11. Optional: Enter the property names to use to log into WebSphere Application Server in the Login properties field.
    This field takes multiple login properties, delimited by a semicolon (;). For example, uid;mail.
    Note: If you want the login properties to be case-sensitive, then ensure that the attributeCache is disabled. Alternatively, you can choose to define login property names that are not part of the distinguished name element.

    All login properties are searched during login. If multiple entries or no entries are found, an exception is thrown. For example, if you specify the login properties as uid;mail and the login ID as Bob, the search filter searches for uid=Bob or mail=Bob. When the search returns a single entry, then authentication can proceed. Otherwise, an exception is thrown.

    Supported configurations: If you define multiple login properties, the first login property is programmatically mapped to the federated repositories principalName property. For example, if you set uid;mail as the login properties, the LDAP attribute uid value is mapped to the federated repositories principalName property. If you define multiple login properties, after login, the first login property is returned as the value of the principalName property. For example, if you pass joe@yourco.com as the principalName value and the login properties are configured as uid;mail, the principalName is returned as joe.
  12. Optional: Specify the LDAP attribute for Kerberos principal name. This field is enabled and can be modified only when Kerberos is configured and it is one of the active or preferred authentication mechanisms.
  13. Optional: Select the certificate map mode in the Certificate mapping field.
    You can use the X.590 certificates for user authentication when LDAP is selected as the repository. The Certificate mapping field is used to indicate whether to map the X.509 certificates into an LDAP directory user by EXACT_DN or CERTIFICATE_FILTER. If EXACT_DN is selected, the DN in the certificate must exactly match the user entry in the LDAP server, including case and spaces.
  14. If you select CERTIFICATE_FILTER in the Certificate mapping field, specify the LDAP filter for mapping attributes in the client certificate to entries in LDAP.

    If more than one LDAP entry matches the filter specification at run time, authentication fails because the result is an ambiguous match. The syntax or structure of this filter is:

    LDAP attribute=${Client certificate attribute}

    For example, uid=${SubjectCN}.

    The first side of the filter specification (LDAP attribute) is an LDAP attribute that depends on the schema that your LDAP server is configured to use. The other side of the filter specification (${Client certificate attribute}) is one of the public attributes in your client certificate. This side must begin with a dollar sign ($) and open bracket ({) and end with a close bracket (}). You can use the following certificate attribute values on this side of the filter specification. The case of the strings is important:
    • ${UniqueKey}
    • ${PublicKey}
    • ${IssuerDN}
    • ${Issuer<xx>}

      where <xx> is replaced by the characters that represent any valid component of the Issuer Distinguished Name. For example, you might use ${IssuerCN} for the Issuer Common Name.

    • ${NotAfter}
    • ${NotBefore}
    • ${SerialNumber}
    • ${SigAlgName}
    • ${SigAlgOID}
    • ${SigAlgParams}
    • ${SubjectDN}
    • ${Subject<xx>}

      where <xx> is replaced by the characters that represent any valid component of the Subject Distinguished Name. For example, you might use ${SubjectCN} for the Subject Common Name.

    • ${Version}
  15. Optional: Select the Require SSL communications option if you want to use Secure Sockets Layer communications with the LDAP server.
    If you select the Require SSL communications option, you can select either the Centrally managed or Use specific SSL alias option.
    Centrally managed
    Enables you to specify an SSL configuration for a particular scope, such as the cell, node, server, or cluster in one location. To use the Centrally managed option, you must specify the SSL configuration for the particular set of endpoints. The Manage endpoint security configurations and trust zones panel displays all of the inbound and outbound endpoints that use the SSL protocol. If you expand the Inbound or Outbound section of the panel and click the name of a node, you can specify an SSL configuration that is used for every endpoint on that node. For an LDAP registry, you can override the inherited SSL configuration by specifying an SSL configuration for LDAP. To specify an SSL configuration for LDAP, complete the following steps:
    1. Click Security > SSL certificate and key management > Manage endpoint security configurations and trust zones.
    2. Expand Outbound > cell_name > Nodes > node_name > Servers > server_name > LDAP.
    Use specific SSL alias
    Select the Use specific SSL alias option if you intend to select one of the SSL configurations in the menu that follows the option.
    This configuration is used only when SSL is enabled for LDAP. The default is DefaultSSLSettings. To modify or create a new SSL configuration, complete the following steps:
    1. Click Security > SSL certificate and key management.
    2. Under Configuration settings, click Manage endpoint security configurations and trust zones > configuration_name.
    3. Under Related items, click SSL configurations.
  16. Click OK.

Results

After completing these steps, your LDAP repository settings are configured.

What to do next