Configuring Management OAuth Profiles for Event Broker Service Authentication

You can enable Single Sign-On (SSO) for individual event broker services using the REST APIs for advanced event mesh 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 or SAP Identity Authentication Service (IAS) to advanced event mesh 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

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 REST API for advanced event mesh.

  • You can create a maximum of three OAuth profiles per event broker service for role-based authentication.

  • You must configure your OAuth provider or SAP Identity Authentication Service (IAS) correctly. See Configuring Your OAuth Provider or SAP Identity Authentication Service.

  • The event broker service does not natively support multiple OAuth profiles using the same IdP.

  • You can't map advanced event mesh roles to SAP IAS custom claims.

  • You can't configure event broker services to use claim arrays (for example, {"claim":["claimOne","claimTwo"]})

  • 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 or SAP Identity Authentication Service

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) or SAP Identity Authentication Service (IAS) 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 or SAP IAS 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. See Consume APIs from Other Applications in the SAP documentation.

For more information about configuring your OAuth IdP or SAP IAS correctly, see your OAuth provider documentation or the SAP Identity Authentication Operation Guide.

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 advanced event mesh. 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 or SAP (IAS) correctly. To configure your event broker service services to OAuth profiles for authenticating user log in, follow these steps:

  1. Creating a Connection to Your Identity Provider

  2. Securing Redirects From Your Identity Provider

  3. Mapping the OAuth Profiles for Authentication

Creating a Connection to Your Identity Provider

    The first step in configuring role-based authentication for your event broker service is to create a connection between the event broker service and your OAuth identity provider or SAP Identity Authentication Service (IAS). To create this connection, you issue the following POST call: https://${ENDPOINT}/SEMP/v2/config/oauthProfiles/${PROFILE_NAME}.

    Where:

    • {ENDPOINT}—Replace this with ${CLOUD_HOST}/api/v2/missionControl/eventBrokerServices/${SERVICE_ID}/broker where:

    • {PROFILE_NAME}—The name of the profile you created for role-based authentication with your Identity Provider (IdP).

    Provide the following JSON objects in the body of the POST call:

    {
  "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 profiles by issuing the following GET call: https://${ENDPOINT}/SEMP/v2/config/oauthProfiles. Replace the ENDPOINT variable with the ${CLOUD_HOST}/api/v2/missionControl/eventBrokerServices/${SERVICE_ID}/broker URL outlined at the start of this procedure.

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

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

    • 400—Something is wrong with the request. For example, there is a typo or the requested object cannot be found.

    • 401—Something is wrong with the client authentication. For example, the password is incorrect or the user does not exist.

    • 403—The necessary permissions are not enabled on the API token.

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, issue the following POST call: https://${ENDPOINT}/SEMP/v2/config/oauthProfiles/${PROFILE_NAME}/clientAllowedHosts.

Where:

  • {ENDPOINT}—Replace this with ${CLOUD_HOST}/api/v2/missionControl/eventBrokerServices/${SERVICE_ID}/broker where:

  • {PROFILE_NAME}—The name of the profile you created in your Identity Provider (IdP).

Provide the following JSON objects in the body of the POST:

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

Where:

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

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

  • 400—Something is wrong with the request. For example, there is a typo or the requested object cannot be found.

  • 401—Something is wrong with the client authentication. For example, the password is incorrect or the user does not exist.

  • 403—The necessary permissions are not enabled on the API token.

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 advanced event mesh. 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

To create the editor profile issue the following PUT call: https://${ENDPOINT}/SEMP/v2/config/oauthProfiles/${PROFILE_NAME}/accessLevelGroups/${ACCESS_LEVEL_EDITOR_GROUP_NAME}.

Where:

  • {ENDPOINT}—Replace this with ${CLOUD_HOST}/api/v2/missionControl/eventBrokerServices/${SERVICE_ID}/broker where:

  • {PROFILE_NAME}—The name of the profile you created in your Identity Provider (IdP).

  • {ACCESS_LEVEL_EDITOR_GROUP_NAME}—The claim value that is mapped to the editor level access for the group.

Enter the following JSON object in the body of the POST:

{
  "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.

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

  • 400—Something is wrong with the request. For example, there is a typo or the requested object cannot be found.

  • 401—Something is wrong with the client authentication. For example, the password is incorrect or the user does not exist.

  • 403—The necessary permissions are not enabled on the API token.

Creating the Viewer Profile

To create the viewer profile issue the following PUT call https://${ENDPOINT}/SEMP/v2/config/oauthProfiles/${PROFILE_NAME}/accessLevelGroups/${ACCESS_LEVEL_READER_GROUP_NAME}

Replace the variables in the POST call above with values as listed below:

  • {ENDPOINT}—Replace this with ${CLOUD_HOST}/api/v2/missionControl/eventBrokerServices/${SERVICE_ID}/broker where:

  • {PROFILE_NAME}—The name of the profile you created in your Identity Provider (IdP).

  • {ACCESS_LEVEL_READER_GROUP_NAME}—The claim value that is mapped to the editor level access for the group.

Enter the following JSON object in the body of the POST:

{
  "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.

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

  • 400—Something is wrong with the request. For example, there is a typo or the requested object cannot be found.

  • 401—Something is wrong with the client authentication. For example, the password is incorrect or the user does not exist.

  • 403—The necessary permissions are not enabled on the API token.

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, 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 advanced event mesh roles mapped in your OAuth provider account or SAP Identity Authentication Service (IAS). 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 SAP (IAS) 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:

  1. Setup the OAuth profile by issuing the following PUT call: https://${ENDPOINT}/SEMP/v2/config/oauthProfiles/${PROFILE_NAME}

    2. Replace the variables in the PUT call above with values listed below:

    • {ENDPOINT}—Replace this with ${CLOUD_HOST}/api/v2/missionControl/eventBrokerServices/${SERVICE_ID}/broker where:

    • {PROFILE_NAME}—The name of the profile you created for role-based authentication with your Identity Provider (IdP).

    Enter the following JSON object in the body of the PUT:

    {
  "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 issuing a GET to https://${ENDPOINT}/SEMP/v2/config/oauthProfiles. Replace the ENDPOINT variable with the ${CLOUD_HOST}/api/v2/missionControl/eventBrokerServices/${SERVICE_ID}/broker URL outlined at the start of this procedure.

    The GET returns a list of roles if your PUT 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 or the SAP Identity Authentication Operation Guide 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. 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:

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

  1. Log in to the 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 Cloud Console.

  2. Click User & Account, select Account Details, and then click the Account Settings.

  3. In the Security Settings section click the SAP 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 issue a PUT to https://{CLOUD_HOST}/api/v2/missionControl/eventBrokerServices/{serviceId}/sempBasicAuth

Where:

  • {CLOUD_HOST}—The URL for the Cloud Console, for example https://console.sap.cloud

  • {SERVICE_ID}—The unique identifier of the event broker service where you want to disable basic authentication. You can determine the unique identifier for an event broker service using the Cloud Console or by using a GET call. See Getting the Connection Details for the Event Broker Service Using the REST API.

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, issue the following DELETE call: https://${ENDPOINT}/SEMP/v2/config/oauthProfiles/${PROFILE_NAME}

Where:

  • {ENDPOINT}—Replace this with ${CLOUD_HOST}/api/v2/missionControl/eventBrokerServices/${SERVICE_ID}/broker where:

  • {PROFILE_NAME}—The name of the profile you created for role-based authentication with your Identity Provider (IdP).