Configuring OAuth Profiles for Management Access to Event Broker Services

You can configure management access to your event broker services using OAuth profiles. OAuth profiles allow users and machines (other computers and applications) to connect and authenticate using single sign-on (SSO) through an OAuth identity provider (IdP). An event broker service can have up to three OAuth profiles. Using OAuth profiles, you can map custom roles in your IdP to existing roles in PubSub+ Cloud. Users and machines connecting to your event broker services have permissions granted by the mapped roles.

Before configuring OAuth profiles using the SEMP Proxy v2 REST APIs you must:

If you want to configure management access to event broker services using the same SSO authentication as the Cloud Console, see Configuring Single Sign-On for Event Broker Services.

Depending on whether you are configuring access for individual users or machines (event broker service as resource server for other event broker services, computers, or applications) you must then:

Considerations for Configuring OAuth Profiles for Authentication

Here are some considerations when configuring OAuth profiles for your event broker services:

  • Configuring OAuth profiles on event broker services to enable sigle sign-on (SSO) through your identity provider (IdP) is only possible using the SEMP Proxy v2 REST APIs.

  • You can create a maximum of three OAuth profiles per event broker service.

  • You must configure your OAuth identity provider correctly. For more information, see Configuring Your OAuth Identity Provider.

  • Event broker services prior to 10.6.0 support only a single OAuth profile per IdP.

  • Event broker services 10.6.0 and later support two OAuth profiles per IdP. One OAuth profile must be for user authentication. The other OAuth profile must be for machine-to-machine authentication.

  • 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 Identity Provider

Using OAuth profiles for authenticating management access to your event broker service for users depends upon OAuth 2.0 and OpenID Connect (OIDC). OAuth profiles for machine-to-machine authentication depend upon OAuth client credential grants. Numerous identity providers (IdP) provide these tools, some more well know examples include:

Using OAuth profiles requires that you configure your IdP correctly. There is a configuration process for each type of authorization, with each having similar requirements:

  • User-based authentication

  • Machine-to-machine based authentication for connecting, where the event broker service is a resource server for other connecting event broker services, computers, or applications.

We outline the configuration process and requirements for each below. If you need help configuring your IdP, refer to their OpenID Connect documentation for authenticating users, and their client credential grants documentation for authenticating machines.

User-based authentication
For user-based authentication, the general IdP configuration process includes:

  • 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, your IdP provides the following information at a minimum:

  • A client ID

  • A client secret

  • An OpenID Connect Discovery or Configuration endpoint where your IdP publishes metadata. This is typically an URL ending in .well-known/openid-configuration.

Record the provided information, as it is required to set up authentication using the REST APIs in Configuring OAuth Profiles for Role-Based Authentication for an Event Broker Service.
Machine-to-Machine setup
To configure SSO authentication so connecting machines (other event broker services, computers, and applications) use the event broker service as a resource server, you must complete the following general IdP configuration process:

  • Set up an API, including providing it with the Hostname URL (located under DMR Cluster in the Detailed Service Information page) and assign permissions to it.

  • Create a machine-to-machine OAuth application and assign an API and credential permissions to it.

When configured correctly, your IdP may provide the following information:

  • A client ID (required for validation using an introspection endpoint)

  • A client secret (required for validation using an introspection endpoint)

  • The discovery endpoint where your IdP publishes metadata. It is typically an URL ending in .well-known/openid-configuration.

Record the information you require, as it is required to set up authentication using the REST APIs in Configuring OAuth Profiles for Machine-to-Machine Authentication for an Event Broker Service. You don't need the client ID and client secret if configuring validation of the token using JSON Web Key Sets (JWKS).

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

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

You can configure event broker services to authenticate connecting users through your OAuth identity provider (IdP). You do this by creating OAuth profiles on the event broker service. The OAuth profile contains information the event broker service requires to enable single sign-on through your IdP. You can map existing roles in PubSub+ Cloud through the OAuth profiles to custom roles in your IdP, providing role-based permissions to authenticated users. Role-based mappings allow you to provide direct access to the event broker service while restricting permissions to roles assigned through your (IdP) configuration.

In the procedures below, we create an OAuth profile, secure redirects from your IdP, and then map two roles: an editor and a viewer. We map these roles to existing Cluster Manager roles, providing the editor with permissions to perform an array of tasks through Broker Manager, and restricting the viewer to logging in and viewing the event broker service settings.

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

  1. Creating an OAuth Profile on the Event Broker Service

  2. Securing the Redirects From Your Identity Provider

  3. Mapping OAuth Profiles Roles for Authentication

Creating an OAuth Profile on the Event Broker Service

