Authentications and permissions in the REST APIs

Requests to all endpoints in the REST API must be on behalf of a TrueSight Server Automation user. Before processing a request, the API authenticates the request to determine the user. This API uses the API key-based protocol for this authentication. 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 Server Automation.

Authorization tokens

Every HTTP request to the API must contain a request header with the values for session-id and role parameters. The role parameter is optional. If there is no role specified in the request, the role assigned during the session creation is used.

Syntax:

curl -X GET "https://<hostname>:<port>/rest/<version>/servers" -H "accept: application/json" -H "session-id: <sessionID>" -H "role: <role>"

Example:

curl -X GET "https://<hostname>:<port>/rest/v1/servers" -H "accept: application/json" -H "session-id: 82a7e854-69cc-4191-85ad-df83f9cf6b73" -H "role: BLAdmins"

Sample response:

"session_id": "4c11beb3-4033-41f5-8e73-d61ca35c4c84",
"roles": "BLAdmins",
"expiration_time": "2019-05-16T19:39:01.764+0000",
"default_role": "BLAdmins",
"service_ticket": "string"

To configure the session expiration time, run the following command in the BLAS Admin console. An API session ID is an opaque string. A session ID is associated with one TrueSight Server Automation session that is created for a session POST request, and each session ID contains an expiry time, after which it is no longer valid, You should protect the session ID as securely as a password.

set authserver SessionCredentialLifetime <minutes>

The default value is 600 minutes.

To generate an expiring token from the /sessions endpoint

To generate an expiring token for a TrueSight Server Automation user, use the /api/v1/sessions endpoint. This endpoint accepts a POST request that contains the username, password, role, and authentication type of the user. TrueSight Server Automation supports SRP and Domain authentication for REST APIs.

As defined in the HTTP Basic authentication scheme defined in RFC 2617., you provide the request parameters. For example:

curl -X POST "<hostname>:<port>/rest/api/v1/sessions" -H "accept: application/json" -H "Content-Type: application/json"
-d "{ \"user_name\": \"BLAdmin\", \"password\": \"string\", \"role_name\": \"BLAdmins\", \"authentication_type\": \"SRP\"}"

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

"session_id": "4c11beb3-4033-41f5-8e73-d61ca35c4c84",
"roles": "BLAdmins",
"expiration_time": "2019-05-16T19:39:01.764+0000",
"service_ticket":"eNrNVntUE2cWzyQhQjCgCYp2gUbwsQWTmUl4JRtDAydmrFvwn8AMuOAsA== eNpz8nFMyc3MKwYAC+QC6w=="
"roles": ["BLAdmins"]

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 access permission from the user temporarily.
Deactivate the user temporarily.
Destroy the session by using DELETE:/sessions API.
Delete the user to invalidate all permanent and expiring tokens for them.

All tokens generated from this endpoint request expire after a certain time. 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.

Endpoints not requiring tokens

You can access the following endpoints without a token or HTTPS "Authorization" header:

/rest/<version>/api-docs: Returns the swagger definition of all endpoints in a given API version. For example, https://<servername>:<port>/rest/v2/api-docs.
/rest/apidocs: Returns the APIs in Swagger view. For example, https://<servername>:<port>/rest/apidocs
/api/<version>/sessions: This POST call generates an expiring token (session ID) for use when accessing other endpoints. For example, https://<servername>:<port>/rest/api/v1/sessions

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.

To configure and use Remedy Single Sign-On authentication

For information about configuring and using Remedy Single Sign-On authentication, see Implementing-Remedy-Single-Sign-On-authentication.