Configuring LDAP Authentication

To successfully enable LDAP authentication for CLI users and/or LDAP authorization for clients, the following must be configured:

• on external host machines, up to three LDAP servers
• on the Solace PubSub+ event broker, up to ten LDAP profiles

For information about LDAP authorization for clients, see Configuring Client LDAP Authorization.

Configuring LDAP Servers

To successfully enable LDAP authentication for CLI users and/or LDAP authorization for clients, an LDAP administrator must install and configure an LDAP server on an external host machine. For information on choosing a host machine and installing the server software, refer to the third-party LDAP server documentation.

Configuring LDAP Profiles

For LDAP authentication of CLI users and/or LDAP authorization of clients to function, an LDAP profile must be configured on the event broker and be enabled. An LDAP profile contains authentication/authorization request retry timeout values and LDAP authentication/authorization configurations for each of the LDAP servers used by the LDAP profile. Each LDAP profile can use up to three LDAP servers, and up to ten LDAP profiles can be configured.

At a minimum, a system administrator must configure at least one reachable LDAP server and a search base-dn for the LDAP profile. The LDAP profile must then be enabled (refer to Enabling LDAP Profiles).

• To create a new LDAP profile, enter the following CONFIG level command:

  solace(configure)# authentication
  solace(configure/authentication)# create ldap-profile <profile-name>

• To edit properties for an existing LDAP profile, enter the following CONFIG level command:

  solace(configure)# authentication
  solace(configure/authentication)# ldap-profile <profile-name>

Where:

<profile-name> is the name of the LDAP profile. An LDAP profile name can contain up to 32 alphanumeric characters and underscores.

The no version of this command, no ldap-profile <profile-name>, deletes the specified LDAP profile from the event broker (the LDAP profile named default, however, cannot be deleted). Before deleting a LDAP profile:

• it must be disabled through the shutdown LDAP Profile Authentication CONFIG command
• no other configured objects can refer to it

When an LDAP profile is created, it is not automatically enabled. To enable an LDAP profile, you must enter the no shutdown LDAP Profile Authentication CONFIG command (refer to Enabling LDAP Profiles).

After setting the ldap-profile, you can configure the following parameters:

• Allowing Unauthenticated Authentication
• Configuring Admin Distinguished Names
• Configuring Search Parameters
• Enabling LDAP Profiles
• Enabling TLS/SSL Encryption
• Registering LDAP Servers

Allowing Unauthenticated Authentication

To configure an LDAP profile to allow unauthenticated authentication for all clients (if LDAP is the provisioned authentication method on the event broker), enter the following CONFIG command:

solace(configure/authentication/ldap-profile)# allow-unauthenticated-authentication

The no version of this command, no allow-unauthenticated-authentication, turns off unauthenticated authentication by LDAP (the default) so that all clients of LDAP profiles that attempt to connect without passwords are rejected immediately by the event broker without consulting the LDAP server.

Configuring Admin Distinguished Names

To configure the credentials of the event broker in the current LDAP profile for connecting to an LDAP server, enter the following CONFIG command:

solace(configure/authentication/ldap-profile)# admin dn <admin-dn> password <admin-password>

Where:

<admin-dn> is the LDAP distinguished name for the event broker to use to authenticate itself to the LDAP server.

<admin-password> is the password to use with the admin distinguished name to bind to the LDAP server.

Configuring Search Parameters

To configure search parameters in the current LDAP profile for connecting to an LDAP server, enter the following CONFIG command:

solace(configure/authentication/ldap-profile)# search [base-dn <distinguished-name> | deref {never | search | base | always} | filter <filter> | follow-continuation-references | scope {base | one-level | subtree} | timeout <duration>]

Where:

base-dn sets the base node for searches:

• <distinguished-name> is the LDAP distinguished name of the node of the directory tree to start searches from. For example: “ou=software,dc=solacesystems,dc=com”

deref configures the alias dereferencing behavior of directory searches:

• never—never dereference aliases
• search—only dereference aliases when searching
• base—only dereference aliases when locating the base node
• always—always dereference aliases (default)

filter sets the templated filter to use to locate individual users in the directory service:

