Configuring IAM Users for IBM® MQ as a Service

This topics tell you how to configure IAM users.

Attention: This guide applies to managing users for the IBM® MQ as a Service Reserved Deployment Service plan only and is only available in limited regions.

Note: The following points apply to managing IAM users for IBM MQ as a Service:

To manage a user who has already been added to the IBM MQ service instance, first remove them from the User credentials tab before re-adding them by assigning an access policy in IAM.
IAM users with pending invites need to accept the invitation before they can be assigned access to IBM MQ.
It might take a few minutes for changes in access to be reflected in the IBM MQ service instance.

Use case

The following guide shows how an IBM MQ as a Service administrator can create and manage user permissions by using Service IDs and Access Groups rather than by using IBM MQ as a Service directly. This method allows for better separation of duties for the users of your IBM MQ as a Service service instance and gives a central location to manage users through IAM instead of through individual Queue Managers.

Creating and managing users in IAM

You require necessary permissions for creating and managing Service IDs and Access Groups. For more details on managing IAM users, see Managing users in an account

Create a new Service ID, or use an existing one
Create a new Access Group
- Add the Service ID you created to the Access Group under the Service IDs tab
Under the Access tab of this new Access Group, assign a new access:
- Service should be MQ
- Resources should be scoped accordingly; available scopes include your Account, Region, Reserved Deployment Service or Resource Group. For example, scoping to a specific Reserved Deployment Service:
  - Attribute: Service Instance
  - Operator: string equals
  - Value: Your Service Instance CRN
- Roles and Actions should be scoped based on your specific needs:
  - Writer grants messaging-level access (the ability to put and get messages to Queue Managers)
  - Manager grants full admin access to the IBM MQ as a Service Queue Managers (full administration access, ability to create Queues etc)
After creating this new Access Group, check the IAM Managed Credentials tab on the Manage page of your Reserved Deployment Instance. You should be able to see the Service ID you created.

Get a list of users with short names

To retrieve a list of users (including their short names) for a Service Instance, you can make a GET request to the Users API.

Prerequisites

You must have a valid IAM Access Token. This is <IAM_TOKEN> in the example command.
You must set up authentication for the MQ SaaS APIs.
You need the Service Instance GUID for your Reserved Deployment instance. This is <SERVICE_INSTANCE_GUID> in the example command.

Determine the correct base url for your Service Instance based on its region. This is <BASE_URL> in the example command.

$ curl -X GET --location --header "Authorization: Bearer <IAM_TOKEN>" --header "Accept: application/json" "<BASE_URL>/v1/<SERVICE_INSTANCE_GUID>/users"

An example response for the above command is:

{
  "offset": 0,
  "limit": 25,
  "first": {
    "href": "https://api.private.eu-de.mq2.cloud.ibm.com/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/users?limit=25"
  },
  "users": [
    {
      "id": "8414515e99e16c988f",
      "name": "testuser",
      "email": "NOT APPLICABLE",
      "iam_service_id": "iam-ServiceId-6c213316-ca90-45g1-84c6-9bcf0e06a636",
      "href": "https://api.private.eu-de.mq2.cloud.ibm.com/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/users/31a413dd84346effd8895b6ba4641641"
    }
  ]
}

Update a user’s short name

After creating the Access Group, your Service ID will have been added to your Reserved Deployment Instance with an auto-generated shortname. You can update the shortname if required by sending a PATCH request to the Users API.

Prerequisites

You must have a valid IAM Access Token. This is IAM_TOKEN in the example command.
You must set up authentication for the IBM MQ as a service APIs
You need the Service Instance GUID for the relevant Reserved Deployment instance. This is <SERVICE_INSTANCE_GUID> in the example command.
Determine the correct base url for your Service Instance. This is <BASE_URL> in the example command.
Determine the User ID for the user you want to update, this can be retrieved by the API call in the previous stage of these instuctions. This is <USER_ID> in the example command.

The new short name must be:

lowercase
1–12 characters
match the regex: ^[a-z][-a-z0-9]\*$
unique across your Reserved Deployment instances

$ curl -X PATCH --location --header "Authorization: Bearer <IAM_TOKEN>" --header "Accept: application/json" --header "Content-Type: application/json" "<BASE_URL>/v1/<SERVICE_INSTANCE_GUID>/users/<USER_ID>"  --data '{ "name": "<NEW_NAME>" }'

Updating a user's short name using the Terraform Module

You can also manage users using the IBM MQ as a Service Terraform Module. Instructions on how to set up the provider can be found here.

After setting up and authenticating the provider, create a main.tf file with an empty user block:
```
$ resource "ibm_mqcloud_user" "user1" {

}
```
Import a user to your terraform instance using terraform import, retrieving the Service Instance GUID and User ID in the same way as for the API instructions above:
```
$ terraform import  "ibm_mqcloud_user"."user1" ${service_instance_guid}/${user_id}
```

Update the terraform state file to include the imported users details as per details here:

$ resource "ibm_mqcloud_user" "user1" {
  name = "testuser"
  service_instance_guid = "8f3390a1-0de1-45e9-a3ad-31f1678244ac"
}

Update the value of name and run terraform apply.
The name of the user is updated.

Configuring authority for each User/Certificate

Once you have a User configured in your Queue Manager using any of the methods above, you can create a certificate for each user or application you want to connect.

For example, the following SSLPEER maps a certificate with a common name of application1 and an organizational unit (OU) of team1 to user user1. In addition to the SSLPEER, you should also specify SSLCERTI to be very specific about the issuer of the certificate. The MCAUSER is the user name that you have created in IAM with IBM MQ as a Service access.

SET CHLAUTH('MTLS.SVRCONN') TYPE(SSLPEERMAP) SSLPEER('CN=application1,OU=team1') SSLCERTI('CN=applicationCA,OU=Certificate Authority') USERSRC(MAP) MCAUSER('user1') ACTION(REPLACE)

For more information on using custom certificates, see Queue manager certificate administration.