Enabling LDAP 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® App Connect Enterprise 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

You can enable LDAP authentication for an integration node. See Enabling an integration node to use LDAP for authentication. You can also enable LDAP authentication for an integration server. See Enabling an integration server to use LDAP for authentication.

If a web user account has a local password, and LDAP authentication is enabled, the local password is ignored. When LDAP authentication is enabled, all web user logins must be authenticated by using LDAP. Any local passwords are ignored.

Enabling an integration node to use LDAP for authentication

About this task

You can enable LDAP authentication for an integration node by modifying the node.conf.yaml configuration file, by following the steps in the following procedure.
Alternatively, you can enable LDAP authentication for an integration node by running the mqsichangeproperties command. For more information, see Enabling LDAP authentication by using the mqsichangeproperties command.

Procedure

Stop the integration node. See Starting and stopping an integration node on Windows, Linux, and UNIX systems.

Open the node.conf.yaml configuration file for your integration node by using a YAML editor.

If you do not have access to a YAML editor, you can edit the file by using a plain text editor. However, you must ensure that you do not include any tab characters because they are invalid in YAML and would cause your configuration to fail. If you are using a plain text editor, ensure that you use a YAML validation tool to validate the content of your file.

The properties that you need to set are in the Admin Security section of the node.conf.yaml configuration file:

Admin Security:
#  Authentication
  #basicAuth: true                                                    # Clients web user name and password will be authenticated when set true
  #ldapUrl: ldap[s]://server[:port]/baseDN[?[uid_attr][?[base|sub]]]  # ldap authentication url
  #ldapBindDn: ldap::adminAuthentication                              # Resource alias or full bind dn
  #ldapBindPassword: ldap::adminAuthentication                        # Resource alias or bind password
  #  Authorization
  #authorizationEnabled: false     # Clients web user role will be authorized when set true
  #authorizationMode: 'ldap'       # Set authorization mode. Choose 1 of : ldap, file or mq

Set the following properties:
1. Set the basicAuth property to true.
2. Set the ldapUrl property to the URL of your LDAP server.
  If ldapUrl is using TLS ("ldaps") and the server has a certificate that is self-signed or issued by a company-specific CA, then the caPath property in the RestAdminListener section might need to be configured to a directory that contains the public certificates for the server. Otherwise, errors such as BIP2775E with an "UNABLE_TO_GET_ISSUER_CERT_LOCALLY" error code might result.
```
RestAdminListener:
  caPath: '/var/mqsi/ldaps-certs'
```
  The caPath property specifies the file path that contains certificate authority certificates; files in this path must be base-64 encoded PEM files. DER, JKS, P7b, and P12/PFX files are ignored.
3. Optional: Specify the service credentials to be used by the integration node when it binds to the LDAP server during a query. This information is required if the sub option is used in the ldapUrl and your LDAP server does not support anonymous bind.
  To specify these credentials, set the ldapBindDn and ldapBindPassword properties. Set these properties by using one of the following methods.
  - Set the properties in the node.conf.yaml file (which stores the credential in clear text).
  - Set an alias name that you then use with the mqsisetdbparms command.
  - Set an alias name that you then use with the mqsicredentials command to store the LDAP bind DN and password.
Start the integration node. See Starting and stopping an integration node on Windows, Linux, and UNIX systems.
Optional: Configure the web user accounts for each user that you want to authorize. This step is not required if you intend to configure authorization by using LDAP groups. See Configuring authorization by using LDAP groups. The step is required when you use file-based or queue-based authorization. See Configuring administration security to use file-based, queue-based, or LDAP authorization. Either create new web user accounts or modify existing web user accounts:
- Create a web user account by using the mqsiwebuseradmin command. For example,
```
mqsiwebuseradmin intNode -c -u ldapusername -x -r sysrole
```
  where ldapusername is the username 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.
- Modify an existing web user account to remove any local password. For example,
```
mqsiwebuseradmin intNode -m -u ldapusername -x -r sysrole
```
  You can modify an existing web user account to be authenticated by using LDAP only if the existing username matches the username in the LDAP directory. If the usernames do not match, you must create a new web user account.

Enabling an integration server to use LDAP for authentication

Procedure

Stop the integration server. See Stopping an integration server.

Open the server.conf.yaml configuration file for your integration server by using a YAML editor.

Admin Security:
#  Authentication
  #basicAuth: true                                                    # Clients web user name and password will be authenticated when set true
  #ldapUrl: ldap[s]://server[:port]/baseDN[?[uid_attr][?[base|sub]]]  # ldap authentication url
  #ldapBindDn: ldap::adminAuthentication                              # Resource alias or full bind dn
  #ldapBindPassword: ldap::adminAuthentication                        # Resource alias or bind password
  #  Authorization
  #authorizationEnabled: false     # Clients web user role will be authorized when set true
  #authorizationMode: 'ldap'       # Set authorization mode. Choose 1 of : ldap, file or mq

Set the following properties:
1. Set the basicAuth property to true.
2. Set the ldapUrl property to the URL of your LDAP server.
  If the ldapUrl is using TLS ("ldaps") and the server has a certificate that is self-signed or issued by a company-specific CA, then the caPath property in the RestAdminListener section might need to be configured to a directory that contains the public certificates for the server. Otherwise, errors such as BIP2775E with an "UNABLE_TO_GET_ISSUER_CERT_LOCALLY" error code might result.
```
RestAdminListener:
  caPath: '/var/mqsi/ldaps-certs'
```
  The caPath property specifies the file path that contains certificate authority certificates; files in this path must be base-64 encoded PEM files. DER, JKS, P7b, and P12/PFX files are ignored.
3. Optional: Specify the service credentials to be used by the integration server when it binds to the LDAP server during a query. This information is required if the sub option is used in the ldapUrl and your LDAP server does not support anonymous bind.
  To specify these credentials, set the ldapBindDn and ldapBindPassword properties. Set these properties by using one of the following methods.
  - Set the properties in the server.conf.yaml file (which stores the credential in clear text).
  - Set an alias name that you then use with the mqsisetdbparms command.
  - Set an alias name that you then use with the mqsicredentials command to store the LDAP bind DN and password.
Start the integration server. See Starting an integration server.
Optional: Configure the web user accounts for each user that you want to authorize. This step is not required if you intend to configure authorization by using LDAP groups. See Configuring authorization by using LDAP groups. The step is required when you use file-based or queue-based authorization. See Configuring administration security to use file-based, queue-based, or LDAP authorization. Either create new web user accounts or modify existing web user accounts:
- Create a web user account by using the mqsiwebuseradmin command. For example,
```
mqsiwebuseradmin intNode -c -u ldapusername -x -r sysrole
```
  where intNode is the name of the integration node, ldapusername is the username 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.
- Modify an existing web user account to remove any local password. For example,
```
mqsiwebuseradmin intNode -m -u ldapusername -x -r sysrole
```
  You can modify an existing web user account to be authenticated by using LDAP only if the existing username matches the username in the LDAP directory. If the usernames do not match, you must create a new web user account.

What to do next

You might want to authorize users for administration. For more information, see Authorizing users for administration.