Use token-based authentication with the REST API for IBM MQ Version 9.0.4 and earlier

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 Configure users and roles.
  • Optionally, configure the expiry time for the LTPA token. For more information, see Configure the user logout timer.
  • Ensure that you are using a secure connection when you send REST requests. When we 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 we use token based authentication with the REST API.
  • We 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

  1. Log in a user:
    1. Use the HTTP POST method on the login resource: 
      https://host:port/ibmmq/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, and CSRF token cookie, csrfToken, that are returned from the request in the local cookie store.
  2. Authenticate REST requests with the stored tokens:

    • Provide the LTPA token, LtpaToken2, as a cookie with every request.
    • For requests that use the HTTP PUT, PATCH, or DELETE methods, include the contents of the CSRF token, csrfToken, in a ibm-mq-rest-csrf-token header.

      The content of the csrfToken cookie is used to confirm that the credentials that are being used to authenticate the request are being used by the owner of the credentials. That is, the token is used to prevent cross-site request forgery attacks.

      We cannot use a cached version of the content of the cookie because the content of the cookie can change. You must use the latest value of the cookie for each request.

  3. Log out a user:
    1. Use the HTTP DELETE method on the login resource: 
      https://host:9443/ibmmq/v1/login
      You must provide the LTPA token, LtpaToken2, as a cookie to authenticate the request. You must also include the contents of the CSRF token, csrfToken, in an ibm-mq-rest-csrf-token header.
    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, and CSRF token, csrfToken, 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 and including the contents of the CSRF token in a header. The LTPA token, LtpaToken2, is retrieved from the cookiejar.txt file by using the -b flag. The CSRF token, csrfToken, is included in an ibm-mq-rest-csrf-token HTTP header. The value of the CSRF token is copied from the cookiejar.txt file: Version 9.0.4: 
    curl -k https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/queue -X POST -b c:\cookiejar.txt 
-H "ibm-mq-rest-csrf-token: D82EEBAF1D52F51FE14766474282D3573A432F30D5CD730DB04B1B6187940DF9138B69
381DD68E7B0042ABA0C3D6EFFA2F6DBE13E1F67AEFE309E7AA02AD6013FFCB6265210281C7949690E215750A1F55FDBA8B
16B25EAA6F915F7F2299CC2B87EFB9AD4BAAFD28210DDAA9563AC23DDAB259C8992079A7917194E0A6A6ABE1B3DDA5E2D0
3187FF8CEE8C707E012D730F2B278ADF6E67A3F4AC1FD5586DEF91C7EC04F5969138D929B7CC118B9EBC74D2733EF90E90
3E0A4792A198AF5281F1CFB6E500F72EECDB63B43FED5813708FE1EAC518CA88DFCF687A5AA41BC2BCD3B6C173A605C6A7
2E7C49F60113B6D171FDCAF7ED85D14FF32761D5BC771796BF" -H "Content-Type: application/json" 
--data "{\"name\":\"Q1\"}"
    Version 9.0.3 and earlier: 
    curl -k https://localhost:9443/ibmmq/rest/v1/qmgr/QM1/queue -X POST -b c:\cookiejar.txt 
-H "ibm-mq-rest-csrf-token: D82EEBAF1D52F51FE14766474282D3573A432F30D5CD730DB04B1B6187940DF9138B69
381DD68E7B0042ABA0C3D6EFFA2F6DBE13E1F67AEFE309E7AA02AD6013FFCB6265210281C7949690E215750A1F55FDBA8B
16B25EAA6F915F7F2299CC2B87EFB9AD4BAAFD28210DDAA9563AC23DDAB259C8992079A7917194E0A6A6ABE1B3DDA5E2D0
3187FF8CEE8C707E012D730F2B278ADF6E67A3F4AC1FD5586DEF91C7EC04F5969138D929B7CC118B9EBC74D2733EF90E90
3E0A4792A198AF5281F1CFB6E500F72EECDB63B43FED5813708FE1EAC518CA88DFCF687A5AA41BC2BCD3B6C173A605C6A7
2E7C49F60113B6D171FDCAF7ED85D14FF32761D5BC771796BF" -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. The CSRF token, csrfToken, is included in an ibm-mq-rest-csrf-token HTTP header. The value of the CSRF token is copied from the cookiejar.txt file. 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/login -X DELETE 
-H "ibm-mq-rest-csrf-token: D82EEBAF1D52F51FE14766474282D3573A432F30D5C
D730DB04B1B6187940DF9138B69381DD68E7B0042ABA0C3D6EFFA2F6DBE13E1F67AEFE3
09E7AA02AD6013FFCB6265210281C7949690E215750A1F55FDBA8B16B25EAA6F915F7F2
299CC2B87EFB9AD4BAAFD28210DDAA9563AC23DDAB259C8992079A7917194E0A6A6ABE1
B3DDA5E2D03187FF8CEE8C707E012D730F2B278ADF6E67A3F4AC1FD5586DEF91C7EC04F5
969138D929B7CC118B9EBC74D2733EF90E903E0A4792A198AF5281F1CFB6E500F72EECDB
63B43FED5813708FE1EAC518CA88DFCF687A5AA41BC2BCD3B6C173A605C6A72E7C49F6011
3B6D171FDCAF7ED85D14FF32761D5BC771796BF" -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. We can configure the mqweb server to require an HTTPS connection when an LTPA token is used:
  1. 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.

  2. Add the following line to the mqwebuser.xml file:
    <webAppSecurity ssoRequiresSSL="true"/>