You require the following information from your IdP to complete this procedure:

  • A client ID

  • A client secret

  • (optional) Custom claims from your IdP if mapping roles

  • The OpenID Connect Discovery or Configuration endpoint where your IdP publishes metadata. This is an URL typically ending with .well-known/openid-configuration.

Complete the following steps to create the OAuth profile on the event broker service.

  1. 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:

  2. 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.

    3. Specify the Path Parameter fields as follows:

    Path ParameterDefinition
    serviceIdThe 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.
    resourcePathThe resource path where you want to define the resource object. For example, oauthProfiles/machineRole.

    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"
}

    Replace the variables in the JSON body above with the definitions listed in the table below

    Variable Definition
    CUSTOM_CLAIM You define custom claims in your IdP. The JSON web token (ID Token) issued as part of the authorization process contains the custom claim. You can use the custom claim to map permissions.
    CLIENT_ID The client ID is a alphanumeric string that is unique to the application you created in your IdP. It is provided by your IdP when you create the OAuth application.
    CLIENT_SECRET The client secret is a string used to sign and validate ID tokens for authentication flows. This is provided by your IdP when you create the OAuth application.
    ENDPOINT_DISCOVERY

    This is the OpenID Connect Discovery or Configuration endpoint where your IdP publishes metadata. It is typically an URL ending in .well-known/openid-configuration. Some examples include:

    • Azure: https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration
    • SAP IAS: https://accounts.sap.com/.well-known/openid-configuration

    If you do not configure have an OpenID Connect Discovery endpoint, you must configure the other endpoints manually.
    PROFILE_NAME Enter the same name you used for the PROFILE_NAME variable in URL when making this POST.

    A successful POST request returns code 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, 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 OAuth roles if your POST call completed successfully .

Securing the Redirects From Your Identity Provider

After creating an OAuth profile on the event broker service, 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.

Variable Definition
ENDPOINT

The URL to the event broker service: ${CLOUD_HOST}/api/v2/missionControl/eventBrokerServices/${SERVICE_ID}/broker

Where:

PROFILE_NAME The name of the OAuth profile you created in Creating an OAuth Profile on the Event Broker Service.

Specify the Path Parameter fields as follows:

Path ParameterDefinition
serviceIdThe 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.
resourcePathThe resource path where you want to define the resource object. For example, oauthProfiles/machineRole.

Provide the following JSON objects into the Body Params field:

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

Replace the variables in the JSON body above with the definitions listed in the table below:

VariableDefinition
VMR_HOST

The event broker service's hostname. You can find the hostname under DMR Cluster in the Detailed Service Information or 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.

SEMP_PORTThe port number for Secured Broker Management Host (SEMP) communication on the event broker service. You can find the SEMP port number by using the procedure to edit port configuration in the Cloud Console. For more information, see Editing the Existing Port Configuration for an Event Broker Service
PROFILE_NAMEThe name of the OAuth profile you created in Creating an OAuth Profile on the Event Broker Service.

A successful POST request returns a code 200.

Mapping OAuth Profiles Roles for Authentication

After securing redirects, you can create roles for the OAuth profile and map them to roles in your identity provider (IdP). You can create up to three OAuth profiles per event broker service and assign roles to the profiles as needed. Here, we are creating two roles for the OAuth profile we created earlier: an editor and a viewer. We will map these roles through the IdP to existing Cluster Manager roles in PubSub+ Cloud. The role mappings allow us to define the permissions users have 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 can view, edit, and delete event broker service properties. Meanwhile, users logging in with the viewer can only view event broker service settings.

To create the two roles, see:

Creating the Editor Role

To create the editor role 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 Parameter fields as follows:

Path ParameterDefinition
serviceIdThe 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.
resourcePathThe resource path where you want to define the resource object. For example, oauthProfiles/machineRole.

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}"
}

Replace the variables in the JSON body above with the definitions listed in the table below:

VariableDefinition
ACCESS_LEVEL_EDITOR_GROUP_NAMEThe claim value that is mapped to the editor level access for the group.
PROFILE_NAMEThe name of the OAuth profile you created when Creating an OAuth Profile on the Event Broker Service.

A successful PUT request returns a code 200.

Creating the Viewer Role

To create the viewer role 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:

Path ParameterDefinition
serviceIdThe 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.
resourcePathThe resource path where you want to define the resource object. For example, oauthProfiles/machineRole.

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}"
}

Replace the variables in the JSON body above with the definitions listed in the table below:

VariableDefinition
ACCESS_LEVEL_READER_GROUP_NAME

The claim value that is mapped to the viewer level access for the group.

