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
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 ldapUrl
-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 username
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 three 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 username maps, typically uid,
CN, or email address. The default is uid.
base
or sub
- (Optional) Defines whether to run 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 completed 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
Put public server certificates in the integration node truststore for use with LDAPS connections;
do not put them in the webadmin truststore.
- Optional: If you want to configure authorization by using LDAP groups, you
must set the authorizationMode property to
'ldap'
, by using
the mqsichangeauthmode command, or by setting it in the
.yaml configuration file.
If you set the authorizationMode property to 'file'
, or
'mq'
, and you enabled LDAP authentication, you must configure the authorization
role for web user account for each user that you want to authorize. To configure the role for each
web user, either create new web user account or modify any existing web user accounts as
follows:
- 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.If you add a local password by using the
-a parameter, 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.
- 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.