Configuring Management OAuth Profiles for Event Broker Service Authentication

You can enable Single Sign-On (SSO) for individual event broker services using the SEMP Proxy v2 REST APIs. These APIs enable you to provide direct access to your event broker services using OAuth profiles on the event broker service. The OAuth profiles authenticate users and machines connecting to them based on mapping custom roles in your OAuth provider account to PubSub+ Cloud roles. Users and machines connecting to the event broker service are given access based on the permissions granted by that the role.

To configure OAuth profiles for your event broker services, see the following:

Considerations for Configuring OAuth Profiles for Authentication
Configuring Your OAuth Provider
Configuring Multiple OAuth Profiles for Role-Based Authentication for an Event Broker Service
Configuring Machine-to-Machine OAuth Profile-Based Authentication

Considerations for Configuring OAuth Profiles for Authentication

Here are some considerations for configuring OAuth profiles for authenticating connections with your event broker services.

Configuration of OAuth profiles for role authenticating connections with individual event broker services is only possible using the SEMP Proxy v2 REST APIs.
You can create a maximum of three OAuth profiles per event broker service for role-based authentication.
You must configure your OAuth provider correctly. See Configuring Your OAuth Provider.
The event broker service does not natively support multiple OAuth profiles using the same IdP.
You require an API token generated from the Cloud Console by an account with the Administrator or Mission Control Manager roles. The API token must have the following permissions:
- Get My Services with Management Credentials
- Create Services
For more information see Creating an API Token.

Configuring Your OAuth Provider

The ability to use OAuth profiles for authenticating connections with your event broker service is dependent upon OAuth and OpenID Connect authorization and authentication. Numerous identity providers (IdP) provide these tools, and using Single Sign-On (SSO) authentication for event broker service log in requires you to configure your OAuth identity provider (IdP) correctly. The configuration process has similar requirements for all IdPs. There are two configuration processes: one for user and another for machine-to-machine based authentication. We outline these configuration processes below. For specific configurations requirements, see your IdP’s documentation.

User-based role authentication

For role-based authentication for users, the general IdP configuration process includes:

configuring a custom action
adding a login flow
adding roles and users, including verifying user email addresses, and assigning users to the created roles
creating an OAuth application
configuring the URLs

When configured correctly, the OAuth IdP provides an OpenID Configuration URL, which is required by to set up role-based authentication using the REST APIs in these procedures.

Machine to Machine setup

For SSO authentication for machines, the general IdP configuration process includes:

Setting up an API, including providing it with the Hostname URL (located under DMR Cluster in the Detailed Service Information) and assigning permissions to it.
Creating a machine-to-machine OAuth application and assigning an API and credential permissions to it.

For more information about configuring your OAuth IdP correctly, see your OAuth provider documentation .

Configuring Multiple OAuth Profiles for Role-Based Authentication for an Event Broker Service

You can configure event broker services so that users and machines connecting directly to them authenticate with OAuth. You do this by creating OAuth profiles on your event broker service. An OAuth profile contains all the information the event broker service requires to communicate with your identity provider (IdP). It also contains the mapping of roles to the existing roles in PubSub+ Cloud. After creating an OAuth profile, you can add roles to it. Roles define a group of users and the access they have to the event broker service. This allows you to provide direct access to event broker service while restricting permissions to roles assigned through your OAuth configuration.

In the procedures below, we create a profile with two roles: an editor and a viewer. These are mapped to existing Cluster Manager roles, providing the editor with permissions that allow them to do a wide array of tasks with an event broker service through the Cloud Console. The viewer role is limited, with only the ability to log in and view the event broker service.

Before configuring your event broker services OAuth profiles for authenticating user log in, ensure you have configured your OAuth identity provider correctly. To configure your event broker service services to OAuth profiles for authenticating user log in, follow these steps:

Creating a Connection to Your Identity Provider
Securing Redirects From Your Identity Provider
Mapping the OAuth Profiles for Authentication

Creating a Connection to Your Identity Provider

Determine the unique identifier for the event broker service you want to enable role-based authentication using one of the following methods:
- In Cluster Manager, select the event broker service and get its unique identifier from the last segment in the URL. For example, 9c5vurtex4b is the identifier from https://console.solace.cloud/services/9c5vurtex4b.
- Use the Get list of services REST endpoint to find the unique identifier (id) of the event broker service.
For example, on the Get list of services page, paste your API token into the Bearer field and then click Try It!. To find your event broker service named My-Primary-Service, you can find that string in the name object and its corresponding id object is the unique identifier for the service, which is 9wbofn0wvwb as shown:
Use the Create a resource object for an event broker service using a SEMP POST API to create an OAuth profile on the event broker service.

Specify the Path Params fields as follows:

