Amazon MQ

Synopsis

The amazonmq device type consumes a queue of an Amazon MQ broker, of either engine: RabbitMQ or ActiveMQ. It is the RabbitMQ device with Amazon MQ's rules on top: every key of that device keeps its meaning, and the keys on this page are added or constrained. The device dials out to the broker and binds no port. Its records carry definition id 849.

What it adds to the RabbitMQ device:

• engine is required, and decides the protocol: activemq speaks AMQP 1.0 alone.
• TLS is always on, on port 5671, and the broker's certificate is checked by default.
• address names one broker, or the two brokers of an active/standby pair.
• On the RabbitMQ engine, the device can sign in with an IAM token or an OAuth 2.0 token, renewed before it expires, or with a client certificate.

note

The rabbitmq and AMQP devices still reach Amazon MQ brokers, and are unchanged, including their tls.insecure_skip_verify default. Use amazonmq for the engine checks, the certificate check by default, and IAM or OAuth 2.0 sign-in.

Schema

- id: <numeric>
  name: <string>
  description: <string>
  type: amazonmq
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    engine: <string>
    address: <string | string[]>
    protocol: <string>
    port: <numeric>
    vhost: <string>
    authentication: <string>
    username: <string>
    password: <string>
    region: <string>
    iam_audience: <string>
    key: <string>
    secret: <string>
    session: <string>
    role_arn: <string>
    external_id: <string>
    token_url: <string>
    client_id: <string>
    client_secret: <string>
    scope: <string>
    audience: <string>
    queue:
      name: <string>
    tls:
      cert_name: <string>
      key_name: <string>
      ca_name: <string>
      insecure_skip_verify: <boolean>

Every other key of the RabbitMQ device (exchange.*, the rest of queue.*, selector, prefetch_count, workers, reuse, max_buffer_size, content_encoding, the timeouts, and the rest of tls.*) applies with the same meaning.

Configuration

The following fields are used to define the device:

Device

Field	Required	Default	Description
id	Y	-	Unique numeric identifier
name	Y	-	Device name
description	N	-	Optional description
type	Y	-	Must be amazonmq
pipelines	N	-	Optional pre-processor pipelines
status	N	true	Enable/disable the device

Connection

Field	Required	Default	Description
engine	Y	-	The engine of the Amazon MQ broker: rabbitmq or activemq
protocol	N	0-9-1 on rabbitmq, 1.0 on activemq	On rabbitmq: 0-9-1 or 1.0. On activemq: always 1.0, and 0-9-1 is a Configuration error
address	Y	-	One broker host, or the two hosts of an active/standby broker, separated by a comma. More than two is refused
port	N	5671	Port of every broker that has none of its own
vhost	N	/	The virtual host

An activemq broker with protocol: "0-9-1" is refused when the configuration is read, rather than failing to connect. Under protocol: "1.0", the keys mean what the Protocol section of RabbitMQ says.

Authentication

Field	Required	Default	Description
authentication	N	plain	plain, or on the rabbitmq engine only: iam, oauth2 or external. iam, oauth2 and external on activemq are refused, and the error says why
username	Y for plain	-	The user. Under plain a missing username is refused: Amazon MQ signs in no anonymous user
password	Y for plain	-	The user's password

authentication	Signs in with
plain	username and password
iam	A token of IAM's, through STS's GetWebIdentityToken (IAM outbound federation). See IAM
oauth2	A token of an OAuth 2.0 identity provider, through the client credentials grant. See OAuth 2.0
external	The TLS client certificate, which is then required: set tls.cert_name and tls.key_name. The broker must be set up for it. See Prerequisites for Client Certificates

Under iam and oauth2, the token is the password and the username is empty (SASL PLAIN). Any username or password set on the device is ignored.

IAM

Used under authentication: iam.

Field	Required	Default	Description
region	Y	-	The AWS region whose STS issues the token
iam_audience	Y	-	The audience of the token, as the broker's IAM settings name it
key	N	-	AWS access key ID. Without key, secret and session, the default chain is used: the instance profile, IRSA, or the environment
secret	N	-	AWS secret access key
session	N	-	AWS session token, for temporary credentials
role_arn	N	-	A role assumed through sts:AssumeRole first. The token is then asked for as that role
external_id	N	-	The external ID sent with the assumed role. Needs role_arn

OAuth 2.0

Used under authentication: oauth2.

Field	Required	Default	Description
token_url	Y	-	The identity provider's token endpoint. https:// only
client_id	Y	-	The client of the client credentials grant
client_secret	Y	-	The client's secret. Takes a $secret{…} reference
scope	N	-	Scopes, separated by spaces
audience	N	-	Sent as the audience form parameter

key, secret, session, external_id and client_secret take text, ${ENV_VAR} or $secret{…}, resolved each time a token is asked for.