• <filter> is the filter string used to search for directory entries.

  The following substitution variables can be added to the filter:

  • $CLIENT_USERNAME
  • $VPN_NAME

    Substitution variables are recognized by the event broker and are substituted with the client’s relevant information. Examples of filters using substitution variables:

    • “(&(cn=$CLIENT_USERNAME)(ou=$VPN_NAME))”
    • “(cn=$CLIENT_USERNAME)”

    When using LDAP to authenticate and/or authorize users, the username is substituted into the variable $CLIENT_USERNAME in the filter string.

follow-continuation-references enables or disables the following of continuation references returned by the contacted LDAP server. When this parameter is enabled, if an LDAP search does not fully end on the contacted server, the search for relevant entries may continue on up to ten other servers it references. By default, this parameter is enabled.

scope configures the scope of directory searches:

• base—search only the base node
• one-level—search only one level deep
• subtree—search the entire subtree directory (default)

timeout configures the amount of time (in seconds) to wait before retrying an authentication or authorization request to a LDAP server:

• <duration> is an integer from 1 to 40 that indicates the amount of time (in seconds) to wait to retry a request. This is the amount of time the LDAP server has to complete a search request.

There are two configurable timeouts related to LDAP requests. One is for LDAP lookup of the username and password, and the other is for the lookup of the client's group membership.

Enabling LDAP Profiles

• To enable the current LDAP profile on the event broker, enter the following CONFIG command:

  solace(configure/authentication/ldap-profile)# no shutdown

• To disable the current LDAP profile on the event broker, enter the following CONFIG command:

  solace(configure/authentication/ldap-profile)# shutdown

By default, LDAP profiles are not enabled on an event broker.

Enabling TLS/SSL Encryption

There are two ways to enable TLS/SSL encryption for LDAP Authentication: StartTLS and LDAPS.

LDAP authentication with StartTLS—A plaintext LDAP connection established over the default port 389, which is upgraded to a secure connection.

To enable TLS/SSL encryption with StartTLS in the current LDAP profile, enter the following CONFIG command:

solace(configure/authentication/ldap-profile)# starttls

The no version of this command, no starttls, disables TLS for the current LDAP profile.

LDAP authentication with LDAPS—A secure connection, by default, over port 636

To enable an encrypted connection using LDAPS, add ldaps:// as the prefix to the LDAP server name specified in the ldapserver parameter. Refer to Registering LDAP Servers for more information.

Registering LDAP Servers

To register the connection information for each LDAP server used by the LDAP profile, enter the following CONFIG command for each host:

solace(configure/authentication/ldap-profile)# ldap-server <ldap-host> index <server-index>

Where:

<ldap-host> is the Uniform Resource Indicator (URI) of the LDAP server. A system administrator can specify an IP address and port number (if a number is not specified, port 389 is used by default) or a domain name. For example, “ldap://192.167.123.4:389” or “ldap://ldap.solace.com”.

<server index> is the priority index of the host to be provisioned. Valid values are 1, 2, or 3.

The no version of this command, no ldap-server {<ldap-host> | index <server-index>}, deprovisions the LDAP host, as indicated by a URI or the server index, and deletes all associated configuration values from the Solace PubsSub+ event broker.

Using TLS/SSL

By default, information sent between the Solace PubSub+ event broker (the LDAP client) and the LDAP server during the authentication process is sent as plain text. If better protection of information passed between the event broker and a provisioned LDAP server is required, TLS/SSL can be used to encrypt the communication. As mentioned in Enabling TLS/SSL Encryption, you can configure TLS/SSL support for LDAP Authentication using StartTLS or LDAPS.

To use LDAP authentication/authorization over TLS/SSL, an LDAP profile enabled for TLS/SSL must be used, and the event broker must be configured with a list of Certificate Authority (CA)-approved certificates.

Configuring TLS Support for LDAP Authentication

To support TLS/SSL encryption for connections to LDAP servers, do the following:

1. You can enable a secure connection using StartTLS or LDAPS.

   • To enable a secure connection using StartTLS, using the following command:

   solace(configure/authentication/ldap-profile)# starttls

   The starttls setting is ignored if an LDAP-server host URL is specified with LDAPS protocol.

   • To enable a secure connection using LDAPS, in Step 3 below, add ldaps:// as the prefix to the LDAP-server name specified in the ldapserver parameter.
