In a prior blog post I introduced the Role-Based Management (RBM) capability that was added to the IBM MQ Appliance in 9.0.1 (see the related links at the end of this article). RBM is a security model for managing appliance (administrative) users and the authorities assigned to them. The IBM MQ Object Authority Manager (OAM) provides the security model for the other type of user on the appliance, known as messaging users, who perform operations such as putting messages to, and getting messages from, queues. One of the options provided by RBM is to use an external LDAP repository instead of defining administrative users locally on the appliance. Using an LDAP repository is particularly useful if you have multiple appliances that you need to secure with the same administrative access policies, or your organization employs a single sign-on solution for I.T. security. LDAP server implementations include OpenLDAP, Microsoft Active Directory and IBM Security Directory Server.
To authenticate using an LDAP repository you need to decide how to map the name of appliance users (what is entered at the login screen) to the distinguished name (DN) of LDAP users. RBM provides two options that allow you to perform this mapping:
- The appliance user ID can be a substring of the distinguished name of an LDAP user.
- The appliance user ID can be a substring of an LDAP filter expression (query) that identifies the distinguished name of an LDAP user.
Option 1: User ID is a substring of the distinguished name
This option is useful when the distinguished name of users contains an attribute such as their common name. When this option is used the distinguished name of a user is built by concatenating a defined prefix and suffix with the user name provided to log in. For example, let’s assume we have defined the prefix to be “cn=” and the suffix to be “ou=abc,o=xyz”. If Bob attempts to log in using a user name of “bob” then the appliance will attempt to bind to the LDAP repository using the password supplied by Bob and a distinguished name of “cn=bob,ou=abc,o=xyz”. Note that when using this option a comma is implicitly added between the user name and the defined suffix if the suffix is not blank. The result of the LDAP bind determines whether the user is successfully authenticated or access is denied.
Option 2: User ID is a substring of a different LDAP user attribute
This option is useful when the distinguished name is comprised of less user-friendly attributes, or a single sign-on model is required, whereby a user logs in using an alternative attribute, such as their e-mail address. To accomplish this the appliance performs an LDAP query to search for the user profile, then it extracts the user’s distinguished name. The distinguished name and the user-supplied password are then used to perform a second bind that authenticates the user. The bind used by the appliance to perform the query can either be anonymous or it can use a pre-configured distinguished name and password.
Let’s assume that this time Bob needs to log in using his email address, “email@example.com” instead of using his common name. The LDAP filter expression used to identify Bob in the LDAP repository is similarly generated by concatenating a defined prefix and suffix with the user name provided to log in. In this example the prefix would be something like “mail=” and the suffix would be blank because the user name is the entire value of the mail attribute. An LDAP Search Parameters object is used to represent the LDAP query that is used to lookup each user’s distinguished name.
In this example Bob’s user name on the appliance is his entire email address, but this might be problematic if the user name also has to be a valid messaging user. This is a requirement when, for example, implementing granular access to the MQ Console (see the related links at the end of this article for another post that describes how to do this). Therefore, care needs to be taken when selecting which LDAP attribute should be used as the appliance user name. However, it is worth noting that the user name can be a substring of an LDAP attribute’s value if the remainder of the value is fixed for all users. By way of example, if all the email addresses have a short mailbox name and they share the same domain then the LDAP search parameters can be configured so that Bob logs in using his mailbox name “bob.smith”, which is also a valid messaging user name. The “@xyz.com” domain can be defined as part of the LDAP filter expression. This is possible because, unlike for the first option when a distinguished name is built up, a comma is not automatically inserted between the supplied user name and the LDAP filter suffix.
Authorisation (credential mapping)
After a user has been authenticated using an LDAP repository it is then necessary to determine which resources are visible to them and what actions they are permitted to perform. This step is commonly called authorisation, but on the appliance it is also referred to as credential mapping – the mapping of authenticated users (credentials) to access profiles. The appliance can be configured to perform this mapping using the following options:
- The distinguished name of authenticated users can be mapped to an access profile using an XML file, either directly or via a group that is also defined in the file.
- The appliance can be configured to perform a further LDAP query to lookup the groups the user is a member of, based on the user’s distinguished name, in the same or a different LDAP repository. A specified attribute of each returned group is then mapped to an access profile using either an XML file or locally defined groups. The user is assigned the superset of the authority that is assigned to those groups.
Option 1: Credential mapping for LDAP users
To authorise users based on their distinguished name an XML file needs to be constructed that maps the distinguished name of users to access profiles. This mapping can use regular expressions to match distinguished names to reduce the number of definitions that must be specified in the file. The file can either be created by hand then uploaded to the appliance, or it can be created using a wizard that is provided in the web UI. To construct the file using the wizard perform the following steps:
- In the RBM Settings configuration set the credential mapping method to XML File
- Click New next to XML file URL
- Select an existing XML file to start with (optional)
- Leave the Default Credential Name blank (this is only applicable to XML file authentication)
- Skip past Defining User Identities (also only applicable to XML file authentication)
- At the Access Profile Mappings step define the required credential mappings (see below)
- Finally, specify a name and location for the XML file and proceed to save it. The fully-qualified location of the file must then be specified in the RBM settings, for example local:///rbm-ldap-authorities.xml
When defining the access profile mappings:
- The Credential Name is a pattern that matches the distinguished name of one or more users, or it is the name of a group.
- The Access Profile is the set of access policies that define what authority is to be granted, or it is the name of a group to recursively search for.
Consider the following definitions:
The definitions illustrate how to grant Bob full access by mapping his distinguished name to an access profile. The access profile contains a single access policy that grants full access (read, write, add, delete and execute permission) to all resources. It could alternatively contain a list of more granular access policies that grant/restrict access to different resources. In this example all other users in the same organisational unit are granted read-only access using an indirect mapping to a group called "guest". Bob is not mapped to the guest profile because the more specific rule for his distinguished name takes precedence. The use of a group does not add any value in this trivial example because only one credential name/pattern maps to it. However, its use would avoid repetition when multiple users need to be granted the same access and a simple regular expression cannot be used for the credential name to identify them.
Option 2: Credential mapping for LDAP groups
To authorise users based on LDAP groups the appliance needs to be configured to perform a further LDAP query to lookup the groups the authenticated LDAP user is a member of. This query does not have to use the same LDAP repository. To configure the LDAP query select the option Search LDAP for group name then define the LDAP connection and search parameters in the same way as per for authentication. The input value to the LDAP search is the distinguished name of the LDAP user, not the user name entered to log in. The filter prefix is likely to be something like “member=”. The attribute returned by the LDAP search can be any attribute from the LDAP group object, such as its common name (or its distinguished name if you prefer). A credential mapping then needs to be configured using either an XML file or local group objects.
Credential mapping for LDAP groups using an XML file
An XML file needs to be constructed, similar to when performing credential mapping for users, except this time the input credential names correspond to the values of the attribute returned by the LDAP search. For example, if the common name (CN) for each group is returned by the search then the credential name values in the XML file are the values of the common name attribute. If a user is a member of multiple groups in the LDAP repository then the access granted for the groups is combined. This can be useful when mapping users to one or more roles.
Instead of defining the authority for each LDAP group in an XML file this information can alternatively be defined using local group objects. To do this select the credential mapping method Local user group. Instead of creating an XML file define a local user group for each LDAP group that you wish to grant authorities to, naming the local group after the value of the attribute returned by the LDAP search. For example, if the configured LDAP search returns the common name (CN) of each LDAP group that the authenticated user is a member of, then local groups must be defined with names that match the LDAP common name values.
Defining authorities using local user group objects has the advantage that the same definitions can be used for both LDAP and fallback users (see tolerating LDAP server outages). However, when managing multiple appliances it has the disadvantage that replicating the group object definitions is more complex than copying a single XML file between them.
Anonymous versus authenticated binds
If an appliance is configured to perform an LDAP query, either to search for the distinguished name of a user or to search for the groups a user is a member of, the connection to the LDAP repository can either use an anonymous bind or an authenticated bind. The default option is to use an anonymous bind, but if these are not permitted the appliance can be configured to connect using a specific user and password. To use an authenticated bind specify values for the LDAP bind DN and LDAP bind password alias properties.
Tolerating LDAP server outages
If an appliance is configured to connect to an LDAP repository it is important to cater for when the repository is not available or when it cannot be contacted due to a network outage. The appliance supports two capabilities that help mitigate this scenario:
At least one fallback user should always be configured if LDAP authentication is used. A fallback user is a local user that can also log in to the appliance. A fallback user is essential when the LDAP repository cannot be contacted or if the LDAP settings have not been configured correctly. If you have not defined a fallback user then the only remaining option in the event of an LDAP outage is to use the built-in "admin" account to log in via the serial connection.
Load balancer groups
The appliance can be configured to connect to a pool of LDAP repositories instead of a single server. Using a load balancer group provides workload balancing to spread requests over multiple LDAP servers, plus it offers higher availability for LDAP connectivity. The appliance can be configured to distribute its requests using a number of approaches, including round-robin, weighted round robin or first alive. The latter approach is useful when a primary server should receive all requests under normal operation but a secondary server has been configured as a backup.
Secure versus unsecure LDAP connections
The appliance can be configured to connect to an LDAP repository using either the LDAP or the LDAPS protocol. The LDAPS protocol uses a connection that is secured using SSL/TLS. When using the LDAP protocol the port used to connect to the LDAP server is usually 389. When using the LDAPS protocol the port is usually 636. To use LDAPS set SSL client type to Client Profile and configure an SSL client profile object. The SSL client profile object defines how to establish the SSL/TLS connection, including:
- The supported SSL/TLS protocols
- The supported SSL/TLS ciphers
- Whether to use optional features, such as Server Name Indication (SNI)
- Whether to present a client certificate (identification credentials) to the LDAP server (optional)
- Whether to validate the certificate presented by the LDAP server (optional)
If the LDAP repository supports both the LDAP and the LDAPS protocol then it is suggested to use the following approach when configuring an appliance to narrow the scope of any configuration errors:
- First configure the appliance to use the LDAP protocol so the authentication and credential mapping settings can be verified
- Next, change the appliance to use the LDAPS protocol without certificate validation
- Finally, if required, configure the appliance to validate the certificate presented by the LDAP server. Validation can be performed by either requiring a specific certificate, requiring a certificate signed by a specific issuer, or performing full certificate chain checking (PKIX).
Caching credential information
The RBM settings on the appliance can be optionally configured to cache credential information. When an appliance is configured to use an LDAP repository caching credentials reduces the number of bind and query requests the appliance sends to the LDAP server(s). This is because the appliance remembers the responses for a configurable period of time.
This blog article describes how to configure the IBM MQ Appliance to authenticate users using an LDAP repository and optionally authorise them based on LDAP groups they are a member of. There is a lot of information in this article but hopefully it provides a good reference for anyone who needs to configure this role based management option. If there are other subjects you would like discussed on MQdev please let us know.
IBM MQ and IBM MQ Appliance 9.0.1 Continuous Delivery Releases are available
Introducing the MQ Appliance Version 9.0.1
IBM MQ Appliance 9.0.x KnowledgeCenter
Introducing Role-Based Management (RBM) for the IBM MQ Appliance
Configuring access to the MQ Console and CLI on the IBM MQ Appliance