Managing Single Sign-On for Event Broker Services with the PubSub+ Cloud REST API

With the PubSub+ Cloud REST API, you can enable single sign-on (SSO) in the PubSub+ Cloud Console using OpenID Connect (OIDC). You can enable Event Broker Service SSO for management access to one or more event broker services after you have enabled Console SSO.

This REST API allows you to configure only Event Broker Service SSO for an event broker service. You must use a separate REST API to configure client access to events and messages on the event broker service. For more information, see Managing Authentication with the PubSub+ Cloud REST API.

This tutorial shows you how to:

Disable or enable SSO for management access on event broker services. For more information, see Enabling or Disabling Event Broker Service SSO Using the REST API.
Retrieve the SSO configuration status for a specific event broker service. For more information, see Determining the SSO Status for an Event Broker Service Using the REST API.
Test SSO access on the event broker service using PubSub+ Broker Manager. For more information, see Testing SSO for an Event Broker Service.
Check the SSO status on the event broker service and take action as required. This is a recommended maintenance practice and ensures that your event broker services are updated with the most recent SSO configuration (such as claims that have been added or removed). For more information, see Keeping Event Broker Services Updated with Recent Account Changes Using the REST API.

Before You Begin

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

You must have an Enterprise Account for PubSub+ Cloud. Trial accounts do not support SSO configuration via Open ID Connect (OIDC).
The roles in your Enterprise Account must be mapped appropriately to the roles in your identity provider:
- the Administrator and Mission Control Manager roles give edit permissions to the Message VPN on the event broker service
- the Mission Control Viewer role gives read access to Message VPN on the event broker service
If you have multiple connection endpoints (or private and public endpoints) configured for the event broker service, the redirect URIs need to be configured on the identity provider (IdP).
SSO via OIDC must be enabled on the account.
Role management must be set up on the account.
Just-in-time provisioning must be configured on the account.
To make the REST API calls, you require an API token in the account with at least the following permissions:

View service OAuth configuration (service_oauth:read)—permits you get SSO configuration status of an event broker service.
Update service OAuth configuration (service_oauth:write)—permits you to set whether SSO configuration status is used on an event broker service.

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:

Adding the Event Broker Service URI to Your Identity Provider

The identity provider (IdP) you've chosen must know the redirect URIs of each event broker services.

You can retrieve the URI using one of the following methods:

Use the PubSub+ Cloud Console. For more information, see Retrieving the URI for an Event Broker Service.
Use the REST API. For more information, see Retrieving the URI for the Event Broker Service to Use as a Redirect URI.

Retrieving the URI for the Event Broker Service to Use as a Redirect URI

To retrieve the URI for a specific event broker service, you need to know the service identifier and perform a GET call to:

https://api.solace.cloud/api/v2/platform/serviceOidcConfigurations/<service_identifer>

From the response, you can use the value from uri as the redirect URI to add to your identity provider (IdP). If have configured multiple connection endpoints, the redirect URIs are returned as a comma-delimited list. You add the redirect URIs to your IdP as a comma-separate list if your IdP supports it, otherwise add each redirect URI separately.

The format of the URI is as follows:

https://<serviceredirectid>.messaging.solace.cloud/oauth/complete

where <serviceredirectid> represents the specific event broker service
where messaging.solace.cloud is the domain for the event broker service. This value may differ depending on your deployment or region of the PubSub+ Home Cloud you selected. It is recommended that you verify the values in the Broker URI field in the list of event broker services in Manage Brokers.

Enabling or Disabling Event Broker Service SSO Using the REST API

You can use the PubSub+ Cloud REST API to enable or disable single sign-on (SSO) for management access on an event broker service. When SSO is enabled, the most recent SSO configuration is used on the event broker service.

To use the REST API, you require the unique identifier (<service_identifer>) of the event broker service to perform these steps:

Before you follow these steps, you must have the API token configured in Postman. The examples all use Postman, but you can issue the requests using a means you choose, such as cURL.

In Postman, issue a PUT request to https://api.solace.cloud/api/v2/platform/serviceOidcConfigurations/<service_identifer>.
In the body of the request, use one of the following in as the body for the PUT request:
- To enable (or add) the SSO configuration on the event broker service, use the following in body:
```
{
   "configuredState" : "enabled"
}
```
- To disable (or remove) the SSO configuration for an event broker service, use the following in the body:
```
{
   "configuredState" : "disabled"
}
```

