SEMP Authentication and Authorization

SEMP v2 supports a number of security features for authentication and access control:

These features are discussed in the sections that follow.

Authentication is required for all requests.

Basic Authentication

SEMP uses management usernames and passwords for HTTP Basic authentication.

To use basic authentication:

  1. Format the credentials as <username>:<password>. For example solly:super_otter_123.

  2. Base-64 encode the formatted credentials. In this example, the result is c29sbHk6c3VwZXJfb3R0ZXJfMTIz.

  3. Include the encoded result in the HTTP Authorization header:

For example, a request using these credentials could be:

curl --location 'http://192.168.133.81:8080/SEMP/v2/monitor/msgVpns/msgVPN1/queues?select=accessType%2Cdurable' \
--header 'Authorization: Basic c29sbHk6c3VwZXJfb3R0ZXJfMTIz'
GET /SEMP/v2/monitor/msgVpns/msgVPN1/queues?select=accessType,durable HTTP/1.1
Host: 192.168.133.81:8080
Authorization: Basic c29sbHk6c3VwZXJfb3R0ZXJfMTIz
Cookie: Session=viyDrD0kRXgTGcqQkC4wLWeTqKEZwoEajuGdEdVEdj0

If authentication is successful, a session is created and the broker returns a cookie containing a session token.

SEMP supports both HTTP and HTTPS connections.

OAuth Authentication

To authenticate using OAuth, a SEMP client must include one or more OAuth tokens in the HTTP Authorization header as a bearer token. The bearer token in the Authorization header must be provided on every request.

In general, the iss claim in the ID token (for OpenID Connect) or access token (for OAuth 2.0), if present, is used by the event broker to identify which OAuth profile to use.

A specific OAuth profile can also be selected by adding ~base64(<issuer>)~ to the beginning of the bearer token. Base64 padding should not be used. For example, to use an OAuth profile called solace that has an issuer of https://www.solace.com with an access token:

Bearer ~aHR0cHM6Ly93d3cuc29sYWNlLmNvbQ~<access_token>

If a profile cannot be identified from the iss claim in the token, and no issuer prefix is provided in the Authorization header, the default profile is used.

Single token

In most case, a single OAuth token is used for authentication. The following format is used to pass a single token in the authentication header: Authorization: Bearer <token>.

Example:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImYwdDZrMUVyWVNXeDdCSmRzNHVkOU8wa2wzcEFxOHVTV3RTdnJHVTJaRmkiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOiJTa2MxSmpsLyIsImVtYWlsIjoic29sbHlAZXhhbXBsZS5jb20iLCJleHAiOjE2MzY2NTA0MjMsImdyb3VwcyI6WyJPdHRlcnMiLCJNYW1tYWxzIl0sImlhdCI6MTYzNjY0NjgyMywiaXNzIjoiaHR0cHM6Ly9teS1vYXV0aC1wcm92aWRlci5leGFtcGxlLmNvbSIsInN1YiI6IlJpaEJDQmszIn0.oIo9gDbjx3qW3Rg-IiKw4B67KIcJ6_l7dTdlI5inwI9lH84moyG_GM0cN1yFnjVioVjUN7h5Ok5ubHW2BaSaSifC1JjpDzFB55bHSA8ygjZaEtCWXCFDUbs-8yN6BWr7jhKbJ6Iffg285Sm5C2H4rXkBC4Z50bu5k2-hK8OVkF5hi0amOl7-K0S6UtiFkqPaGtru5JHhOJ6m8b7tIfB3YYwIT1xGtkqr_4AfQO3tFziUJFXtZ7-dRMlqQhsS2nO_kA18Aa_5RNyAdRx-HGq3W_DMcxlNj1E3VURrLhLx6s-mxAZSTpwIXWv_KTUblUjAc7gp-sYZFwrXdbDhx-4B3A

Multiple tokens

When an OpenID Connect provider issues both an ID token and an access token together, the ID token may contain a reduced number of claims. In such cases, the event broker may require both the ID token and the corresponding access token—authenticating the user through the ID token, and using the access token to retrieve additional claims from the OpenID Connect Userinfo endpoint for the username or group information. The following format is used to pass multiple tokens in the authentication header: Authorization: Bearer <id-token>/<access-token>.

Example:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImYwdDZrMUVyWVNXeDdCSmRzNHVkOU8wa2wzcEFxOHVTV3RTdnJHVTJaRmkiLCJ0eXAiOiJKV1QifQ.eyJhdF9oYXNoIjoiMG5CUGZPUm5uX0l0Z2RTTUNsR2dHUSIsImF1ZCI6IktpQWVIMWtuIiwiZXhwIjoxNjM2NjUwNzYyLCJpYXQiOjE2MzY2NDcxNjIsImlzcyI6Imh0dHBzOi8vbXktb2F1dGgtcHJvdmlkZXIuZXhhbXBsZS5jb20iLCJzdWIiOiJPMjlWTmtvKyJ9.ZMQge6iyjmduO4IY0TaBB3ynqX1NeAmiMfYqZdsPn4bFSs9A0J7aAsc_iuJQcOQrZjEtv-3OXhrAsulTcmLYFCHUTlhWR5oA1eC0cbK1d3gYDeSFo6YUrxlGM9cRYQbr_0fG6VbRc5ivRyowAqmursnk5TVbje4H_Jpug2qnZVrYspZkixqlIkZN6nEbT2Uxzqypvo1o5y1H19uq1t5SF8KKsA9Y22Pgq88mpGg8U27Ov_CY0NKGh_U5KMRVrlQ1X84E0SmpJSWosM9L5Gy7nYGuGhvVGH91eGwxh24L0lpy6HcQkCS7wCiLseVntWcIvu5BUo4mMPCqvQDmg47I7A/zOvubUTO7ig+u2+2NWAibm2U5Tg/pKE4JcwTCwM+qNw=