2. Import and load trusted CA certificates onto the event broker (refer to Configuring the Domain Validation Certificate Authorities List).
3. Configure an LDAP server for an LDAP profile on the event broker for TLS/SSL service through the ldap-server LDAP Profile Authentication CONFIG command. Refer to Registering LDAP Servers for configuration instructions.

When configuring an LDAP server for TLS/SSL, the hostname or IP address must match the subject or a subject alternative name of the LDAP server's certificate.

For example, if the LDAP server hostname is ldap.solace.com, you could use the Solace CLI to verify the server name:

solace# shell “debug”

login: support
Password: 
[support@solace ~]$ openssl s_client -connect ldap.solace.com:636

This returns the certificate, and the server specified in the certificate is the CN of the certificate subject, for example:

subject=/CN=ldap.solace.comQh

If you are using StartTLS, when configuring an LDAP server on the event broker, the unencrypted port should be specified for the server hostname.

Viewing Event Brokers’ Trusted CA Certificates

To view the event broker’s trusted CA certificates, enter the following User EXEC command:

solace> show domain-certificate-authority ca-name <ca-name> [cert [raw-content]

Where:

<ca-name> is the name of the certificate authority.

raw-content specifies to show the CA certificate's raw content.

Configuring LDAP Groups

CLI users can belong to an LDAP group that can be used to authorize CLI users. Specific access levels are configured for each LDAP group.

A CLI user may belong to more than one LDAP group, and the access levels defined for each group may differ. In this case, the greatest global access level and the greatest Message VPN access level access level defined in the groups the CLI user is a member of are used.

To create an LDAP group object that represents an LDAP group that exists on the LDAP server, enter the following CONFIG commands:

solace(configure)# authentication 
solace(configure/authentication)# user-class cli
solace(configure/authentication/user-class)# access-level
solace(...uthentication/user-class/access-level)# ldap
solace(...tication/user-class/access-level/ldap)# create group <group-name>

Where:

group-name is the name of an LDAP group that exists on the LDAP server. LDAP names can contain up to 256 alphanumeric characters, except the ‘*’ or ‘?’ characters, and the first character may not be ‘#’. Additional things to consider about the group name:

• If the group name contains the characters “#”, “+”, “;”, “=”, the LDAP server may return the value of the group name where those characters are appended with a “\” character. For example, for a group name of “test#,lab,com”, the LDAP server could return “test\#,lab,com”. The exact handling of these special characters depends on the LDAP server provider that is used.
• To edit the properties for an LDAP group that has already been provisioned on the event broker, enter the following CONFIG command: solace(...tication/user-class/access-level/ldap)# group <group-name>.
• The group name is case sensitive and must match the case of the groups returned by the LDAP server.

The no version of this command, no group name <group-name>, removes the given group name.

Assigning Global Access Levels

To assign a global access level for CLI users that belong to a given LDAP group, enter the following CONFIG command:

solace(...on/user-class/access-level/ldap/group)# global-access-level [none | read-only | mesh-manager | read-write | admin]

Where:

none specifies a global access level of none.

read‑only specifies a global access level of read-only. The default value is read‑only.

mesh-manager specifies a global access level of mesh-manager.

read-write specifies a global access level of read-write.

admin specifies a global access level of admin.

Assigning Message VPN Default Access Levels

To assign a Message VPN default access level for CLI users that belong to a given LDAP group, enter the following CONFIG commands:

solace(...on/user-class/access-level/ldap/group)# message-vpn
solace(...s/access-level/ldap/group/message-vpn)# default-access-level [none|read-only|read-write]

Where:

none specifies a default Message VPN access level of none. The default value is none.

read‑only specifies a default Message VPN access level of read-only.

read-write specifies a default Message VPN access level of read-write.

Configuring Message VPN Default Access Level Exceptions

To configure an exception to the default Message VPN access level for CLI users that belong to the given LDAP group, enter the following CONFIG command:

solace(c...s/access-level/ldap/group/message-vpn)# create access-level-exception <vpn-name> access-level [none|read-only|read-write]

To modify an existing exception to the default Message VPN access level for CLI users that belong to the given LDAP group, enter the following CONFIG command:

solace(...lass/access-level/default/message-vpn)# access-level-exception <vpn-name> access-level [none|read-only|read-write]

Where:

<vpn-name> is the name of a Message VPN that the exception to the default Message VPN access level will apply to.

none specifies a Message VPN access level of none. The default value is none.

read‑only specifies a Message VPN access level of read-only.

read-write specifies a Message VPN access level of read-write.

The no version of this command, no access-level-exception, removes any exceptions so that the CLI user has the default Message VPN access level for all Message VPNs.

The number of permitted Message VPN default access level exceptions is not limited, except that it cannot exceed the number of existing Message VPNs on the event broker.

Configuring Group Membership Attribute Names

To authenticate a CLI user, a group membership attribute name must be retrieved from the LDAP server as part of the LDAP search.

The attribute name indicates that the CLI user belongs to a particular group that exists on the LDAP server and is referenced through an instance provisioned on the Solace PubSub+ event broker (refer to Configuring LDAP Groups). For example, the attribute name of “memberOf” could be used for an Active Directory‑based LDAP server.

To set a group membership attribute name for user authentication, enter the following CONFIG commands:

solace(configure)# authentication
solace(configure/authentication)# user-class cli
solace(configure/authentication/user-class)# access-level
solace(...uthentication/user-class/access-level)# ldap
solace(...tication/user-class/access-level/ldap)# group-membership-attribute-name <attribute-name>

Where:

<attribute-name> is the name of the attribute the event broker attempts to retrieve from the LDAP server in a search response. An attribute name can contain up to 64 alphanumeric characters.

The no version of this command, no group-membership-attribute-name <attribute-name>, deletes the LDAP group membership attribute name from the event broker. When using LDAP for CLI user authentication, deleting this attribute results in all future CLI users getting the default access levels (refer to Configuring Default CLI User Access Levels with External Authentication).

Enabling LDAP Group Membership Secondary Searches

A typical LDAP server deployment has the group membership information stored in the user records that allows the group list to be retrieved right away. However, you can also use an LDAP group membership secondary search that retrieves an attribute from the user records, and then performs a secondary LDAP search using that attribute’s value to retrieve the group list. By default, LDAP group membership secondary search is not enabled.

To use LDAP group membership secondary search, you must make the following configuration steps.

The CLI examples shown modify the LDAP profile named default.

Step 1: Specify the attribute that needs to be retrieved from the primary search.

Enter the following CONFIG commands:

solace # configure
solace (configure)# authentication
solace (configure/authentication)# ldap-profile default
solace (configure/authentication/ldap-profile)# group-membership-secondary-search
solace (...ile/group-membership-secondary-search)# filter-attribute-from-primary-search <value>

Where:

<value> is the attribute name that the primary search should retrieve from the LDAP server.

Step 2: Provide a substitution variable for the secondary search filter.

When a secondary search is used, a secondary search filter expression substitutes the search attribute value returned from the primary search with a secondary search filter expression using substitution variable $ATTRIBUTE_VALUE_FROM_PRIMARY_SEARCH.

Enter the following CONFIG commands:

solace # configure
solace (configure)# authentication
solace (configure/authentication)# ldap-profile default
solace (configure/authentication/ldap-profile)# group-membership-secondary-search
solace (...ile/group-membership-secondary-search)# filter <filter>

Where:

<filter> is the filter to use to locate user entries in a directory service. The event broker will recognize the substitution variables and substitute the user's relevant information. The following substitution variables can be added to the filter:

• $ATTRIBUTE_VALUE_FROM_PRIMARY_SEARCH
• $CLIENT_USERNAME
• $VPN_NAME

An example of filters using substitution variables is member=$ATTRIBUTE_VALUE_FROM_PRIMARY_SEARCH

Step 3: Enable LDAP group membership secondary searches for the event broker.

Enter the following CONFIG commands:

solace# configure
solace(configure)# authentication
solace(configure/authentication)# ldap-profile default
solace(configure/authentication/ldap-profile)# group-membership-secondary-search
solace(...ile/group-membership-secondary-search)# no shutdown