After you have enabled SSO on the event broker service, you can authenticate to the event broker service using your identity provider.

A 202 response is returned when the call completes successfully. To determine if SSO on the event broker service was enabled, you must retrieve the status. If it the SSO configuration failed, the reason is provided in the failureMessage. For more information about retrieving the SSO status for an event broker service, see Determining the SSO Status for an Event Broker Service Using the REST API.

The following error codes are returned if the REST API call failed:

403—The necessary permissions are not enabled on the API token.
400—The requirements to enable the SSO configuration on the event broker service are not met or the conditions to use Event Broker SSO are not met in the account. This may include one of the following reasons:
- SSO is not configured nor enabled
- Role-mapping has not been configured nor enabled
- Just-in-time user provisioning has not been enabled in the role mapping configuration
- The event broker service does not support SSO

Determining the SSO Status for an Event Broker Service Using the REST API

You can retrieve the SSO status of an event broker service. This check to determines if SSO is enabled or disabled on an individual event broker service, whether the SSO configuration is current, and the redirect URIs for the event broker service. To retrieve the SSO status, use a GET call to https://api.solace.cloud/api/v2/platform/serviceOidcConfigurations/<service_identifer>. You must know the service identifier for the service you want to query.

For example, a GET call to:
https://api.solace.cloud/api/v2/platform/serviceOidcConfigurations/548cdd2l3a4 gives the following response that indicates that SSO is enabled:

{
    "data": {
    "serviceId": "548cdd2l3a4",
    "name": "My-First-Service",
    "dataCenter": "US Central (Iowa)
    "configuredState": "enabled",
    "currentState": "enabled",
    "upToDate": "true"
    "uri: "https://548cdd2l3a4.messaging.solace.cloud/oauth/complete"
    }
}

serviceId

The unique identifier for the event broker service in PubSub+ Cloud.

name

The name of the event broker service.

dataCenter

The location where the event broker service resides. It usually corresponds to the region name that was selected when the event broker service was created.

configuredState

Whether the SSO configuration is enabled. This can have a value of enabled or disabled.

currentState

Actual state of the SSO configuration on the event broker service. This can have the values of:

disabled—No SSO configuration is available on the event broker service and SSO has been disabled. Event broker services that have this state support SSO.
enabled—The SSO configuration was successfully updated on the event broker service and SSO has been enabled. If the URI has been updated on your identity provider, you can use SSO credentials to access Broker Manager.
inProgress—An operation to enable, update, or remove the SSO configuration from the event broker service is in progress.
failed—Enabling, disabling, or updating the SSO configuration failed. You can try again or check the reason in failedMesssage.
unsupported—The event broker service doesn't support SSO. This can be because you using a legacy broker version. For information about upgrading your event broker service, see Upgrading Event Broker Services in PubSub+ Cloud.

upToDate

If the value is true, the event broker service has an updated SSO configuration consistent with the one configured on the Cloud Console. If the value is false, the event broker service has an outdated SSO configuration and must update it. To update the configuration, call the REST API to resend the SSO configuration to the event broker service. For more information, see Enabling or Disabling Event Broker Service SSO Using the REST API.

uri

The URI to add as a redirect in your identity provider (IdP). If have configured multiple connection endpoints, there may be multiple broker URIs to add to your identity provider (IdP). Multiple URIs are required when you have private and public endpoints.

failureMessage

The message from the latest attempt to modify the SSO configuration. This value is only returned in the response when the currentState is in the failed or unsuppported state.

Keeping Event Broker Services Updated with Recent Account Changes Using the REST API

If the Console SSO configuration in your account in PubSub+ Cloud changes, the resulting changes in the SSO configuration must be updated on each event broker service to synchronize the updates. For example, if you updated, deleted, or added any claims in the PubSub+ Cloud Console, you must update each event broker service with the updated SSO configuration.

To determine if an event broker service requires an update, you can issue a GET request to determine the status of the event broker service. In the response, if upToDate is false, then the event broker service must be updated with the SSO configuration.

For more information about the upToDate attribute, see Determining the SSO Status for an Event Broker Service Using the REST API.

To update the event broker service, send a PUT request with the configuredState set to enabled. This call causes the specified event broker service to be updated with the most recent SSO configuration. For more about using the PUT request, see Enabling or Disabling Event Broker Service SSO Using the REST API.

Provide feedback