Use HTTP basic authentication with the REST API

Users of the REST API can authenticate by providing their user ID and password within an HTTP header. To use this method of authentication with HTTP methods, such as POST, PATCH, and DELETE, the ibm-mq-rest-csrf-token HTTP header must also be provided, as well as a user ID and password.


Before you begin

  • Configure users, groups, and roles to be authorized to use the REST API. For more information, see Configure users and roles.
  • Ensure that HTTP basic authentication is enabled. Check that the following XML is present, and is not commented out, in the mqwebuser.xml file. This XML must be within the <featureManager> tags:
    <feature>basicAuthenticationMQ-1.0</feature>
    You must be a privileged user to edit the mqwebuser.xml file.
  • Ensure that you are using a secure connection when you send REST requests. As the user name and password combination are encoded, but not encrypted, you must use a secure connection (HTTPS) when we use HTTP basic 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 basic authentication information 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. Concatenate the user name with a colon, and the password. For example, a user name of admin, and a password of admin becomes the following string:
    admin:admin
  2. Encode this user name and password string in base64 encoding.
  3. Include this encoded user name and password in an HTTP Authorization: Basic header. For example, with an encoded user name of admin, and a password of admin, the following header is created:
    Authorization: Basic YWRtaW46YWRtaW4=
  4. When we use HTTP POST, PATCH, or DELETE methods, you must provide extra authentication, as well as a user name and password. This extra authentication is provided by the ibm-mq-rest-csrf-token HTTP header. The required contents of this header varies depending on the version of IBM MQ. For Version 9.0.4 and earlier, the value of the header is taken from a CSRF token cookie. To obtain this cookie you need to perform the following procedure:
    1. Generate a CSRF token cookie by submitting an HTTP GET request on the login REST API resource. Use the basic user name and password authentication that is outlined in this procedure to authenticate the request.
    2. Put the contents of the CSRF token cookie, csrfToken, that is returned by the request in an extra HTTP header as the header value. The header must be called ibm-mq-rest-csrf-token.

      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.

    From Version 9.0.5, The ibm-mq-rest-csrf-token HTTP header needs to be present in the request; its value can be anything including blank.
  5. Submit your REST request to IBM MQ with the appropriate headers.


Example

The following example shows how to create a new queue Q1, on queue manager QM1, with basic authentication, on Windows systems. The example uses cURL:

  • From Version 9.0.5, we only need to issue a single HTTP request. Use the HTTP POST method with the queue resource, authenticating with basic authentication and including the ibm-mq-rest-csrf-token HTTP header with an arbitrary value. This value can be anything, or blank; it is not checked by the mqweb server. 
    curl -k https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/queue -X POST
-u mqadmin:mqadmin
-H "ibm-mq-rest-csrf-token: value"
-H "Content-Type: application/json" --data "{\"name\":\"Q1\"}"
  • For Version 9.0.4 and earlier two HTTP requests are needed:
    1. The first request generates the CSRF token cookie.Use the HTTP GET method with the login resource, authenticating with basic authentication. The CSRF token that is returned is stored within the cookiejar.txt file. The -u flag specifies the user name and password. The -c flag specifies the location of the file to store the token in:
      curl -k https://localhost:9443/ibmmq/rest/v1/login -u admin:admin -c c:\cookiejar.txt
    2. The second request creates the queue.

      Use the HTTP POST method with the queue resource, authenticating with basic authentication and including the contents of the CSRF token in a header:

      Version 9.0.3 and earlier: 
      curl -k https://localhost:9443/ibmmq/rest/v1/qmgr/QM1/queue -X POST -u admin:admin 
-H "ibm-mq-rest-csrf-token: 83F1817976A6E6F1E980F9F09D7E8A161DC9D9867A634497CE03667B2AF5532B5
E6F9314E40B4FB31E00A2885E07150C0FD06FFB07B46FD4A5D2DA4C239C2D82C3C87588C8850B975892E1AF96034F
05F41699A7A1D36DEC048CE18F49A195BB762020D420EB628568D30120F12538B53D3F91939EF8851863EC7B87B6E
B0F95B57B6AB68B61D4324FAA3DFDE05AC956556736F8A9CA5BAF89BC2174B0EF5CE04E65646626F788F1CE2284EF
1562868C5A800B8BF4BFB8FB6C3FCD194EA6EB2FF43A3CFB57CCF9F5EF76F0E724FAB645B8E14CD3D9484BF799B3B
090CCD67B6CE8C8DAB552018A538903B0CD0B9FD747F2F4C18A80A65A2C3AE2A0D631B298AF" 
-H "Content-Type: application/json" --data "{\"name\":\"Q1\"}"