Authentication/Authorization

BMC Public Api is designed for B2B (e.g. machine ids) to communicate via an OAuth2 client_credentials grant. It does not currently support B2C integration.

Authentication

Concepts

  • ApiClient: the process communicating with the Api. Could be software, could be a person executing commands in Postman.
  • Customer: the entity on-behalf-of which the ApiClient is interacting with the API

Authentication

The process to authenticate to the Api is managed via Amazon Cognito. ApiClients are registered as an app clients within Cognito and issued a client id and secret access key. This key is used to authenticate. The system will then return them a JWT with a specific scope. This scope will allow the ApiClient to perform various actions on the Api.

Scopes

  • support-user: this scope is intended for application support and grants the ApiClient access to all Api permissions.
  • publisher: this scope is intended for the BMC Listener process. It allows reports to be written to the Api. Using this scope REQUIRES an on-behalf-of header to be applied to the request.
  • read-write-user: this scope is assigned to third party ApiClients of the Api. It allows the caller to invoke a subset of Api calls on behalf of customers to which the ApiClient has been provisioned.

Getting a Bearer Token (JWT)

The process to authenticate is relatively simple and is demonstrated below via Postman.

Request to authenticate the ApiClient

Get bearer token

Gets bearer token for an ApiClient

The auth process is delegated to Cognito, and as such, an ApiClient will make an HTTP POST request to Cognito as follows:

POST https://ca-bmc-{env}.auth.us-east-1.amazoncognito.com/oauth2/token?grant_type=client_credentials

Request Headers

  • Authorization : "Basic"+[Username]:Password
  • Content-Type: "application/x-www-form-urlencoded"

On Success: HTTP 200 - OK If successful the request will return a bearer token

Payload: JSON payload (see response below)

Response Example

{
    "access_token":<Token> ,
    "expires_in": 3600,
    "token_type": "Bearer"
}

Once the authentication is done and you receive the token. You must use this token to call the BMC Public endpoints, by setting it as an Authorization Header as follows:

  • Authorization : Bearer [Token]
  • Content-Type : "application/json"

Authorization

Authorization in BMC Public Api is pretty simple. Scopes are defined in the JWT generated by Cognito. The token combined with a custom http header x-ca-on-behalf-of is the entirety of how an ApiClient is authorized to work on a customer's data.

Understanding multi-customer scopes and on-behalf-of logic

As mentioned in the "scopes" section of authentication, each app client assigned to an ApiClient will contain one to many scopes. These scopes provide ApiClients with permission to execute some or all of the Api calls. However, all Api calls are ALWAYS specific to a single Customer's data. As such, the Api uses the on-behalf-of workflow in order to determine which customer's data is affected.

For any read-write-user scope, if the ApiClient only has access to one customer's data, it will always default to that customer. This is determined by the Api's middleware interrogating the JWT and then fetching the customers to which this ApiClient has access. If only one customer id is associated with the ApiClient, that customer is always used by default.

In cases where there are more than one customer associated with the ApiClient, the middleware relies on the ApiClient to tell them which customer id to use via the x-ca-on-behalf-of header. For ApiClients configured with multi-customer access, this obo header is REQUIRED for all calls. It provides the Api middleware with a valid customer id. The middleware will validate that the AppClient has access to this customer and then sets it as the customer id for all work done in the scope of the request/response cycle.