Managing Authentication with the PubSub+ Cloud REST API

With REST API and API token support for authentication, you can configure the authentication mechanism for event broker services.

This tutorial shows you how to:

Before you Begin

Before you can start this tutorial, you'll require the following:

  • An account in PubSub+ Event Broker: Cloud and an event broker service.
  • The service ID of the event broker service. The {serviceId} is the last value of the specified service's URL. For example, in this URL https://console.solace.cloud/services/d4g5cxzcrhk, the service ID is d4g5cxzcrhk. The service identifier is required for many of the REST API calls.
  • Your account must be assigned the Administrator or Cluster Manager Editor role.
  • An API token with the following permissions:
    • From Mission Control:
      • Get My Services with Management Credentials
    • From Organization Services:
      • Get Services with Management Credentials
      • Enable/Disable LDAP Management Access to the Broker
      • Enable / Disable Basic and Certificate Authentication

    To learn how to create an API token, see Creating an API Token.

  • A REST client of your choice. Postman is a good choice if you want a visual REST API development tool. At this time, there is no Solace Blog available so if you use Postman, simply make each call by typing the REST API call after you've set up the environment in Postman to use your API token. For more information about setting up Postman, see Managing API Tokens.

    After you've set up the environment in Postman to use your API token, you can simply make each call by specifying the REST API. To check that API token is set up correctly to use Bearer authorization in Postman, select the Headers tab to validate that it is using Bearer Authorization and set it to use the apiToken environment variable that you had set up earlier. For example, you can see that Authorization is set up to use Bearer and the apiToken in the following illustration:

Configuring Client Certificate Authentication For Event Broker Services

You can enable client certificate authentication or mutual TLS (mTLS) on event broker services using the REST API. Before you enable client certificate authentication, you must add certificates to the event broker service.  For more information, see Managing Certificate Authorities with the PubSub+ Cloud REST API.

The minimum permission required in the API Token to use the REST API call is Enable / Disable Basic and Certificate Authentication.

To enable or disable client certificate authentication, you issue a POST call to https://api.solace.cloud/api/v0/services/{serviceId}/requests/updateAuthenticationRequests.

A successful request returns 202 (Accepted); otherwise the following error codes are returned:

  • 5000 — with a support code of 102 if the updateAuthenticationRequest was passed an invalid format or missing a parameter in the body of the POST request. The request must include all parameters specified in the payload above.
  • 5000 — with a support code of 106 if the update authentication permission (Enable / Disable Basic and Certificate Authentication) is not in the API token that was used.

The POST call requires the following parameters in the body:

  • authenticationBasicEnabled — A boolean value to enable (true) or disable (false) basic authentication for the client applications.

    Do not disable (set to false), otherwise your event broker service is accessible by everyone.

  • authenticationClientCertEnabled — A boolean value to enable (true) or disable (false) Client Certificate Authentication for client applications.

  • authenticationClientCertValidateDateEnabled — A boolean value to enable (true) or disable (false) the requirement to validate the certificate date.

  • authenticationOauthEnabled — A boolean value to enable (true) or disable (false) OAuth authentication for client applications. This will enable clients to connect and authenticate applications and IoT devices with OAuth's advanced security features.

The serviceId is the unique identifier for the service, which you can determine using a call such as Getting the Connection Details for the Event Broker Service Using the REST API

For example, if the identifier for the service identifier of v0q6d1xqg7g, a POST call to https://api.solace.cloud/api/v0/services/v0q6d1xqg7g/requests/updateAuthenticationRequests with the payload looks like this:

{
  "authenticationBasicEnabled": "true",
  "authenticationClientCertEnabled": "true",
  "authenticationClientCertValidateDateEnabled": "false",
  "authenticationOauthEnabled" "false"
}

Upon success, a response is returned:

{
  "data": {
    "id": "0b4tesmsn2b",
    "creationTimestamp": 1631111411837,
    "authenticationBasicEnabled": "true",
    "authenticationClientCertEnabled": "true",
    "authenticationClientCertValidateDateEnabled": "false",
    "authenticationOauthEnabled": "false",
    "type": "updateAuthenticationRequest"
  }
}

Since this operation is asynchronous, you must issue a GET call to https://api.solace.cloud/api/v0/services/{serviceId}/requests/{requestId} to check the progress of the operation, where serviceId is the identifier for the event broker service and requestId is the value from id parameter that was returned in the response from the POST call. Continuing from the previous example, if you issue the GET call to https://api.solace.cloud/api/v0/services/v0q6d1xqg7g/requests/0b4tesmsn2b, you can see the status is completed in the adminProgress progress in the response as follows:

{
  "data": {
    "id": "0b4tesmsn2b",
    "creationTimestamp": 1631111411837,
    "adminProgress": "completed",
    "authenticationBasicEnabled": "true",
    "authenticationClientCertEnabled": "true",
    "authenticationClientCertValidateDateEnabled": "false",
    "authenticationOauthEnabled": "false",
    "type": "updateAuthenticationRequest"
  },
  "meta": {
    "currentTime": 1631111490000
  }
}

Creating an LDAP Profile

