Enabling LDAP authentication

You can use Lightweight Directory Access Protocol (LDAP) or Secure LDAP (LDAPS) with IBM® App Connect Enterprise for two purposes: administration security and message flow security. Administration security controls users' permissions to access integration nodes, integration servers, and their resources, and to complete administrative tasks. Message flow security controls access to individual messages in a message flow, by using the identity of the messages. This topic describes part of the process for using LDAP for administration security. 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, as described in Enabling an integration node and its node-managed integration servers to use LDAP for administration authentication. You can also enable LDAP authentication for an integration server, as described in Enabling an independent integration server to use LDAP for administration 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 and its node-managed integration servers to use LDAP for administration 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, as described in Enabling LDAP authentication by using the mqsichangeproperties command.

Procedure

Stop the integration node. For information about how to stop an 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.

You can edit the file by using the built-in YAML editor that is provided in the IBM App Connect Enterprise Toolkit, either by double-clicking the file in the Application Development view or by right-clicking the file and selecting Open with > YAML editor. If you choose to edit the file by using a plain text editor, ensure that you do not include any tab characters (which are not valid in YAML) and use a YAML validation tool to validate the contents 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 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 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. For example:
  - ldapBindDn: CN=XXXXXXXXX-XXXXXX,OU=PSST,OU=SAUsers,OU=PBS,OU=SS,DC=ent,DC=ds,DC=xxx,DC=xxx
  - ldapBindPassword: ldap::adminAuthentication
  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, as described in 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, as described in Configuring authorization by using LDAP groups. The step is required when you use file-based or queue-based authorization, as described in 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 independent integration server to use LDAP for administration authentication

Procedure

Stop the integration server, as described in Stopping an integration server.

Open the server.conf.yaml configuration file for your integration server 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 server.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 the ldapUrl is using TLS ("ldaps") and the server has a certificate that is self-signed or issued by a company-specific CA, 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. For example:
  - ldapBindDn: CN=XXXXXXXXX-XXXXXX,OU=PSST,OU=SAUsers,OU=PBS,OU=SS,DC=ent,DC=ds,DC=xxx,DC=xxx
  - ldapBindPassword: ldap::adminAuthentication
  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, as described in 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, as described in Configuring authorization by using LDAP groups. The step is required when you use file-based or queue-based authorization, as described in 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.