Using 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 Configuring 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>
```
On z/OS®, you must be a user that has write access to mqwebuser.xml to edit this file.

On all other operating systems, 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 you use HTTP basic 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 basic authentication information 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

Concatenate the user name with a colon, and the password. Note that the user name is case-sensitive.
For example, a user name of admin, and a password of admin becomes the following string:
```
admin:admin
```
Encode this user name and password string in base64 encoding.
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=
```
When you 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 ibm-mq-rest-csrf-token HTTP header must be present in the request, but its value can be anything, including blank.
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:

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, including blank:
```
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\"}"
```