For LDAP authentication of users and/or LDAP authorization of clients, LDAP profiles must be configured on the event broker service and be enabled. You can create the following LDAP profiles:

To create an LDAP profile for an existing service, send a POST request to https://api.solace.cloud/api/v0/services/{id}/requests/ldapAuthenticationProfileRequests. A successful response returns 202 (Accepted). The {id} is the last value in the specified service's URL. For example, in this URL, https://console.solace.cloud//services/d4g5cxzcrhk, the service ID is d4g5cxzcrhk.

The following example payload will create an LDAP management profile. For detailed information on the attributes and parameters, refer to Configuring an LDAP Profile for Basic Authentication.

{
  "operation":"create",
  "ldapAuthenticationProfile":
    {
      "profileName": "management",
      "enabled":false,
      "adminDn":"solly@example.com",
      "adminPassword":"somesuperotter",
      "allowUnauthenticatedAuthentication":false,
      "startTls":true,
      "ldapServerOne":"ldap:myldapserver:1234",
      "ldapServerTwo":null,
      "ldapServerThree":null,
      "searchBaseDn":"apple23",
      "searchDeref":"SEARCH",
      "searchFilter":"(cn=$CLIENT_USERNAME)23",
      "searchScope":"BASE",
      "searchFollowContinuationReferences":true,
      "searchTimeout":3,
      "groupMembershipSecondarySearchEnabled":false,
      "groupMembershipSecondarySearchBaseDn":"",
      "groupMembershipSecondarySearchFilterAttributeFromPrimarySearch":"",
      "groupMembershipSecondarySearchDeref":"ALWAYS",
      "groupMembershipSecondarySearchFilter":"",      
      "groupMembershipSecondarySearchScope":"SUBTREE",
      "groupMembershipSecondarySearchFollowContinuationReferences":false,
      "groupMembershipSecondarySearchTimeout":2
    }
}

Here is an example of a successful 202 response:

{
  "data" : {
    "id" : "zl8oa476l",
    "creationTimestamp" : 0,
    "operation" : "update",
    "type" : "ldapAuthenticationProfileRequest"
  }
}

To verify that the LDAP profile was successfully created, send a GET request to https://api.solace.cloud/api/v0/services/{id}/requests/ldapAuthenticationProfileRequests/<ldap-profile-name>. A successful response returns 200 (OK).

The following is an example response for an LDAP management profile that was successfully created.

{
  "data" : {
    "id" : "management",
    "profileName" : "management",
    "enabled" : true,
    "allowUnauthenticatedAuthentication" : false,
    "startTls" : true,
    "adminDn" : "solly@example.com",
    "adminPassword" : "somesuperotter",
    "groupMembershipSecondarySearchEnabled" : false,
    "groupMembershipSecondarySearchBaseDn" : "",
    "groupMembershipSecondarySearchDeref" : "ALWAYS",
    "groupMembershipSecondarySearchFilter" : "",
    "groupMembershipSecondarySearchFilterAttributeFromPrimarySearch" : "",
    "groupMembershipSecondarySearchFollowContinuationReferences" : false,
    "groupMembershipSecondarySearchScope" : "SUBTREE",
    "groupMembershipSecondarySearchFollowContinuationShutdown" : false,
    "groupMembershipSecondarySearchTimeout" : 2,
    "ldapServerOne" : "ldap://macafee.ca:1234",
    "ldapServerTwo" : null,
    "ldapServerThree" : null,
    "searchBaseDn" : "apple23",
    "searchDeref" : "SEARCH",
    "searchFilter" : "(cn=$CLIENT_USERNAME)23",
    "searchFollowContinuationReferences" : true,
    "searchScope" : "BASE",
    "searchTimeout" : 3,
    "type" : "ldapAuthenticationProfile"
  }
}

To configure LDAP management access through the PubSub+ Cloud console, refer to Configuring an LDAP Profile for Basic Authentication.

Configuring LDAP for Management Access

Before you begin this tutorial, make sure you've created an LDAP Management Profile.

To set LDAP for management access, you must configure the following:

  • configure an LDAP management profile.
  • set the LDAP attribute to check for groups. A group attribute name is retrieved from the LDAP server as part of the LDAP search to authenticate users. The groupAttributeName indicates that a user belongs to a particular group that exists on the LDAP server.
  • provide global-read and/or vpn-read-write access to one or more groups. A user may belong to one or more LDAP groups, and each group's access level may differ. You can provide readOnlyGroupNames and/or readWriteGroupNames to member groups.

To configure LDAP for Management Access through the PubSub+ Cloud console, refer to Configuring Authentication to Event Broker Services.

Enable LDAP for Management Access

To enable the LDAP for Management Access for an existing service, send a POST request to https://api.solace.cloud/api/v0/services/{serviceId}/requests/ldapManagementAccessRequest. A successful response returns 202 ACCEPTED.

The following example payload will enable the LDAP management access, where we set the groupAttributeName and the readOnlyGroupNames and readWriteGroupNames access for specific groups.

{
   "operation":"create",
   "managementProfileName":"<created-management-profile-name>",
   "groupAttributeName":"<group-membership-attribute-name>",
   "readOnlyGroupNames":["<group-name-1>","<group-name-2>"],
   "readWriteGroupNames":["<group-name-1>", "<group-name-3>"]
}