SEMP Sessions

When a client makes its first SEMPv2 request, it must supply a username and password using HTTP Basic authentication, or an OAuth token or tokens using HTTP Bearer authentication.

When HTTP Basic authentication is used, the broker returns a cookie containing a session key. The client can omit the username and password from subsequent requests, because the broker now uses the session cookie for authentication instead. When the session expires or is deleted, the client must provide the username and password again, and the broker creates a new session.

There are a limited number of session slots available on the broker. The broker returns 529 No SEMP Session Available if it is not able to allocate a session.

If certain attributes—such as a user's password—are changed, the broker automatically deletes the affected sessions. However, changes in external user configuration data stored on a RADIUS or LDAP server do not trigger the broker to delete the associated session(s), therefore you must do this manually, if required.

The session is deleted if:

  • the client logs out.
  • the session times out due to inactivity.
  • the session reaches its maximum lifetime.
  • the client's user credentials are altered on the broker. This includes password updates, username changes, and user deletion. It does not include access level changes. If the user credentials change, the event broker deletes all sessions for that user.
  • the broker's auth-type configuration changes (for example, from Radius to LDAP, or from one LDAP profile to another). If the auth-type configuration changes, the event broker deletes all sessions.
  • an admin user deletes the client's session(s) via SEMPv2 or the Solace CLI.
  • the broker restarts.

When the session terminates for any reason, the associated token immediately becomes invalid and cannot be used again. The client must authenticate again to create a new session cookie.

A client can retrieve its current session information using the /about/user endpoint and delete its own session using the /about/user/logout endpoint. A client with appropriate permissions can also manage all sessions using the /sessions endpoint.

Sessions are not created when authenticating with an OAuth token or tokens using HTTP Bearer authentication. If a session cookie is provided, it is ignored.

For information about configuring sessions, see Managing SEMP Sessions.

Sessions are also used by Broker Manager. For details, see Broker Manager Sessions.

Role-Based Access Control

SEMP supports role-based access control. When executing SEMP requests against an event broker, the SEMP user will be authenticated as an event broker management user (equivalent to a Solace CLI user) and receive the access level and scope assigned to that management user. The following is a brief summary of role-based access control on event brokers. For more details refer to Management & Shell Users, which provides full details of the rules and how they work together to provide access control.

There are two access level scopes supported on the event broker:

  • Global
  • Message VPN

There are five user access levels in the event broker:

  • none
  • read-only
  • mesh-manager
  • read-write
  • admin

A management user is then assigned access levels for both the global level and for one or more Message VPNs. This forms the management user's role-based access control. For example:

  • A system-wide event broker administrator would be assigned a global access level of admin, which allows that user to read and modify any attribute of any resource in the API, whether it is a global-scoped or Message VPN-scoped attribute.
  • An event mesh administrator would be assigned a global access level of mesh-manager and a Message VPN access level of read-write for the Message VPN the administrator is responsible for.
  • A Message VPN administrator would be assigned a global access level of none and a Message VPN access level of read-write for the Message VPN the administrator is responsible for.

There are many more examples of how you can effectively use the scope and access level for different types of users. For more examples see the documentation referenced above.

Every SEMP request requires a scope and access level determined in accordance with the following rules:

  • All APIs:

    To make a GET request, the user must have the minimum scope and access level required to retrieve each requested attribute. By default, all attributes are requested in a GET request, but the select query parameter can be used to exclude attributes to which the user does not have access.

  • Configuration API:

    To make a POST request or a PUT request that creates a new object, the user must have the minimum scope and access level required to create the object. In addition, the user must have the minimum scope and access level required to change each attribute provided in the request that differs from the default value.

    To make a PATCH request or a PUT request that replaces an existing object, the user must have the minimum scope and access level required to change each attribute provided in the request that differs from the current value.

    If an attribute is not provided in a PUT request that replaces an existing object, the attribute is reset to its default value. However, if the user does not have the minimum access scope and user access level required to change the attribute, the request will not fail; instead, the attribute will be left unchanged. This allows SEMP users to make PUT requests even if they do not have full access to the object.

    To make a DELETE request, the user must have the minimum scope and access level required to delete the object.

  • Action API:

    To make a PUT request, the user must have the minimum scope and access level required to perform the action.

In general, in the SEMP API all resources under /msgVpns/<msgVpnName>/... are part of the Message VPN scope. All other top-level resources form part of the global scope. The /msgVpns/<msgVpnName> is one resource where the scope of attributes is mixed. Some attributes require global scope and some require Message VPN-level scope. In all cases, the SEMP API Reference makes it clear which scope and access level is required for each SEMP resource.