TLS

TLS is always on. Every tls.* key of the RabbitMQ device applies, with these differences:

Field	Required	Default	Description
tls.status	N	always on	tls.status: false is a Configuration error
tls.insecure_skip_verify	N	false	Skip broker certificate verification. Turning it on logs a warning at start

warning

This device checks the broker's certificate by default. The rabbitmq and amqp devices default tls.insecure_skip_verify to true, and do not. Amazon MQ presents a publicly issued certificate, so the host trust store verifies it with no tls.ca_name.

Operation

Token Renewal

Under iam and oauth2, the token is renewed at 80% of its lifetime, without dropping the connection. The lifetime is read from the token answer's expiry, or from the JWT's exp claim.

Protocol	Renewal
AMQP 0-9-1	update-secret on the connection
AMQP 1.0	PUT /auth/tokens on RabbitMQ 4's management node

If the broker refuses the in-place update, the connection is opened again with a fresh token. If no token can be obtained, the device shows Authentication error. It never keeps an expired token and stalls.

Prerequisites for IAM

• Amazon MQ for RabbitMQ 3.13, or 4.2 and later, with OAuth 2.0 / IAM configured on the broker, taking the token's audience (iam_audience).
• IAM outbound federation enabled on the AWS account.

Neither is configured by the device. When the broker refuses an iam or oauth2 login, the device's error names these requirements.

Prerequisites for Client Certificates

Under authentication: external, the device signs in with SASL EXTERNAL: it presents the TLS client certificate and sends no username, and the broker reads the user from the certificate. Setting tls.cert_name and tls.key_name is not enough on its own. The broker must also be set up for certificate sign-in:

• Amazon MQ for RabbitMQ 4 or later. Amazon MQ offers SSL certificate authentication on version 4 and later only, so a RabbitMQ 3.13 broker refuses external.
• The broker's configuration offers the EXTERNAL mechanism (auth_mechanisms.1 = EXTERNAL) and names the certificate field the username is read from (ssl_cert_login_from, for example common_name).
• The broker trusts the certificate authority that signed the client certificate: aws.arns.ssl_options.cacertfile names the CA certificate's ARN, and aws.arns.assume_role_arn the role the broker reads it with. That role is the broker's, not the device's.
• A broker user with the name read from the certificate, with permissions on the vhost.

None of these is configured by the device.

IAM Permissions

Only authentication: iam calls AWS. plain, oauth2 and external need no IAM permission.

The identity the token is asked for as needs sts:GetWebIdentityToken. That identity is the static key, the default chain's, or role_arn when it is set:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AmazonMQWebIdentityToken",
      "Effect": "Allow",
      "Action": "sts:GetWebIdentityToken",
      "Resource": "*"
    }
  ]
}

With role_arn, the calling identity also needs:

{
  "Sid": "AmazonMQAssumeRole",
  "Effect": "Allow",
  "Action": "sts:AssumeRole",
  "Resource": "arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME"
}

Active/Standby Brokers

With two hosts in address, each connect tries them in turn, as the RabbitMQ device does with the brokers of a cluster. A refused user ends the attempt, since the other broker of the pair refuses the same.

Examples

ActiveMQ Active/Standby

Consuming an Amazon MQ for ActiveMQ active/standby broker over AMQP 1.0, the engine's protocol, with a username and a password...

- id: 1 name: orders_activemq type: amazonmq properties: engine: activemq address: "b-1234-1.mq.eu-west-1.amazonaws.com,b-1234-2.mq.eu-west-1.amazonaws.com" authentication: plain username: "collector" password: "${AMAZONMQ_PASSWORD}" queue: name: "orders"

RabbitMQ with IAM

Consuming an Amazon MQ for RabbitMQ broker with an IAM token, asked for through a role the default chain's identity assumes first...

- id: 2 name: orders_rabbitmq_iam type: amazonmq properties: engine: rabbitmq address: "b-5678.mq.eu-west-1.amazonaws.com" authentication: iam region: "eu-west-1" iam_audience: "rabbitmq" role_arn: "arn:aws:iam::123456789012:role/amazonmq-consumer" queue: name: "orders" durable: true

RabbitMQ over AMQP 1.0 with OAuth 2.0

Consuming an Amazon MQ for RabbitMQ broker over AMQP 1.0, signed in with a token of an identity provider's client credentials grant...

- id: 3 name: orders_rabbitmq_oauth2 type: amazonmq properties: engine: rabbitmq protocol: "1.0" address: "b-5678.mq.eu-west-1.amazonaws.com" authentication: oauth2 token_url: "https://idp.example.com/oauth2/token" client_id: "virtualmetric" client_secret: "$secret{amazonmq-client-secret}" scope: "rabbitmq.read:*/orders" audience: "rabbitmq" queue: name: "/queues/orders"