Here is an example of a successful 202 Accepted response:

{
   "data": {
      "id": "<serviceRequestId>",
      "creationTimestamp": 0,
      "managementProfileName": "<created-management-profile-name>",
      "operation": "create",
      "groupAttributeName": "<group-membership-attribute-name>",
      "readOnlyGroupNames": [
         "<group-name-1>",
         "<group-name-2>"
      ],
      "readWriteGroupNames": [
         "<group-name-1>",
        "<group-name-3>"
      ],
      "type": "ldapManagementRequest"
   }
}

Update/Disable LDAP for Management Access

To update the LDAP for Management Access for an existing service, send a POST request to https://api.solace.cloud/api/v0/services/{serviceId}/requests/ldapManagementAccessRequest. A successful response returns 202 ACCEPTED.

The following example payload will update the LDAP management access, where we set "operation: update" and enableManagementProfileAuthentication: true. Setting enableManagementProfileAuthentication: false will disable the LDAP for Management Access.

{
    "operation":"update",
    "managementProfileName":"<created-management-profile-name<",
    "groupAttributeName":"<group-membership-attribute-name<",
    "readOnlyGroupNames":["<group-name-1<","<group-name-2<","<group-name-4<"],
    "readWriteGroupNames":[],
    "enableManagementProfileAuthentication": true
}

Here is an example of a successful 202 Accepted response:

{
   "data": {
      "id": "<serviceRequestId>",
      "creationTimestamp": 0,
      "managementProfileName": "<created-management-profile-name>",
      "operation": "create",
      "groupAttributeName": "<group-membership-attribute-name>",
      "readOnlyGroupNames": [
         "<group-name-1>",
         "<group-name-2>",
         "<group-name-4>"
      ],
        "readWriteGroupNames": [],
        "enableManagementProfileAuthentication": true,
        "type": "ldapManagementRequest"
    }
}

Remove LDAP for Management Access

To remove the LDAP for Management Access for an existing service, send a POST request to https://api.solace.cloud/api/v0/services/{serviceId}/requests/ldapManagementAccessRequest. A successful response returns 202 ACCEPTED.

The following example payload will remove the LDAP management access, where we set "operation: delete" and enableManagementProfileAuthentication: false.

{
    "operation":"delete",
    "managementProfileName":"<created-management-profile-name<",
    "groupAttributeName":"<group-membership-attribute-name<",
    "readOnlyGroupNames":["<group-name-1<","<group-name-2<","<group-name-4<"],
    "readWriteGroupNames":[],
    "enableManagementProfileAuthentication": false
}

Here is an example of a successful 202 response:

{
    "data": {
      "id": "<serviceRequestId>",
      "creationTimestamp": 0,
      "managementProfileName": "<created-management-profile-name>",
      "operation": "create",
      "groupAttributeName": "<group-membership-attribute-name>",
      "readOnlyGroupNames": [
         "<group-name-1>",
         "<group-name-2>",
         "<group-name-4>"
      ],
        "readWriteGroupNames": [],
        "enableManagementProfileAuthentication": false,
        "type": "ldapManagementRequest"
    }
}

Get LDAP for Management Access Information

To retrieve the information for LDAP for Management Access, send a GET request to https://api.solace.cloud/api/v0/services/{service-id}/ldapManagementAccess. A successful response returns 200 OK. If the event broker service was deleted or disabled, the response will be 404 NOT FOUND.

The following is an example response for LDAP management access information that is enabled.

{
   "data": {
        "id": "{vmrId}/{vpn}/ldapManagement",
        "creationTimestamp": 0,
        "adminProgress": "completed",
        "managementProfileName": "<created-management-profile-name>",
        "operation": "create",
        "groupAttributeName": "<group-membership-attribute-name>",
        "readOnlyGroupNames": [
            "<group-name-1>",
            "<group-name-2>"
        ],
        "readWriteGroupNames": [
            "<group-name-1>",
            "<group-name-3>"
        ],
        "enableManagementProfileAuthentication": true,
        "type": "ldapManagementRequest"
    }
}

Check Status of LDAP for Management Access Service Request

To verify that the LDAP for Management Access was successfully enabled, updated, or deleted, send a GET request to https://api.solace.cloud/api/v0/services/{serviceId}/requests/{serviceRequestId}. A successful response returns 200 OK. If the event broker service was deleted or disabled, the response will be 404 NOT FOUND.

The following is an example response for LDAP management access that is enabled.

{
  "data": {
        "id": "<serviceRequestId>",
        "creationTimestamp": 0,
        "adminProgress": "completed",
        "managementProfileName": "<created-management-profile-name>",
        "operation": "create",
        "groupAttributeName": "<group-membership-attribute-name>",
        "readOnlyGroupNames": [
            "<group-name-1>",
            "<group-name-2>"
        ],
        "readWriteGroupNames": [
            "<group-name-1>",
            "<group-name-3>"
        ],
        "type": "ldapManagementRequest"
    },
    "meta": {
        "currentTime": 1622142431031
  }
}