Enabling an integration node to use LDAP for authentication

Web user accounts can be authenticated against a Lightweight Directory Access Protocol (LDAP) or Secure LDAP (LDAPS) server. You can authenticate web users by using the REST API, the web user interface, the IBM® Integration Toolkit, or custom integration applications that use the Integration API.

Before you begin

Ensure that you have an LDAP server that is LDAP Version 3 compliant, for example:

IBM Tivoli® Directory Server
Microsoft Active Directory
OpenLDAP

About this task

If your LDAP directory does not permit unrecognized user IDs to log in, and does not grant search access rights on the subtree, you must set up a separate, authorized ID that the integration node can use for the search. For more information, see Configuring authorization with LDAP or Authenticating incoming requests with LDAP.

Procedure

Open a command window that is configured for your environment.
To set the LDAP server that you want to use for authentication, enter the following command on the command line.
```
mqsichangeproperties intNode -b webadmin -o server -n ldapAuthenticationUri
-v "ldapURL" 
```
where intNode is the name of your integration node and ldapURL is the URL for your LDAP.
Enter the ldapURL by using the following syntax:
```
ldap[s]://server[:port]/baseDN[?[uid_attr][?[base|sub]]] 
```
ldap or ldaps

(Required) Fixed protocol string. Use ldaps to specify that SSL is used.

server

(Required) Name or IP address of the LDAP server.

port

(Optional) Port on the LDAP server. If SSL is not enabled, the default port is 389. If SSL is enabled, the default port is 636.

baseDN

(Required) String that defines the base distinguished name (DN) of all users in the directory. If users exist in different subtrees, specify a common subtree under which a search on the user name uniquely resolves to the required user entry, and set the sub attribute.
If users who need access to the integration exist in multiple base DNs, you can specify more than one base DN in the ldapURL by enclosing each base DN in parentheses. The following syntax shows how to specify the ldapURL when users exist in 3 base DNs:
ldap[s]://server[:port]/|(baseDN1)(baseDN2)(baseDN3)[?[uid_attr][?[base|sub]]]
uid_attr

(Optional) String that defines the attribute to which the incoming user name maps, typically uid, CN, or email address. The default is uid.

base or sub

(Optional) Defines whether to perform a base or subtree search. If base is selected, the authentication is faster because the DN of the user is constructed from the uid_att, username, and baseDN values. If sub is selected, a search must be performed before the DN can be resolved. The default is sub.
For example:
```
ldap://ldap.acme.com:389/ou=sales,o=acme.com
```
or
```
ldaps://localhost:636/ou=sales,o=acme?cn?base
```
Note:
Put public server certificates in the integration node truststore for use with LDAPS connections; do not put them in the webadmin truststore.
Configure the web user accounts for each user that you want to authenticate. Either create new web user accounts or modify existing web user accounts:
- Create a new web user account by using the mqsiwebuseradmin command. For example:
```
mqsiwebuseradmin intNode -c -u ldapusername -x -r sysrole
```
  where ldapusername is the user name in the LDAP directory, and sysrole is the role to associate with the web user account. For more information about roles, see Role-based security.
  Note: If you add a local password by using the -a parameter, the local password is used instead of LDAP authentication.
- Modify an existing web user account to remove any local password. For example:
```
mqsiwebuseradmin intNode -m -u ldapusername -x -r sysrole
```
  Note: You can modify an existing web user account to be authenticated by using LDAP only if the existing user name matches the user name in the LDAP directory. If the user names do not match, you must create a new web user account.