Configuring Authentication to Event Broker Services

PubSub+ Cloud allows microservices to connect to your event broker service with Basic Authentication (internal database or LDAP), user authentication through LDAP management access, client certificate authentication (also known as mutual TLS), and OAuth provider authentication.

Management access to event broker services using single sign-on (SSO) is configured separately. For more information, see Configuring Single Sign-On for Event Broker Services.

This section includes the following tasks:

• Configuring Basic Authentication
• Configuring LDAP Client Authentication
• Configuring LDAP for Management Access
• Configuring Client Certificate Authentication
• Controlling When an Event Broker Service Requests a Certificate
• Configuring OAuth Provider Authentication
• Configuring User Access to Event Broker Services with Role-Based Access Control
• Configuring OAuth Profiles on Event Broker Services for Direct User and Machine Authentication

Configuring Basic Authentication

Basic authentication is the default client authentication scheme for PubSub+ Cloud event broker services. You can use basic authentication with an internal database or LDAP server.

To view or manage basic authentication settings, perform the following steps:

1. Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your authentication scheme. For more information, see Logging In to the PubSub+ Cloud Console.
2. Select Cluster Manager from the navigation bar.
3. Select the event broker service for which you want to configure basic authentication. If the event broker service is not listed, make sure you have the right environment selected. For more information, see Selecting and Changing Environments.
4. On the Service Details page, click the Manage tab.
5. Click the Authentication tile.
   
6. Basic Authentication is enabled by default. You can set the basic authentication type (Internal Database or LDAP) in the Type list. To use LDAP authentication, an LDAP profile must be configured.
   

   We do not recommend disabling Basic Authentication. If you disable Basic Authentication, your event broker service could become accessible to anyone.

7. Click Save.

Configuring LDAP Client Authentication

You can configure basic authentication with LDAP to ensure only authorized applications connect to the event broker service. Any event broker service can be linked to an existing LDAP server to authenticate clients. You must configure an LDAP profile in the Cloud Console and point the event broker service to an existing LDAP server.

To configure the LDAP profile for your event broker service, perform following steps:

1. Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your authentication scheme. For more information, see Logging In to the PubSub+ Cloud Console.
2. Select Cluster Manager.
3. Select an event broker service. If the event broker service is not listed, make sure you have the right environment selected. For more information, see Selecting and Changing Environments.
4. On the Service Details page, click the Manage tab.
5. Click the Authentication tile.
6. Expand the LDAP Profile section and enter the appropriate details for the following settings:

   Setting	Description
   Admin Distinguished Name	LDAP distinguished name for the event broker service to use to authenticate itself to the LDAP server.
   Admin Distinguished Name Password	Password to use with the admin distinguished name to bind to the LDAP server.
   Start TLS	A plain-text LDAP connection established over the default port 389, which is upgraded to a secure connection.
   Base Distinguished Name	The LDAP distinguished name of the node of the directory tree to start searches from.
   Dereferencing Behaviour	Dereferencing behavior of directory searches. always—always dereference aliases (default) never—never dereference aliases search—only dereference aliases when searching base—only dereference aliases when locating the base node
   Filter	Sets the templated filter to use to locate individual users in the directory service. By default, the filter field is filled in with client username. 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, the username is substituted into the variable $CLIENT_USERNAME in the filter string
   Scope	The scope of directory searches. subtree—search the entire subtree directory (default) base—search only the base node one-level—search only one level deep
   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.
   Timeout (Seconds)	The amount of time (in seconds) to wait before retrying an authentication or authorization request to an LDAP server.
   Group Membership Secondary Search Enabled	Retrieves an attribute from the user records, and then performs a secondary LDAP search using that attribute’s value to retrieve the group list.

7. Click Save.
8. Open Broker Manager for the selected event broker service to complete the LDAP configuration. See Using PubSub+ Broker Manager for instructions to access it.

Configuring LDAP for Management Access

PubSub+ Cloud administrators can configure LDAP for management access so that other users can be authenticated and authorized to log in to an event broker service using their LDAP credentials.

In the example below, we will configure the LDAP for management access using the Cloud Console. To use the REST API to configure LDAP for management access, see Managing Authentication with the PubSub+ Cloud REST API.

To configure LDAP for management access, perform the following steps:

1. Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your authentication scheme. For more information, see Logging In to the PubSub+ Cloud Console.
2. Select Cluster Manager.
3. Select an event broker service. If the event broker service is not listed, make sure you have the right environment selected. For more information, see Selecting and Changing Environments.
4. On the Service Details page, click the Manage tab and select Advanced Options.
   
5. Navigate to the LDAP for Management Access section. If you haven't previously configured LDAP for management access, it will be disabled.
   