serviceId—The unique identifier of the event broker service that you acquired in Step 1.
resourcePath—The resource path where you want to create the resource object, in this case oauthProfiles.

In the Body Params field, enter the following JSON object which contains the necessary details to create the profile and connect it to your IdP. See Create an OAuth Profile object in the SEMP reference documentation for a list of all possible parameters for the JSON body.

{
  "accessLevelGroupsClaimName": "{CUSTOM_CLAIM}",
  "clientId": "${CLIENT_ID}",
  "clientRedirectUri": "",
  "clientRequiredType": "JWT",
  "clientScope": "openid email",
  "clientSecret": "${CLIENT_SECRET}",
  "clientValidateTypeEnabled": false,
  "defaultGlobalAccessLevel": "none",
  "defaultMsgVpnAccessLevel": "none",
  "displayName": "",
  "enabled": true,
  "endpointAuthorization": "",
  "endpointDiscovery": "${ENDPOINT_DISCOVERY}",
  "endpointDiscoveryRefreshInterval": 86400,
  "endpointIntrospection": "",
  "endpointIntrospectionTimeout": 1,
  "endpointJwks": "",
  "endpointJwksRefreshInterval": 86400,
  "endpointToken": "",
  "endpointTokenTimeout": 1,
  "endpointUserinfo": "",
  "endpointUserinfoTimeout": 1,
  "interactiveEnabled": true,
  "interactivePromptForExpiredSession": "",
  "interactivePromptForNewSession": "select_account",
  "issuer": "",
  "oauthProfileName": "${PROFILE_NAME}",
  "oauthRole": "client",
  "resourceServerParseAccessTokenEnabled": true,
  "resourceServerRequiredAudience": "",
  "resourceServerRequiredIssuer": "",
  "resourceServerRequiredScope": "",
  "resourceServerRequiredType": "at+jwt",
  "resourceServerValidateAudienceEnabled": true,
  "resourceServerValidateIssuerEnabled": true,
  "resourceServerValidateScopeEnabled": true,
  "resourceServerValidateTypeEnabled": true,
  "sempEnabled": false,
  "usernameClaimName": "sub"
}

Where:

{CUSTOM_CLAIM}— The URL for the OAuth custom claim configured in your IdP. To get your custom claim, see your IdP's documentation
{CLIENT_ID}— The Client ID for your IdP. To get your Client ID, see your IdP's documentation.
{CLIENT_SECRET}—The Client Secret for your IdP. To get your Client Secret, see your IdP's documentation.
{ENDPOINT_DISCOVERY}—The OpenID Configuration provided by your IdP.
{PROFILE_NAME}—The name of the role you created in your IdP.

If the PUT call completes successfully, a 200 code is returned.

You can test the successful creation of the profile by using the Get a specific resource object for an event broker service by the object path using a SEMP GET API REST endpoint, where:

serviceId—The unique identifier of the event broker service that you acquired in Step 1.
resourcePath—The resource path where you want to create the resource object, in this case oauthProfiles.

The GET returns a list of roles if your PUT call successfully completed.

Securing Redirects From Your Identity Provider

After creating a connection to your Identity Provider (IdP), it is important for security purposes to specify which hostnames can make token requests to the OAuth server. To specify the allowed hostnames, use the Create a resource object for an event broker service using a SEMP POST API to create an Allowed Value object on the event broker service that contains the hostname information.

Specify the Path Params fields as follows:

serviceId—The unique identifier of the event broker service that you acquired in Step 1.
resourcePath—The resource path where you want to create the resource object, in this case oauthProfiles/<profile-name>/clientAllowedHosts.

Provide the following JSON objects into the Body Params field:

{
    "allowedHost": "${VMR_HOST}",
    "oauthProfileName": "${PROFILE_NAME}"
}

Where:

{VMR_HOST}—The hostname for the event broker service. You can determine the hostname URL under DMR Cluster in the Detailed Service Information page for the event broker service or by a using the Get a specific event broker service by identifier API and selecting serviceConnectionEndpoints in the Query Params field and looking for the hostNames value in the response body.
{PROFILE_NAME}—The name of the profile you created in your Identity Provider (IdP).

If the PUT call completes successfully, a 200 code is returned.

Mapping the OAuth Profiles for Authentication

After securing redirects you can create roles for the OAuth profile on your event broker service that map to your IdP roles. You can create up to three OAuth profiles per event broker service, and assign roles to the profiles as needed. In this case, we are creating two roles in the OAuth profile we created: an editor and a viewer that we can map through the IdP to Cluster Manager roles in PubSub+ Cloud. This mapping provides us with the ability to dictate the functions a user can perform on particular event broker services based on the role they authenticate with when accessing that service. For example, users logging in with the editor role have the ability to view the event broker service, edit its properties, and delete it. Meanwhile, users logging in with the viewer role are restricted to only viewing event broker service information.