PROFILE_NAMEThe name of the OAuth profile you created when Creating an OAuth Profile on the Event Broker Service.

A successful PUT request returns a code 200.

When configured successfully, users logging into an event broker service see a log in screen with the option to log-in with a username and password, using single-sign on (SSO) through your OAuth IdP, as shown in the image below. After configuring and testing OAuth profile-based authentication, you can disable basic authentication, forcing users to authenticate through SSO. For more information, 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 OAuth Profiles for Machine-to-Machine Authentication for an Event Broker Service

You can configure event broker services so that machines (other event broker services, computers, and applications) connecting to them authenticate with OAuth. You do this by creating an OAuth profile on the event broker service, and configuring it so that the event broker service acts as a resource server for the connecting applications. You can only create one OAuth profile on the event broker service for machine-to-machine authentication. Machines connecting to your event broker service receive authentication using an OAuth client credentials grant.

Before configuring your event broker services to use SSO for machine-to-machine authentication, ensure you have configured your identity provider (IdP) correctly. You also require an API token with the permissions outlined in Considerations for Configuring OAuth Profiles for Authentication.

You require various information to complete this procedure depending on whether token validation will be performed by an introspection endpoint, or JWKS:

  • A client ID (required for validation using an introspection endpoint)

  • A client secret (required for validation using an introspection endpoint)

  • The URL to your IdP

  • The discovery endpoint where your IdP publishes metadata. It is typically an URL ending in .well-known/openid-configuration.

To configure OAuth authentication for machine-to-machine connections to your event broker service services, follow these steps:

  1. Create the OAuth profile on the event broker service 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.

    2. Specify the Path Parameter fields as follows:

    Path ParameterDefinition
    serviceIdThe 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.
    resourcePathThe resource path where you want to define the resource object. For example, oauthProfiles/machineRole.

    Enter the following JSON object into the Body Params field:

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

    Replace the variables in the JSON body above with the definitions listed in the table below:

    Variable Definition
    CLIENT_ID Optional—The client ID is a alphanumeric string that is unique to the application you created in your IdP and is only required when validating a token by introspection endpoint. It is provided by your IdP when you create the OAuth application.
    CLIENT_SECRET Optional—The client secret is a string used to sign and validate ID tokens for authentication flows and is only required when validating a token by introspection endpoint. This is provided by your IdP when you create the OAuth application.
    ENDPOINT_DISCOVERY

    This is the OpenID Connect Discovery or Configuration endpoint where your IdP publishes metadata. It is typically an URL ending in .well-known/openid-configuration. Some examples include:

    • Azure: https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration
    • SAP IAS: https://accounts.sap.com/.well-known/openid-configuration

    If you do not configure have an OpenID Connect Discovery endpoint, you must configure the other endpoints manually.
    PROFILE_NAME Enter the same name you used for the PROFILE_NAME variable in URL when making this POST.
    AUDIENCE This is the URL to your IdP.

    A successful POST request 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 Path Parameter fields as follows:

    Path ParameterDefinition
    serviceIdThe 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.
    resourcePathThe resource path where you want to define the resource object. For example, oauthProfiles/machineRole.

    The GET request returns a list of profiles if your POST request created them successfully.

  2. 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.

  3. (Optional) After the configuration is successful, you can disable basic authentication for the event broker service.

  4. (Optional) When you no longer need the machine-to-machine based OAuth profile, you can delete it. See Deleting an OAuth Profile on an Event Broker Service.

Disabling Basic Authentication for Event Broker Service Management

You can disable basic access to your event broker service after creating and configuring OAuth profiles to better secure them. Disabling basic authentication includes:

Disabling Pre-Authentication Using the Cloud Console

You can disable pre-authentication for event broker services. This is an organization wide change. Once disabled, users must authenticate when launching Broker Manager from the Cloud Console and can do so using the OAuth profiles. For more information, see Pre-Authentication for Broker Manager

  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. Click User & Account, select Account Details, and then click the Account Settings.

  3. In the Security Settings section click the PubSub+ Pre Authentication slider to disable pre-authentication.

Disabling Basic User Access Using the REST API

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

You can disable basic user authentication for event broker services. This forces connecting users or machines (computers and applications) to authenticate with single sign-on using the OAuth profiles you configured on the event broker service. If you disable basic authentication, you should also consider disabling pre-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 Parameter fields as follows:

Path ParameterDefinition
serviceIdThe 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 whether 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

You can delete OAuth profiles when you no longer need them.

To delete an 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 Parameter fields as follows:

Path ParameterDefinition
serviceIdThe 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.
resourcePathThe resource path where you want to define the resource object. For example, oauthProfiles/machineRole.