Using token-based authentication with the REST API for IBM MQ 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 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
Example
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 anibm-mq-rest-csrf-token
HTTP header. The value of the CSRF token is copied from the cookiejar.txt file:IBM MQ 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\"}"
IBM MQ 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 anibm-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
- 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.
- On UNIX, Linux®, and Windows:
- Add the following line to the mqwebuser.xml
file:
<webAppSecurity ssoRequiresSSL="true"/>