Using token-based authentication with the REST API from IBM MQ 9.0.5

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. 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.
Optionally, configure the expiry time for the LTPA token. For more information, see Configuring the user logout timer.
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.
You can query the credentials of the current user by using the HTTP GET method on the login resource, providing the LTPA token, LtpaToken2, to authenticate the request. This request returns information about the authentication method, 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, LtpaToken2 that is returned from the request in the local cookie store.
Authenticate REST requests with the stored LTPA token, LtpaToken2, 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, LtpaToken2, 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, 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, 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, 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. 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
```

What to do next

If both HTTP and HTTPS ports are enabled for the mqweb server, consider enforcing the use of a secure HTTPS connection with the LTPA token. You can configure the mqweb server to require an HTTPS connection when an LTPA token is used:

As a privileged user, open the mqwebuser.xml file.
The mqwebuser.xml file can be found in one of the following directories:
- On UNIX, Linux®, and Windows: MQ_DATA_DIRECTORY/web/installations/installationName/servers/mqweb
- On z/OS®: WLP_user_directory/servers/mqweb
  where WLP_user_directory is the directory that was specified when the crtmqweb.sh script ran to create the mqweb server definition.
Add the following line to the mqwebuser.xml file:
```
<webAppSecurity ssoRequiresSSL="true"/>
```