Web services authentication
This section explains how the web service requests are authenticated. The implementation of the authentication mechanism varies according to your Infrastructure Management setup.
Authentication mechanism
A web service request is authenticated using a user name and password. You have the option to use a tenant name with the user name and password for some web service requests. The user credentials are passed through the HTTP header. Based on your Infrastructure Management setup, the user credentials are authenticated against the information in the Infrastructure Management Database, the LDAP server, or Remedy SSO.
The authentication mechanism uses the following formats to encode the user credentials:
URL-encoded format
In the URL-encoded format, a successful authentication generates an authentication token. You can use this authentication token in your subsequent web service requests. The token has a time-limited validity. You can configure the validity time of the authentication token by updating the value of the loginExpiryInterval_hrs property set in the bppmws.properties file. In a multiple server environment, you must set this property in all the servers. The file is located in the pw\pronto\conf directory. By default, the value of the loginExpiryInterval_hrs property is 24.
Expiry settings is controlled by Remedy SSO settings
The loginExpiryInterval_hrs property settings is controlled by the expiry settings configured in Remedy SSO.
Authenticating user credentials
The login API uses the POST method to authenticate user credentials. After successful authentication, the login API generates an authentication token.
The generic syntax of the URL to authenticate user credentials is as follows:
https://<TSPShostname>:<port>/tsws/10.0/api/authenticate/login
Entry | Description |
|---|---|
https|http | Type of protocol to send the request. BMC TrueSight Presentation Server supports HTTPS protocol by default. You can use HTTP protocol as well. |
serverHost | Host name of the Presentation Server. |
port | Port number through which communication is established. By default, the HTTPS protocol is supported and the default port number is 443. If you use HTTP protocol, use the port number 80. |
Input parameters for login API
You must provide the following parameters in the URL-encoded format.
Parameters | Description |
|---|---|
username | User name that you want to authenticate |
password | Password for the corresponding user name |
tenantName | Name of the tenant for which you want to fetch data. This parameter is optional and is applicable only for stats, configdata, and metadata APIs. |
Sample input parameters in the JSON format are as follows:
{ "username" : "admin", "password" : "admin12345" , "tenantName" : "*" }Response information to login API
The sample response is as follows:
{
"response": {
"status": "OK",
"authToken": "TC9r9c/izIOdaQzztOjlqDE8ozc=",
"authPassed": true
},
"statusCode": "200",
"statusMsg": "OK",
"responseTimeStamp": "2011-07-05T18:08:54"
}The authentication token that is generated is TC9r9c/izIOdaQzztOjlqDE8ozc=. You can also find the expiration date and time of the authentication token in the JSON response.
Note
The REST client internally makes an authentication login API call each time it is used, passing the username/password specified in the command line. Therefore, do not use the REST client to directly call the login API.
Authenticating from a POST request
To authenticate from a POST request, send username=admin&password=admin in the body and content type as application/x-www-form-urlencoded of the POST request to the authentication API URL.
Using the authentication token
You must provide the authentication token in the header of your subsequent web service requests by using the authorization parameter. The use of the authentication token in the header of a web service request is as follows:
authorization authtoken TC9r9c/izIOdaQzztOjlqDE8ozc=In this example, authtoken TC9r9c/izIOdaQzztOjlqDE8ozc= is the value of the authorization parameter.
Ending the validity of an authentication token
You can manually end the validity of an authentication token by using logout API that uses the POST method.
The generic syntax of the logout API is as follows:
https://<TSPShostname>:port/tsws/10.0/api/authenticate/logout
Input parameters for logout API
You must provide the following parameters in the URL-encoded format:
Parameters | Description |
|---|---|
username | User name that you want to authenticate |
password | Password for the corresponding user name |
tenantName | Name of the tenant for which you want to fetch data. This parameter is optional. |
Response information of logout API
The sample response is as follows:
{
"response": {
"status": "OK",
"authPassed": true
},
"statusCode": "200",
"statusMsg": "OK",
"responseTimeStamp": "2011-12-07T14:05:19"
}
You cannot use the authentication token after ending its validity. You must create a new authentication token by using the login API.
Base64-encoded format
In this format, a concatenated string of the user name and password separated by a colon (:) is created. This string is encoded in the Base64 format. A web service client uses this encoded string as the user credentials in the HTTP header. Every web service request must have the Base64-encoded format of the user credentials in the HTTP header. If you decide to use this format, you do not have to run the login API.
For example, if the user name is admin and password is admin, the concatenated string is admin:admin. The Base64 encoded string of admin:admin is YWRtaW46YWRtaW4=. You must use this encoded string as the user credentials in the HTTP header of every web service request. The use of the Base64 encoded string in the header of a web service request is as follows:
authorization basic YWRtaW46YWRtaW4=Note
BMC recommends that you use the Base64 format only when you have SSL configured and if you do not use web service requests frequently.
Comments
Hi, I think there is a mistake in the "Ending the validity of an authentication token" section. Using "username, password tenantName" isn't working (an error message appears). Instead only using "authToken" parameter seems to work just fine. Liran.
Yes, the documentation here needs to be updated. Thank you Liran! Nice catch! :)
Thanks, Liran Tevet and Josh Reynolds. We will update the documentation and you will see it when we publish the changes very soon.
HI, please look at the new authentification web URL. In TSPS it is called "https://:port/tsws/api/v10.1/token". In this documentation you have the old URL inside.
Hi, still something is missing. TSIM auth logout doesn't work, as new parameter "Token To Logout" is requested:
'https://monptsim.sp.securitasdirect.local/bppmws/api/authenticate/logout' { "errors": [ "Required input parameter Token To Logout is not found." ], "responseTimeStamp": "2019-09-30T06:46:30", "statusCode": "400", "statusMsg": "Bad Request" }
Note to self:
Requested Parag for contact and clarification, as this is content has not been updated in recent times.
Hi @Sistemas Securitas direct, thanks for the feedback. I have checked with the concerned team and it is working fine. Please recheck it and let us know if you face any issues.
Log in or register to comment.