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 starting

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

On all other operating systems, we must be a privileged user to edit the mqwebuser.xml file.
Ensure that we are using a secure connection when you send REST requests. As the user name and password combination are encoded, but not encrypted, we 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 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 we use HTTP POST, PATCH, or DELETE methods, we 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\"}"
```

Parent topic: IBM MQ Console and REST API security