chldap

Edit online

Use the chldap command to change system-wide Lightweight Directory Access Protocol (LDAP) configuration. This command can be used to configure remote authentication with LDAP. These settings apply when authenticating against any of the LDAP servers configured using the mkldapserver command.

Syntax

Read syntax diagramSkip visual syntax diagram chldap -typeaditdsother-reset-usernameusername-password'password'-encpassword'password'-securitytlssslnone-userattributeuser_attribute-groupattributegroup_attribute-auditlogattributeauditlogattribute-authcacheminutesauth_cache_minutes-nestedgroupsearchclientserveroff

Parameters

-type ad |itds|other | -reset
(Optional) Specify the LDAP server type, or reset LDAP configuration to defaults for the current server type. Defaults for the configured server type:
  • Active Directory (AD)
  • IBM Security Directory Server (ISDS)
  • Other
-username username
(Optional) Specifies a username for administrative binding. This can be:
Note:
  • A distinguished name (DN)
  • A user principal name (UPN) or NT login name for Active Directory
-password password
(Optional) Specifies the password for the administrative binding. You can optionally specify the password with this parameter. You must enclose the password in single quotation marks. If you do not specify the password, the system prompts you for it before running the command and does not display the password that you type. Do not enclose the password in single quotation marks if you use the prompt.
-encpassword password
(Optional) Specifies the password for the enclosure. You can optionally specify the password with this parameter. You must enclose the password in single quotation marks. If you do not specify the password, the system prompts you for it before running the command and does not display the password that you type. Do not enclose the password in single quotation marks if you use the prompt.
-security tls | ssl | none
(Optional) Specifies the type of security to use when communicating with LDAP servers. Specifying tls enables Transport Layer Security (TLS) security. Specifying ssl enables Secure Socket Layer (SSL) security. The default value is none.
-userattribute user_attribute
(Optional) Specifies the LDAP attribute used to determine the user name of remote users. The user attribute must exist in your LDAP schema and must be unique for each of your users.
-groupattribute group_attribute
(Optional) Specifies the LDAP attribute used to determine the group memberships of remote users. The attribute must contain either the DN of a group or a colon-separated list of group names.
-auditlogattribute auditlogattribute
(Optional) Specifies the LDAP attribute used to determine the identity of remote users. When a user performs an audited action, this information is recorded in the audit.
-authcacheminutes auth_cache_minutes
(Optional) Specifies the period for which to cache authentication details.
-nestedgroupsearch client | server | off
(Optional) Specifies whether nested groups are evaluated on the client (clustered system), server (authentication service), or are not evaluated not at all.

Description

At least one parameter must be specified.

The chldap command can be run whether or not LDAP authentication is enabled. Specifying -reset or -type populates the default values unless otherwise specified.

You can only specify -password or -encpassword if -username is specified.

The -type parameter values are only set to defaults for the specified type if the type is different from the existing type.

If the type is itds, -nestedgroupsearch cannot be executed (nested groups are evaluated by default). If the type is ad, -nestedgroupsearch can only be set to client or off because there is no server support. If the type is other, the -nestedgroupsearch parameter is fully configurable.

Use -username to specify a distinguished name (DN), user principal name (UPN), or NT login name. Distinguished names (DN) must be a sequence of attribute=value pairs separated by a comma (,), semi-colon(;), or plus sign (+). A backslash (\,) must be used to escape special characters, and can also be used to specify UTF-8 characters using their byte encoding. For example, c acute can be represented as \C4\87. NT logins are valid for only the Active Directory and must be in the DOMAIN\user format. These logins must not start or end with a period (.) and both the DOMAIN and the user must not use the following characters: \/:?"<>| UPN logins are valid for Active Directory only and must be in the format user@suffix. Both user and suffix can not use spaces or the following characters: ()<>,;:\"[]@

Tip:
  • Remember that -userattribute, -groupattribute, and -auditlogattribute accept values that:
    1. Must begin with a letter
    2. Only contain ASCII letters, digit characters, and hyphens
    3. Are case-insensitive
The following LDAP (first-time) configuration suggestions assist with LDAP server setup:
Important:
  • Ensure that the system is configured appropriately according to your LDAP schema. Issue chldap -type to populate the system's LDAP configuration with the server type defaults. Issue chldap -reset to return to these defaults at any time.
    • (Advanced) For all server types, users are authenticated with a username configured in the LDAP attribute user_attribute. This attribute must exist in the LDAP schema and must be unique for each user. It is configurable by issuing chldap -userattribute. Active Directory users can also authenticate using their UPN or NT login names.
    • (Advanced) Authenticated users are assigned roles according to their LDAP group memberships. Each user's group memberships must be stored in the LDAP attribute group_attribute. This can be either an LDAP attribute containing the DN of the user's LDAP group, or an LDAP attribute containing a colon-separated list of user group names. It is configurable by issuing chldap -groupattribute.
    • (Advanced) When an LDAP authenticated user runs a command that is audited, the user's login name is placed in the audit log. The name is extracted from the LDAP attribute audit_log_attribute, which is configurable by issuing chldap -auditlogattribute.
  • Ensure that the system is able to search within the user and group trees on LDAP servers. By default the system authenticates anonymously. Consequently, you must either permit anonymous searches of the LDAP directory, or create an LDAP user with the appropriate permissions and issue the chldap -username and chldap -password commands to instruct the system to search as this user.
  • Ensure that the system is able to connect with the appropriate level of security. Passwords are sent to the LDAP server as clear text, so Transport Layer Security (TLS) encryption is recommended. Issue chldap -security to change the security level.
  • (Advanced): On Active Directory and some other LDAP servers, the system (by default) identifies groups to which users belong directly. To assign users permissions according to a parent group, enable the nested group search on the client by issuing chldap -nestedgroupsearch. This setting has an additional performance overhead and supports up to 8 levels of nesting.

An invocation example

chldap -type
itds -username uid=joebloggs,cn=admins,dc=company,dc=com -password 'passw0rd'
-auditlogattribute descriptiveName

The resulting output:

No feedback