Using token-based authentication with the REST API

Users of the REST API can authenticate by providing a user ID and password to the REST API login resource with the HTTP POST method. An LTPA token is generated that enables the user to authenticate future requests. This LTPA token has the prefix LtpaToken2. The user can log out by using the HTTP DELETE method, and can query the log in information of the current user with the HTTP GET method.

Before you begin

Configure users, groups, and roles to be authorized to use the REST API. For more information, see Configuring users and roles.
By default, the name of the cookie that includes the LTPA token starts with LtpaToken2, and includes a suffix that can change when the mqweb server is restarted. This randomized cookie name allows more than one mqweb server to run on the same system. However, if you want the cookie name to remain a consistent value, you can specify the name that the cookie has by using the setmqweb command. For more information, see Configuring the LTPA token.
By default, the LTPA token cookie expires after 120 minutes. You can configure the expiry time of the LTPA token cookie by using the setmqweb command. For more information, see Configuring the LTPA token.
Ensure that you are using a secure connection when you send REST requests. When you use the HTTP POST method on the login resource, the user name and password combination that is sent with the request are not encrypted. Therefore, you must use a secure connection (HTTPS) when you use token based authentication with the REST API. By default, you cannot use HTTP with LTPA token authentication. You can enable the LTPA token to be used by insecure HTTP connections by setting secureLTPA to False. For more information, see Configuring the LTPA token.
You can query the credentials of the current user by using the HTTP GET method on the login resource, providing the LTPA token to authenticate the request. This request returns information about the user name, and the roles that the user is assigned. For more information, see GET /login.

Procedure

Log in a user:
1. Use the HTTP POST method on the login resource:
```
https://host:port/ibmmq/rest/v1/login
```
  Include the user name and password in the body of the JSON request, in the following format:
```
{
    "username" : name,
    "password" : password
}
```
2. Store the LTPA token that is returned from the request in the local cookie store. By default, this LTPA token has a prefix of LtpaToken2.
Authenticate REST requests with the stored LTPA token as a cookie with every request.
For requests that use the HTTP PUT, PATCH, or DELETE methods, include an ibm-mq-rest-csrf-token header. The value of this header can be anything, including blank.
Log out a user:
1. Use the HTTP DELETE method on the login resource:
```
https://host:9443/ibmmq/rest/v1/login
```
  You must provide the LTPA token as a cookie to authenticate the request, and include an ibm-mq-rest-csrf-token header. The value of this header can be anything, including blank
2. Process the instruction to delete the LTPA token from the local cookie store.
  
  Note: If the instruction is not processed, and the LTPA token remains in the local cookie store, then the LTPA token can be used to authenticate future REST requests. That is, when the user attempts to authenticate with the LTPA token after the session is ended, a new session is created that uses the existing token.

Example

The following cURL example shows how to create a new queue Q1, on queue manager QM1, with token-based authentication, on Windows systems:

Log in and add the LTPA token with the prefix LtpaToken2, to the local cookie store. The user name and password information are included in the JSON body. The -c flag specifies the location of the file to store the token in:
```
curl -k https://localhost:9443/ibmmq/rest/v1/login -X POST 
-H "Content-Type: application/json" --data "{\"username\":\"mqadmin\",\"password\":\"mqadmin\"}" 
-c c:\cookiejar.txt
```
Create a queue. Use the HTTP POST method with the queue resource, authenticating with the LTPA token. The LTPA token with the prefix LtpaToken2 is retrieved from the cookiejar.txt file by using the -b flag. CSRF protection is provided by the presence of the ibm-mq-rest-csrf-token HTTP header:
```
curl -k https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/queue -X POST -b 
c:\cookiejar.txt -H "ibm-mq-rest-csrf-token: value" -H "Content-Type: application/json" 
--data "{\"name\":\"Q1\"}"
```
Log out and delete the LTPA token from the local cookie store. The LTPA token is retrieved from the cookiejar.txt file by using the -b flag. CSRF protection is provided by the presence of the ibm-mq-rest-csrf-token HTTP header. The location of the cookiejar.txt file is specified by the -c flag so that the LTPA token is deleted from the file:
```
curl -k https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/queue -X DELETE 
-H "ibm-mq-rest-csrf-token: value" -b c:\cookiejar.txt 
-c c:\cookiejar.txt
```