Authentication and permissions in the REST API

Requests to all endpoints in the REST API must be on behalf of a BMC Discovery user. Before processing a request, the API authenticates the request to determine the user. The API uses the OAuth 2.0 protocol for this authentication, and the process is based on tokens as described below.

After successful authentication, a permission check decides if the user is allowed to perform the requested action. This check uses the existing group-based permissions.

Authentication tokens

Following the OAuth 2.0 specification, every HTTP request to the API must contain an "Authorization" header with the value "bearer <your_token>". For example:

curl -i -X GET -H 'Authorization: bearer <your_token>' https://appliance/api/v1.0/discovery

HTTP/1.1 200 OK
{
    "running": false,
    "status": "running"
}

An API token is an opaque string. A token is associated with one BMC Discovery user, either a local or LDAP user. Some tokens contain an expiry time, after which they are no longer valid, while others are permanent and never expire. In both cases the token should be protected as securely as a password.

You can generate a user token in one of the following ways:

Generate a permanent token from the user interface
Generate an expiring token from the /api/token endpoint

Generate a permanent token from the user interface

To generate a permanent token for a local BMC Discovery user, use the Users administration page. Tokens generated in this way do not expire, so can be embedded in a program or script which calls the REST API. Multiple requests to generate a token for the same user results in the same token being returned.

Security considerations

Protect the API token as securely as a password. If the token is leaked then delete the user to prevent unauthorized access. There is no way to revoke a permanent token.

Tokens cannot be generated for the local System user. This is to encourage more secure use of permissions in the system, and also because if the System user's API token was revealed there is no way to delete this user.

It is not possible to generate permanent tokens for LDAP users.

Generate an expiring token from the `/api/token` endpoint

To generate an expiring token for a local or LDAP BMC Discovery user, use the /api/token endpoint. This endpoint accepts a POST request containing the username and password of the user, which can be supplied in two ways.

The first approach is to use the HTTP Basic authentication scheme defined in RFC 2617. Supply your username and password in an Authorization header, separated by a single colon, within a base64 encoded string. The request body must contain the grant_type of "password". For example, for a username of "example", and a password of "SuperSecretPassword" the request would be:

curl -i -X POST -H 'Authorization: Basic ZXhhbXBsZTpTdXBlclNlY3JldFBhc3N3b3Jk' -d 'grant_type=password' https://appliance/api/token

Alternatively, supply the username and password in the POST request body, along with the grant_type field:

curl -i -X POST -d 'grant_type=password&username=example&password=SuperSecretPassword' https://appliance/api/token

In both cases the response body of a successful request returns the token inside the following JSON object:

{
    "access_token": "<your_token>",
    "expires_in": 3600,
    "token_type": "bearer"
}

All tokens generated from /api/token expire after one hour. Therefore this approach is more suited to a program or script which is run on-demand and on behalf of different users. Further tokens can be requested for a user as required.

Security considerations

Protect the API token as securely as a password. If the token is leaked before the expiry time, prevent unauthorized access by blocking REST API access for the remainder of the token's lifetime. You can do this in one of the following ways:

Remove the api-access permission from the user temporarily (see below).
Deactivate the user temporarily.

Alternatively you can delete the user to invalidate all permanent and expiring tokens for them.

Note that, as with the user interface approach, it is not possible to generate a token for the local System user.

Failed authentication

A request to generate a token from /api/token with incorrect credentials, or for a user that has been deactivated, results in a 401 Unauthorized HTTP status code.

A standard endpoint request that omits a valid, unexpired token also results in a 401 Unauthorized status code.

Endpoints not requiring tokens

The following endpoints may be accessed without a token or HTTP "Authorization" header:

/api/about: Returns a list of supported API versions and product information.
/api/token: Generates an expiring token for use when accessing other endpoints.

/api/<version>/swagger.json: Returns the swagger definition of all endpoints in a given API version. For example, /api/v1.0/swagger.json.

Permissions

After successful authentication of a user, endpoints check the user has permission to perform the requested action. Users require the same permissions as if they were attempting the action through the equivalent user interface or command line tool. For example, if a user does not have permission to start new discovery runs in the user interface, they cannot do it from the REST API either. If the user lacks the required permission, a 403 Forbidden status code is returned from the endpoint.

There is also a specific permission required to make ANY requests to the REST, CSV or XML APIs. This is the api-access permission. Without this permission, a 403 Forbidden status code is also returned from any endpoint.

If writing a script or program to make unattended calls against the REST API, it is recommended that a new local BMC Discovery user of type "API Access" is created just for this purpose. This user can be given just the permissions that the program requires, and a permanent token can be generated and embedded in the program.