6. Click Configure Settings to create an LDAP profile.
7. In the dialog that appears, enter the appropriate details for the following settings:

   Configuration	Description
   Admin Distinguished Name	LDAP distinguished name for the event broker to use to authenticate itself to the LDAP server.
   Admin Distinguished Name Password	Password to use with the admin distinguished name to bind to the LDAP server.
   Start TLS	A plaintext LDAP connection established over the default port 389, which is upgraded to a secure connection.
   Base Distinguished Name	The LDAP distinguished name of the node of the directory tree to start searches from.
   Dereferencing Behaviour	Dereferencing behavior of directory searches. always—always dereference aliases (default) never—never dereference aliases search—only dereference aliases when searching base—only dereference aliases when locating the base node
   Filter	Sets the templated filter to use to locate individual users in the directory service. By default, the filter field is filled in with client username. 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, the username is substituted into the variable $CLIENT_USERNAME in the filter string
   Scope	The scope of directory searches. subtree—search the entire subtree directory (default) base—search only the base node one-level—search only one level deep
   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.
   Timeout (Seconds)	The amount of time (in seconds) to wait before retrying an authentication or authorization request to an LDAP server.
   Group Membership Secondary Search Enabled	Retrieves an attribute from the user records, and then performs a secondary LDAP search using that attribute’s value to retrieve the group list.

8. Click Save.
9. Expand the Configure LDAP Management Access section to view the configuration options.
10. Enter the LDAP Group Membership Attribute Name value to check for groups. This is the name of the attribute that is used to look for matching groups.
    
11. To provide global-read (Messaging Viewer) and/or vpn-read-write (Messaging Editor) access to one or more groups, perform the following steps:
    1. Under VPN Read-Write Groups or Global Read-Only Groups section, click Add new group.
    2. In the field that appears, add the group information.
    3. Click the Add button.
12. Select the Enable LDAP for Management Access checkbox.
    
13. Click Save. Users can now log in to the event broker service using their LDAP credentials.

Configuring Client Certificate Authentication

You can enable client certificate authentication (or mutual TLS) on an event broker service. Before clients can authenticate with an event broker service using certificates, you must also upload the necessary certificate authority (CA) certificates to the event broker service. For more information about uploading certificates, see Managing Domain and Client Certificate Authorities.

To configure client certificate authentication, perform the following steps:

1. Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your authentication scheme. For more information, see Logging In to the PubSub+ Cloud Console.
2. Select Cluster Manager .
3. Select an event broker service. If the event broker service is not listed, make sure you have the right environment selected. For more information, see Selecting and Changing Environments.
4. On the Service Details page, click the Manage tab.
5. Click the Authentication tile.
   
6. Click the Client Certificate Authentication toggle to turn on certificate-based authentication.
7. Click the Validate Certificate Dates toggle to require event broker services to check the expiry dates of certificates.
   .
8. Click Save.

Client applications can now authenticate with your event broker service using a valid client certificate. For a tutorial, see Configuring an Event Broker Service to use Client Certificate Authentication.

Controlling When an Event Broker Service Requests a Certificate

When you configure an event broker service to use client certificate authentication, you can configure when it requests the client certificate during the TLS handshake process to secure the communication session. You can also choose settings based on the protocol (REST, MQTT, or web transport) that clients use to connect to the event broker service. For example, you could configure the event broker service to never request a certificate for client applications connecting using web transport, but always request a certificate for clients connecting using MQTT.

Perform the following steps in PubSub+ Broker Manager to configure when an event broker service requests a certificate from the client application.

1. In PubSub+ Broker Manager, select Message VPN  on the navigation bar.
2. Select the Services tab. To control when the event broker service requests a client certificate, set the Authentication Request Client Cert option (for Web Transport or MQTT) and Producer Authentication Request Client Cert (for REST):

• Always—Always ask for a client certificate.
• Never—Never ask for a client certificate.
• When Enabled in Message VPN—Ask for a client-certificate only when client certificate authentication is enabled for clients authenticating to the event broker service. This is the default setting for event broker services.

When the event broker service has client authentication enabled, it will request client certificates from applications during the TLS handshake. Client applications with certificates will connect normally. However, browser-based clients expecting to use basic authentication (username and password) may experience connectivity issues due to some browsers prompting for a client certificate even though it is not required. If you experience this problem you can set the Authentication Request Client Cert to Never or When Enabled in Message VPN to resolve the issue.

Configuring OAuth Provider Authentication

You can configure an event broker service to use an OAuth identity provider to authenticate client applications. This enables clients to connect and authenticate applications and IoT devices with OAuth's advanced security features.

For more information, see Configuring an Event Broker Service to Use OAuth Identity Provider Authorization.

Configuring User Access to Event Broker Services with Role-Based Access Control

You can configure user access to event broker services on a per-service basis using role-based access control (RBAC). RBAC is implemented using the Mission Control User role. The Mission Control User role provides limited access to event broker services. The access can be increased by assigning addtional roles to the Mission Control User.

For more information, see Configuring User Access to Event Broker Services.

Configuring OAuth Profiles on Event Broker Services for Direct User and Machine Authentication

You can configure OAuth profiles directly on event broker services. This allows you to authenticate users and machines connecting directly to your event broker services by mapping custom roles in your OAuth provider account to PubSub+ Cloud roles.

For more information, see Configuring OAuth Profiles for Management Access to Event Broker Services.