To create the two roles, see:

Creating the Editor Profile
Creating the Viewer Profile

Creating the Editor Profile

To create the editor profile use the Replace a resource object on an event broker service using a SEMP POST API to create resource object on the broker containing the information about the editor role.

Specify the Path Params fields as follows:

serviceId—The unique identifier of the event broker service where you want to create the roles. You can determine the unique identifier for an event broker service using the Cloud Console or by using a GET call. See Get a list of event broker services.
resourcePath—the resource path where you want to define the resource object. In this example, oauthProfiles/editor.

Enter the following JSON object into the Body Params field:

{
  "description": "SolaceAdmin Group",
  "globalAccessLevel": "read-only",
  "groupName": "${ACCESS_LEVEL_EDITOR_GROUP_NAME}",
  "msgVpnAccessLevel": "read-write",
  "oauthProfileName": "${PROFILE_NAME}"
}

Where:

{ACCESS_LEVEL_EDITOR_GROUP_NAME}—The claim value that is mapped to the editor level access for the group.
{PROFILE_NAME}—The name of the profile you created in your IdP.

If the PUT call completes successfully, a 200 code is returned.

Creating the Viewer Profile

To create the viewer profile use the Replace a resource object on an event broker service using a SEMP POST API to create resource object on the broker containing the information about the viewer role.

Specify the Path Params fields as follows:

serviceId—The unique identifier of the event broker service where you want to create the roles. You can determine the unique identifier for an event broker service using the Cloud Console or by using a GET call. See Get a list of event broker services.
resourcePath—the resource path where you want to define the resource object. In this example, oauthProfiles/viewer.

Enter the following JSON object into the Body Params field:

{
  "description": "SolaceAdmin Group",
  "globalAccessLevel": "read-only",
  "groupName": "${ACCESS_LEVEL_READER_GROUP_NAME}",
  "msgVpnAccessLevel": "read-only",
  "oauthProfileName": "${PROFILE_NAME}"
}

Where:

{ACCESS_LEVEL_READER_GROUP_NAME}—The claim value that is mapped to the viewer level access for the group.
{PROFILE_NAME}—The name of the profile you created in your IdP.

If the PUT call completes successfully, a 200 code is returned.

When configured, users will be presented with a log in screen that includes the ability to log in with a username and password, or to log in with using a OAuth based profile, as shown in the following image (Login with ClientOauthProfile in the example below). Clicking a profile takes the user to an OAuth provider log in. After you have configured role-based authentication and tested it, you can disable the various types of basic authentication, forcing users to authenticate with a role when connecting to Broker Manager, or the event broker service. See Disabling Basic Authentication for Event Broker Service Management. If you no longer require a role you have created, you can delete it. See Deleting an OAuth Profile on an Event Broker Service.

Configuring Machine-to-Machine OAuth Profile-Based Authentication

You can configure Single Sign-On (SSO) for machine-to-machine authentication by configuring OAuth profiles on for your event broker services. This causes machines connecting to the event broker service to have permissions based on PubSub+ Cloud roles mapped in your OAuth provider account. This allows you to configure different levels of access for machines on a per event broker service basis. Configuring OAuth profiles on the event broker service is required when you want to enable machine-to-machine authentication.

Before configuring your event broker services to use SSO for machine-to-machine authentication, ensure you have configured your OAuth identity provider correctly. Ensure you have an API token with appropriate permissions as outlined in Considerations for Configuring OAuth Profiles for Authentication.

To configure your event broker service services to use role-based authentication for user log in, follow these steps:

Setup the OAuth profile by using the Create a resource object on an event broker service using a SEMP POST API to create an OAuth profile on the event broker service.

Specify the Path Params fields as follows:

serviceId—The unique identifier of the event broker service where you want to create the roles. You can determine the unique identifier for an event broker service using the Cloud Console or by using a GET call. See Get a list of event broker services.
resourcePath—the resource path where you want to define the resource object. For example, oauthProfiles/machineRole.

Enter the following JSON object into the Body Params field:

