Authentication and permissions in the TSWS REST API

Requests to all endpoints in the REST API must be on behalf of a TrueSight Presentation Server user. Before processing a request, the API authenticates the request to determine the user. The API uses the OAuth 2.0 protocol 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 role-based accessed used by the TrueSight Presentation Server.

Authentication tokens

Every HTTP request to the API must contain an "Authorization" header with the value "authToken <your_token>". For example:

curl -X POST "https://tsps.host.com:443/tsws/api/v10.1/token?username=admin&password=admin12345&tenantName=*" -H "accept: application/json"

An API token is an opaque string. A token is associated with one TrueSight Presentation Server user, and each token contains an expiry time, after which it is no longer valid, You should protect the token as securely as a password.

To generate an expiring token from the /token endpoint

To generate an expiring token for a TrueSight Presentation Server user, use the /api/v10.1/token endpoint. This endpoint accepts a POST request that contains the username, password, and tenant of the user.

As defined in the HTTP Basic authentication scheme defined in RFC 2617., you supply the three request parameters, as in the following example:

curl -X POST "https://tsps.host.com:443/tsws/api/v10.1/token?username=admin&password=admin12345&tenantName=*" -H "accept: application/json"

This sample request returns a request similar to the following example:

{
"authToken": "_ce14bc5c-e517-4df4-916f-5b942ec25b35",
"authPassed": true,
"expires": "2018-01-18T13:08:18.000Z",
"status": "OK"
}

All tokens generated from this endpoint request 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/about 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.

Permissions

After successful authentication of a user, endpoints verify that 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, BMC recommends that a new local <productName> user of type "API Access" is created just for this purpose.This user can be given just the required permissions for the program.