{
  "accessLevelGroupsClaimName": "groups",
  "clientId": "",
  "clientRedirectUri": "",
  "clientRequiredType": "JWT",
  "clientScope": "SolaceEditor",
  "clientSecret": "",
  "clientValidateTypeEnabled": false,
  "defaultGlobalAccessLevel": "none",
  "defaultMsgVpnAccessLevel": "read-write",
  "displayName": "",
  "enabled": true,
  "endpointAuthorization": "",
  "endpointDiscovery": "${ENDPOINT_DISCOVERY}",
  "endpointDiscoveryRefreshInterval"   : 86400,
  "endpointIntrospection": "",
  "endpointIntrospectionTimeout": 1,
  "endpointJwks": "",
  "endpointJwksRefreshInterval": 86400,
  "endpointToken": "",
  "endpointTokenTimeout": 1,
  "endpointUserinfo": "",
  "endpointUserinfoTimeout": 1,
  "interactiveEnabled": false,
  "interactivePromptForExpiredSession": "",
  "interactivePromptForNewSession": "select_account",
  "issuer": "",
  "oauthProfileName": "${PROFILE_NAME}",
  "oauthRole": "resource-server",
  "resourceServerParseAccessTokenEnabled": true,
  "resourceServerRequiredAudience": "${AUDIENCE}",
  "resourceServerRequiredIssuer": "",
  "resourceServerRequiredScope": "SolaceAdmin",
  "resourceServerRequiredType": "JWT",
  "resourceServerValidateAudienceEnabled": true,
  "resourceServerValidateIssuerEnabled": true,
  "resourceServerValidateScopeEnabled": true,
  "resourceServerValidateTypeEnabled": true,
  "sempEnabled": true,
  "usernameClaimName": "sub"
}

Where:

{ENDPOINT_DISCOVERY}—The claim value that is mapped to the editor level access for the group.
{PROFILE_NAME}—The name of the profile you created in your IdP.
{AUDIENCE}—The name of the profile you created in your IdP.

A successful PUT returns a code of 200.

You can test the successful creation of the profile by using the Get a specific resource object for an event broker service by the object path using a SEMP GET API REST endpoint. Specify the following parameters. Specify the Path Params fields as follows:

serviceId—The unique identifier of the event broker service that you acquired in Step 1.
resourcePath—The resource path where you want to create the resource object, in this case oauthProfiles.

The GET returns a list of roles if your PUT created them successfully.

You can test the connection by getting a token from your IdP and adding it to the authentication header. See your see your OAuth provider documentation for information on how to get a token.

If you're having trouble connecting, check that your introspection endpoint is returning token information. For more information, see Token Introspection Endpoint in the OAuth documentation.
(Optional) After the configuration is successful, you can disable basic authentication for the event broker service.
When you no longer need the machine-to-machine based role, you can delete it. See Deleting an OAuth Profile on an Event Broker Service.

Disabling Basic Authentication for Event Broker Service Management

With OAuth profiles configured for your event broker service you can increase the security of your event broker services by disabling the basic types of authentication. Disabling the basic types of authentication include disabling:

pre-authenticated log in when accessing the event broker service manager quick settings or Broker Manager. See Disabling Basic Authentication for Event Broker Service Management.
basic user authentication for logging into event broker services, requiring SSO to be used when logging into an event broker service. See Disable Basic User Access Using the REST API.

Disabling Pre-Authentication Using the Cloud Console

You can disable pre-authentication on the event broker service. You should be aware that this is an organization wide change. When disabled, users must authenticate themselves with launching Broker Manager from the Cloud Console. They can authenticate using the OAuth profiles configured on the event broker service. For more information, see Pre-Authentication for Broker Manager

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 into the PubSub+ Cloud Console.
Click User & Account, select Account Details, and then click the Account Settings.
In the Security Settings section click the PubSub+ Pre Authentication slider to disable pre-authentication.

Disable Basic User Access Using the REST API

Disabling basic authentication without enabling OAuth profiles will disable all access to the event broker service.

You can disable basic user authentication for event broker services. When you do this, users or machines connecting to the event broker service must authenticate with Single Sign-On using OAuth profiles you configured on the event broker service. If you disable basic authentication, you should also consider disabling pre-authentication.

This procedure requires the unique identifier for the event broker service and the same API token you used in Configuring Management OAuth Profiles for Event Broker Service Authentication.

To disable basic authentication use the Enable or disable basic authentication for users logging onto an event broker service API to delete the OAuth profile from the event broker service.

Specify the Path Params fields as follows:

serviceId—The unique identifier of the event broker service where you want to create the roles. You can determine the unique identifier for an event broker service using the Cloud Console or by using a GET call. See Get a list of event broker services.
enabled—Select the value to indicate wether basic OAuth authentication should be enabled or disabled, either:
- true—Basic authentication is enabled
- false—Basic authentication is enabled

Deleting an OAuth Profile on an Event Broker Service

If you no longer need an OAuth Profile you have created on an event broker service, you can delete it.

To delete a machine-to-machine based OAuth profile use the Delete a resource object on an event broker service by object path using a SEMP DELETE API to delete the OAuth profile from the event broker service.

Specify the Path Params fields as follows:

serviceId—The unique identifier of the event broker service where you want to create the roles. You can determine the unique identifier for an event broker service using the Cloud Console or by using a GET call. See Get a list of event broker services.
resourcePath—the resource path where you want to define the resource object. For example, oauthProfiles/machineRole.

Provide feedback