Chapter 8. Reference

8.1. Custom Resource configuration reference

A Custom Resource Definition (CRD) is a schema of configuration items for a custom OpenShift object deployed with an Operator. By deploying a corresponding Custom Resource (CR) instance, you specify values for configuration items shown in the CRD.

The following sub-sections detail the configuration items that you can set in Custom Resource instances based on the main broker CRD.

8.1.1. Broker Custom Resource configuration reference

A CR instance based on the main broker CRD enables you to configure brokers for deployment in an OpenShift project. The following table describes the items that you can configure in the CR instance.

Important

Configuration items marked with an asterisk (*) are required in any corresponding Custom Resource (CR) that you deploy. If you do not explicitly specify a value for a non-required item, the configuration uses the default value.

Table 8.1. Broker CR reference
Entry	Sub-entry	Description and usage
`adminUser*`		Administrator user name required for connecting to the broker and management console. If you do not specify a value, the value is automatically generated and stored in a secret. The default secret name has a format of `<custom_resource_name>-credentials-secret`. For example, `my-broker-deployment-credentials-secret`. Type: string Example: my-user Default value: Automatically-generated, random value
`adminPassword*`		Administrator password required for connecting to the broker and management console. If you do not specify a value, the value is automatically generated and stored in a secret. The default secret name has a format of `<custom_resource_name>-credentials-secret`. For example, `my-broker-deployment-credentials-secret`. Type: string Example: my-password Default value: Automatically-generated, random value
`ingressDomain`		Append a custom domain to the host name in routes and ingresses that are created for acceptors, connectors and the management console. Type: string Example: mydomain.com
`deploymentPlan*`		Broker deployment configuration
	`image*`	Full path of the broker container image used for each broker in the deployment. You do not need to explicitly specify a value for `image` in your CR. The default value of `placeholder` indicates that the Operator has not yet determined the appropriate image to use. To learn how the Operator chooses a broker container image to use, see Section 2.7, “How the Operator chooses container images”. Type: string Example: registry.redhat.io/amq7/amq-broker-rhel8@sha256:55ae4e28b100534d63c34ab86f69230d274c999d46d1493f26fe3e75ba7a0cec Default value: placeholder
	`size*`	Number of broker Pods to create in the deployment. If you specify a value of 2 or greater, your broker deployment is clustered by default. The cluster user name and password are automatically generated and stored in the same secret as `adminUser` and `adminPassword`, by default. Type: int Example: 1 Default value: 1
	`requireLogin`	Specify whether login credentials are required to connect to the broker. Type: Boolean Example: false Default value: true
	`persistenceEnabled`	Specify whether to use journal storage for each broker Pod in the deployment. If set to `true`, each broker Pod requires an available Persistent Volume (PV) that the Operator can claim using a Persistent Volume Claim (PVC). Type: Boolean Example: false Default value: true
	`initImage`	Init Container image used to configure the broker. You do not need to explicitly specify a value for `initImage` in your CR, unless you want to provide a custom image. To learn how the Operator chooses a built-in Init Container image to use, see Section 2.7, “How the Operator chooses container images”. To learn how to specify a custom Init Container image, see Section 4.11, “Specifying a custom Init Container image”. Type: string Example: registry.redhat.io/amq7/amq-broker-init-rhel8@sha256:442339c33549f2be9fe3b5c71184a753a3cf10b000b2ecc5bc9a062dd91c8def Default value: Not specified
	`journalType`	Specify whether to use asynchronous I/O (AIO) or non-blocking I/O (NIO). Type: string Example: aio Default value: nio
	`messageMigration`	When a broker Pod shuts down due to an intentional scaledown of the broker deployment, specify whether to migrate messages to another broker Pod that is still running in the broker cluster. Type: Boolean Example: false Default value: true
	`resources.limits.cpu`	Maximum amount of host-node CPU, in millicores, that each broker container running in a Pod in a deployment can consume. Type: string Example: "500m" Default value: Uses the same default value that your version of OpenShift Container Platform uses. Consult a cluster administrator.
	`resources.limits.memory`	Maximum amount of host-node memory, in bytes, that each broker container running in a Pod in a deployment can consume. Supports byte notation (for example, K, M, G), or the binary equivalents (Ki, Mi, Gi). Type: string Example: "1024M" Default value: Uses the same default value that your version of OpenShift Container Platform uses. Consult a cluster administrator.
	`resources.requests.cpu`	Amount of host-node CPU, in millicores, that each broker container running in a Pod in a deployment explicitly requests. Type: string Example: "250m" Default value: Uses the same default value that your version of OpenShift Container Platform uses. Consult a cluster administrator.
	`resources.requests.memory`	Amount of host-node memory, in bytes, that each broker container running in a Pod in a deployment explicitly requests. Supports byte notation (for example, K, M, G), or the binary equivalents (Ki, Mi, Gi). Type: string Example: "512M" Default value: Uses the same default value that your version of OpenShift Container Platform uses. Consult a cluster administrator.
	`storage.size`	Size, in bytes, of the Persistent Volume Claim (PVC) that each broker in a deployment requires for persistent storage. This property applies only when `persistenceEnabled` is set to `true`. The value that you specify must include a unit. Supports byte notation (for example, K, M, G), or the binary equivalents (Ki, Mi, Gi). Type: string Example: 4Gi Default value: 2Gi
	`jolokiaAgentEnabled`	Specifies whether the Jolokia JVM Agent is enabled for the brokers in the deployment. If the value of this property is set to `true`, Fuse Console can discover and display runtime data for the brokers. Type: Boolean Example: true Default value: false
	`managementRBACEnabled`	Specifies whether role-based access control (RBAC) is enabled for the brokers in the deployment. To use Fuse Console, you must set the value to `false`, because Fuse Console uses its own role-based access control. Type: Boolean Example: false Default value: true
	`affinity`	Specifies scheduling constraints for pods. For information about affinity properties, see the properties in the OpenShift Container Platform documentation.
	`tolerations`	Specifies the pod’s tolerations. For information about tolerations properties, see the properties in the OpenShift Container Platform documentation.
	`nodeSelector`	Specify a label that matches a node’s labels for the pod to be scheduled on that node.
	`storageClassName`	Specifies the name of the storage class to use for the Persistent Volume Claim (PVC). Storage classes provide a way for administrators to describe and classify the available storage. For example, a storage class might have specific quality-of-service levels, backup policies, or other administrative policies associated with it. Type: string Example: gp3 Default value: Not specified
	`startupProbe`	Configure a startup probe to check if the AMQ Broker application within the broker container has started. For information about startup probe properties, see the properties in the OpenShift Container Platform documentation.
	`livenessProbe`	Configures a periodic health check on a running broker container to check that the broker is running. For information about liveness probe properties, see the properties in the OpenShift Container Platform documentation.
	`readinessProbe`	Configures a periodic health check on a running broker container to check that the broker is accepting network traffic. For information about readiness probe properties, see the properties in the OpenShift Container Platform documentation.
	`extraMounts`	Mounts a secret or configMAP, that contains configuration information, as a file on a broker Pod. For example, you can mount a secret that contains customized logging configuration for AMQ Broker. Type: object Example See Section 4.18, “Configuring logging for brokers” Default value: Not specified
	`labels`	Assign labels to a broker pod. Type: string Example: location: "production" Default value: Not specified
	`podSecurityContext`	Defines the security options used to run the broker pods. The following default security values allow the broker pods to run on a OpenShift Container Platform restricted security context constraint (SCC): `runAsNonRoot`: `true` `seccompProfile`: `type:RuntimeDefault` If you want the broker to run on a custom SCC, you can configure the following `podSecurityContext` options in the CR. If you configure any `podSecurityContext` option in the CR, none of the defaults apply, so you must configure all the options that are required to run under the custom SCC. `fsGroup` `fsGroupChangePolicy` `runAsGroup` `runAsUser` `runAsNonRoot` `seLinuxOptions` `seccompProfile` `supplementalGroups` `sysctls` `windowsOptions` For information on the `podSecurityContext` options, see the properties in the OpenShift Container Platform documentation.
	`containerSecurityContext`	Defines the security options used to run the broker containers in the pods. With the following default values, the containers run on a OpenShift Container Platform restricted security context constraint (SCC): `allowPrivilegeEscalation`: `false` `capabilities`: `drop:ALL` `runAsNonRoot`: `true` `seccompProfile`: `type:RuntimeDefault` If you want the broker to run on a custom SCC, you can configure the following `containerSecurityContext` options in the CR. If you configure any `containerSecurityContext` option in the CR, none of the defaults apply, so you must configure all the options that are required to run under the custom SCC. `allowPrivilegeEscalation` `capabilities` `privileged` `procMount` `readOnlyRootFilesystem` `runAsGroup` `runAsNonRoot` `runAsUser` `seLinuxOptions` `seccompProfile` `windowsOptions` For information on the `containerSecurityContext` options, see the properties in the OpenShift Container Platform documentation.
	`podSecurity.serviceAccountName`	Specify a service account name for the broker pod. Type: string Example: amq-broker-controller-manager Default value: default
`console`		Configuration of broker management console.
	`expose`	Specify whether to expose the management console to clients outside OpenShift Container Platform. Type: Boolean Example: true Default value: false
	`exposeMode`	Specify whether to expose the management console by using a route or an ingress. By default, the management console is exposed by using a route only. Type: String Example: ingress Default value: route If you expose the console by using an ingress, you must specify an `ingressHost` or an `ingressDomain` value in the CR.
	`ingressHost`	Specify a custom host value for routes and ingresses exposed for the management console. You can include any the following variables in the host value: * $(CR_NAME) - The value of the `metadata.name` attribute in the CR. * $(CR_NAMESPACE) - The namespace of the custom resource. * $(BROKER_ORDINAL) - The ordinal number assigned to the broker pod by the StatefulSet. * $(ITEM_NAME) - The name of the console. The default name is `wconsj` * $(RES_TYPE) - The resource type. A route has a resource type of `rte`. An ingress has a resource type of `ing`. * $(INGRESS_DOMAIN) - The value of the `spec.ingressDomain` attribute if it is configured in the CR. Type: string Example: console-$(CR_NAME)-$(ITEM_NAME)-$(BROKER_ORDINAL).mydomain.com
	`sslEnabled`	Specify whether to use SSL on the management console port. Type: Boolean Example: true Default value: false
	`sslSecret`	Secret where broker key store, trust store, and their corresponding passwords (all Base64-encoded) are stored. If you do not specify a value for `sslSecret`, the console uses a default secret name. The default secret name is in the form of `<custom_resource_name>-console-secret`. This property applies only when the `sslEnabled` property is set to `true`. Type: string Example: my-broker-deployment-console-secret Default value: Not specified
	`useClientAuth`	Specify whether the management console requires client authorization. Type: Boolean Example: true Default value: false
`acceptors.acceptor`		A single acceptor configuration instance.
	`name*`	Name of acceptor. Type: string Example: my-acceptor Default value: Not applicable
	`port`	Port number to use for the acceptor instance. Type: int Example: 5672 Default value: 61626 for the first acceptor that you define. The default value then increments by 10 for every subsequent acceptor that you define.
	`protocols`	Messaging protocols to be enabled on the acceptor instance. Type: string Example: amqp,core Default value: all
	`sslEnabled`	Specify whether SSL is enabled on the acceptor port. If set to `true`, look in the secret name specified in `sslSecret` for the credentials required by TLS/SSL. Type: Boolean Example: true Default value: false
	`sslSecret`	Secret where broker key store, trust store, and their corresponding passwords (all Base64-encoded) are stored. If you do not specify a custom secret name for `sslSecret`, the acceptor assumes a default secret name. The default secret name has a format of `<custom_resource_name>-<acceptor_name>-secret`. You must always create this secret yourself, even when the acceptor assumes a default name. Type: string Example: my-broker-deployment-my-acceptor-secret Default value: <custom_resource_name>-<acceptor_name>-secret
	`enabledCipherSuites`	Comma-separated list of cipher suites to use for TLS communication. Specify the most secure cipher suite(s) supported by your client application. If you specify a comma-separated list of cipher suites that are common to both the broker and the client, or you do not specify any cipher suites, the broker and client mutually negotiate a cipher suite to use. If you do not know which cipher suites to specify, you can first establish a broker-client connection with your client running in debug mode to verify the cipher suites that are common to both the broker and the client. Then, configure `enabledCipherSuites` on the broker. The cipher suites available depend on the TLS protocol versions used by the broker and clients. If the default TLS protocol version changes after you upgrade the broker, you might need to select an earlier TLS protocol version to ensure that the broker and the clients can use a common cipher suite. For more information, see `enabledProtocols`. Type: string Default value: Not specified
	`enabledProtocols`	Comma-separated list of protocols to use for TLS communication. Type: string Example: TLSv1,TLSv1.1,TLSv1.2 Default value: Not specified If you don’t specify a TLS protocol version, the broker uses the JVM’s default version. If the broker uses the JVM’s default TLS protocol version and that version changes after you upgrade the broker, the TLS protocol versions used by the broker and clients might be incompatible. While it is recommended that you use the later TLS protocol version, you can specify an earlier version in `enabledProtocols` to interoperate with clients that do not support a newer TLS protocol version.
	`keyStoreProvider`	The name of the provider of the keystore that the broker uses. Type: string Example: SunJCE Default value: Not specified
	`trustStoreProvider`	The name of the provider of the truststore that the broker uses. Type: string Example: SunJCE Default value: Not specified
	`trustStoreType`	The type of truststore that the broker uses. Type: string Example: JCEKS Default value: JKS
	`needClientAuth`	Specify whether the broker informs clients that two-way TLS is required on the acceptor. This property overrides `wantClientAuth`. Type: Boolean Example: true Default value: Not specified
	`wantClientAuth`	Specify whether the broker informs clients that two-way TLS is requested on the acceptor, but not required. This property is overridden by `needClientAuth`. Type: Boolean Example: true Default value: Not specified
	`verifyHost`	Specify whether to compare the Common Name (CN) of a client’s certificate to its host name, to verify that they match. This option applies only when two-way TLS is used. Type: Boolean Example: true Default value: Not specified
	`sslProvider`	Specify whether the SSL provider is JDK or OPENSSL. Type: string Example: OPENSSL Default value: JDK
	`sniHost`	Regular expression to match against the `server_name` extension on incoming connections. If the names don’t match, connection to the acceptor is rejected. Type: string Example: some_regular_expression Default value: Not specified
	`expose`	Specify whether to expose the acceptor to clients outside OpenShift Container Platform. Type: Boolean Example: true Default value: false
	`exposeMode`	Specify whether to expose the acceptor by using a route or an ingress. By default, an acceptor is exposed using a route only. Type: String Example: ingress Default value: route If you expose a connector by using an ingress, you must include the `ingressHost` or the `ingressDomain` attribute in the CR.
	`ingressHost`	Specify a custom host value for routes and ingress exposed for the acceptor. You can include any of the following variables for the host: * $(CR_NAME) - The value of the `metadata.name` attribute in the CR. * $(CR_NAMESPACE) - The namespace of the custom resource. * $(BROKER_ORDINAL) - The ordinal number assigned to the broker pod by the StatefulSet. * $(ITEM_NAME) - The name of the acceptor. * $(RES_TYPE) - The resource type. A route has a resource type of `rte`. An ingress has a resource type of `ing`. * $(INGRESS_DOMAIN) - The value of the `spec.ingressDomain` attribute if it is configured in the CR. Type: string Example: my-acceptor-$(CR_NAME)-$(ITEM_NAME)-$(BROKER_ORDINAL).mydomain.com
	`anycastPrefix`	Prefix used by a client to specify that the `anycast` routing type should be used. Type: string Example: jms.queue Default value: Not specified
	`multicastPrefix`	Prefix used by a client to specify that the `multicast` routing type should be used. Type: string Example: /topic/ Default value: Not specified
	`connectionsAllowed`	Number of connections allowed on the acceptor. When this limit is reached, a DEBUG message is issued to the log, and the connection is refused. The type of client in use determines what happens when the connection is refused. Type: integer Example: 2 Default value: 0 (unlimited connections)
	`amqpMinLargeMessageSize`	Minimum message size, in bytes, required for the broker to handle an AMQP message as a large message. If the size of an AMQP message is equal or greater to this value, the broker stores the message in a large messages directory (`/opt/<custom_resource_name>/data/large-messages`, by default) on the persistent volume (PV) used by the broker for message storage. Setting the value to `-1` disables large message handling for AMQP messages. Type: integer Example: 204800 Default value: 102400 (100 KB)
	`BindToAllInterfaces`	If set to true, configures the broker acceptors with a 0.0.0.0 IP address instead of the internal IP address of the pod. When the broker acceptors have a 0.0.0.0 IP address, they bind to all interfaces configured for the pod and clients can direct traffic to the broker by using OpenShift Container Platform port-forwarding. Normally, you use this configuration to debug a service. For more information about port-forwarding, see Using port-forwarding to access applications in a container in the OpenShift Container Platform documentation. Note If port-forwarding is used incorrectly, it can create a security risk for your environment. Where possible, do not use port-forwarding in a production environment. Type: Boolean Example: true Default value: false
`connectors.connector`		A single connector configuration instance.
	`name*`	Name of connector. Type: string Example: my-connector Default value: Not applicable
	`type`	The type of connector to create; `tcp` or `vm`. Type: string Example: vm Default value: tcp
	`host*`	Host name or IP address to connect to. Type: string Example: 192.168.0.58 Default value: Not specified
	`port*`	Port number to be used for the connector instance. Type: int Example: 22222 Default value: Not specified
	`sslEnabled`	Specify whether SSL is enabled on the connector port. If set to `true`, look in the secret name specified in `sslSecret` for the credentials required by TLS/SSL. Type: Boolean Example: true Default value: false
	`sslSecret`	Secret where broker key store, trust store, and their corresponding passwords (all Base64-encoded) are stored. If you do not specify a custom secret name for `sslSecret`, the connector assumes a default secret name. The default secret name has a format of `<custom_resource_name>-<connector_name>-secret`. You must always create this secret yourself, even when the connector assumes a default name. Type: string Example: my-broker-deployment-my-connector-secret Default value: <custom_resource_name>-<connector_name>-secret
	`enabledCipherSuites`	Comma-separated list of cipher suites to use for TLS communication. Type: string NOTE: For a connector, it is recommended that you do not specify a list of cipher suites. Default value: Not specified
	`keyStoreProvider`	The name of the provider of the keystore that the broker uses. Type: string Example: SunJCE Default value: Not specified
	`trustStoreProvider`	The name of the provider of the truststore that the broker uses. Type: string Example: SunJCE Default value: Not specified
	`trustStoreType`	The type of truststore that the broker uses. Type: string Example: JCEKS Default value: JKS
	`enabledProtocols`	Comma-separated list of protocols to use for TLS communication. Type: string Example: TLSv1,TLSv1.1,TLSv1.2 Default value: Not specified
	`needClientAuth`	Specify whether the broker informs clients that two-way TLS is required on the connector. This property overrides `wantClientAuth`. Type: Boolean Example: true Default value: Not specified
	`wantClientAuth`	Specify whether the broker informs clients that two-way TLS is requested on the connector, but not required. This property is overridden by `needClientAuth`. Type: Boolean Example: true Default value: Not specified
	`verifyHost`	Specify whether to compare the Common Name (CN) of client’s certificate to its host name, to verify that they match. This option applies only when two-way TLS is used. Type: Boolean Example: true Default value: Not specified
	`sslProvider`	Specify whether the SSL provider is `JDK` or `OPENSSL`. Type: string Example: OPENSSL Default value: JDK
	`sniHost`	Regular expression to match against the `server_name` extension on outgoing connections. If the names don’t match, the connector connection is rejected. Type: string Example: some_regular_expression Default value: Not specified
	`expose`	Specify whether to expose the connector to clients outside OpenShift Container Platform. Type: Boolean Example: true Default value: false
	`exposeMode`	Specify whether to expose the connector by using a route or an ingress. By default, a connector is exposed using a route only. Type: string Example: ingress Default value: route If you expose a connector by using an ingress, you must include the `ingressHost` or the `ingressDomain` attribute in the CR.
	`ingressHost`	Specify a custom host value for routes and ingresses exposed for the connector. You can include any the following variables in the host value: * $(CR_NAME) - The value of the `metadata.name` attribute in the CR. * $(CR_NAMESPACE) - The namespace of the custom resource. * $(BROKER_ORDINAL) - The ordinal number assigned to the broker pod by the StatefulSet. * $(ITEM_NAME) - The name of the connector. * $(RES_TYPE) - The resource type. A route has a resource type of `rte`. An ingress has a resource type of `ing`. * $(INGRESS_DOMAIN) - The value of the `spec.ingressDomain` attribute if it is configured in the CR. Type: string Example: my-connector-$(CR_NAME)-$(ITEM_NAME)-$(BROKER_ORDINAL).$(INGRESS_DOMAIN).mydomain.com
`addressSettings.applyRule`		Specifies how the Operator applies the configuration that you add to the CR for each matching address or set of addresses. The values that you can specify are: `merge_all` For address settings specified in both the CR and the default configuration that match the same address or set of addresses: Replace any property values specified in the default configuration with those specified in the CR. Keep any property values that are specified uniquely in the CR or the default configuration. Include each of these in the final, merged configuration. For address settings specified in either the CR or the default configuration that uniquely match a particular address or set of addresses, include these in the final, merged configuration. `merge_replace` For address settings specified in both the CR and the default configuration that match the same address or set of addresses, include the settings specified in the CR in the final, merged configuration. Do not include any properties specified in the default configuration, even if these are not specified in the CR. + For address settings specified in either the CR or the default configuration that uniquely match a particular address or set of addresses, include these in the final, merged configuration. `replace_all` Replace all address settings specified in the default configuration with those specified in the CR. The final, megred configuration corresponds exactly to that specified in the CR. Type: string Example: replace_all Default value: merge_all
`addressSettings.addressSetting`		Address settings for a matching address or set of addresses.
	`addressFullPolicy`	Specify what happens when an address configured with `maxSizeBytes` becomes full. The available policies are: `PAGE` Messages sent to a full address are paged to disk. `DROP` Messages sent to a full address are silently dropped. `FAIL` Messages sent to a full address are dropped and the message producers receive an exception. `BLOCK` Message producers will block when they try to send any further messages. The BLOCK policy works only for AMQP, OpenWire, and Core Protocol, because those protocols support flow control. Type: string Example: DROP Default value: PAGE
	`autoCreateAddresses`	Specify whether the broker automatically creates an address when a client sends a message to, or attempts to consume a message from, a queue that is bound to an address that does not exist. Type: Boolean Example: false Default value: true
	`autoCreateDeadLetterResources`	Specify whether the broker automatically creates a dead letter address and queue to receive undelivered messages. If the parameter is set to `true`, the broker automatically creates a dead letter address and an associated dead letter queue. The name of the automatically-created address matches the value that you specify for `deadLetterAddress`. Type: Boolean Example: true Default value: false
	`autoCreateExpiryResources`	Specify whether the broker automatically creates an address and queue to receive expired messages. If the parameter is set to `true`, the broker automatically creates an expiry address and an associated expiry queue. The name of the automatically-created address matches the value that you specify for `expiryAddress`. Type: Boolean Example: true Default value: false
	`autoCreateJmsQueues`	This property is deprecated. Use `autoCreateQueues` instead.
	`autoCreateJmsTopics`	This property is deprecated. Use `autoCreateQueues` instead.
	`autoCreateQueues`	Specify whether the broker automatically creates a queue when a client sends a message to, or attempts to consume a message from, a queue that does not yet exist. Type: Boolean Example: false Default value: true
	`autoDeleteAddresses`	Specify whether the broker automatically deletes automatically-created addresses when the broker no longer has any queues. Type: Boolean Example: false Default value: true
	`autoDeleteAddressDelay`	Time, in milliseconds, that the broker waits before automatically deleting an automatically-created address when the address has no queues. Type: integer Example: 100 Default value: 0
	`autoDeleteJmsQueues`	This property is deprecated. Use `autoDeleteQueues` instead.
	`autoDeleteJmsTopics`	This property is deprecated. Use `autoDeleteQueues` instead.
	`autoDeleteQueues`	Specify whether the broker automatically deletes an automatically-created queue when the queue has no consumers and no messages. Type: Boolean Example: false Default value: true
	`autoDeleteCreatedQueues`	Specify whether the broker automatically deletes a manually-created queue when the queue has no consumers and no messages. Type: Boolean Example: true Default value: false
	`autoDeleteQueuesDelay`	Time, in milliseconds, that the broker waits before automatically deleting an automatically-created queue when the queue has no consumers. Type: integer Example: 10 Default value: 0
	`autoDeleteQueuesMessageCount`	Maximum number of messages that can be in a queue before the broker evaluates whether the queue can be automatically deleted. Type: integer Example: 5 Default value: 0
	`configDeleteAddresses`	When the configuration file is reloaded, this parameter specifies how to handle an address (and its queues) that has been deleted from the configuration file. You can specify the following values: `OFF` The broker does not delete the address when the configuration file is reloaded. `FORCE` The broker deletes the address and its queues when the configuration file is reloaded. If there are any messages in the queues, they are removed also. Type: string Example: FORCE Default value: OFF
	`configDeleteQueues`	When the configuration file is reloaded, this setting specifies how the broker handles queues that have been deleted from the configuration file. You can specify the following values: `OFF` The broker does not delete the queue when the configuration file is reloaded. `FORCE` The broker deletes the queue when the configuration file is reloaded. If there are any messages in the queue, they are removed also. Type: string Example: FORCE Default value: OFF
	`deadLetterAddress`	The address to which the broker sends dead (that is, undelivered) messages. Type: string Example: DLA Default value: None
	`deadLetterQueuePrefix`	Prefix that the broker applies to the name of an automatically-created dead letter queue. Type: string Example: myDLQ. Default value: DLQ.
	`deadLetterQueueSuffix`	Suffix that the broker applies to an automatically-created dead letter queue. Type: string Example: .DLQ Default value: None
	`defaultAddressRoutingType`	Routing type used on automatically-created addresses. Type: string Example: ANYCAST Default value: MULTICAST
	`defaultConsumersBeforeDispatch`	Number of consumers needed before message dispatch can begin for queues on an address. Type: integer Example: 5 Default value: 0
	`defaultConsumerWindowSize`	Default window size, in bytes, for a consumer. Type: integer Example: 300000 Default value: 1048576 (1024*1024)
	`defaultDelayBeforeDispatch`	Default time, in milliseconds, that the broker waits before dispatching messages if the value specified for `defaultConsumersBeforeDispatch` has not been reached. Type: integer Example: 5 Default value: -1 (no delay)
	`defaultExclusiveQueue`	Specifies whether all queues on an address are exclusive queues by default. Type: Boolean Example: true Default value: false
	`defaultGroupBuckets`	Number of buckets to use for message grouping. Type: integer Example: 0 (message grouping disabled) Default value: -1 (no limit)
	`defaultGroupFirstKey`	Key used to indicate to a consumer which message in a group is first. Type: string Example: firstMessageKey Default value: None
	`defaultGroupRebalance`	Specifies whether to rebalance groups when a new consumer connects to the broker. Type: Boolean Example: true Default value: false
	`defaultGroupRebalancePauseDispatch`	Specifies whether to pause message dispatch while the broker is rebalancing groups. Type: Boolean Example: true Default value: false
	`defaultLastValueQueue`	Specifies whether all queues on an address are last value queues by default. Type: Boolean Example: true Default value: false
	`defaultLastValueKey`	Default key to use for a last value queue. Type: string Example: stock_ticker Default value: None
	`defaultMaxConsumers`	Maximum number of consumers allowed on a queue at any time. Type: integer Example: 100 Default value: -1 (no limit)
	`defaultNonDestructive`	Specifies whether all queues on an address are non-destructive by default. Type: Boolean Example: true Default value: false
	`defaultPurgeOnNoConsumers`	Specifies whether the broker purges the contents of a queue once there are no consumers. Type: Boolean Example: true Default value: false
	`defaultQueueRoutingType`	Routing type used on automatically-created queues. The default value is `MULTICAST`. Type: string Example: ANYCAST Default value: MULTICAST
	`defaultRingSize`	Default ring size for a matching queue that does not have a ring size explicitly set. Type: integer Example: 3 Default value: -1 (no size limit)
	`enableMetrics`	Specifies whether a configured metrics plugin such as the Prometheus plugin collects metrics for a matching address or set of addresses. Type: Boolean Example: false Default value: true
	`expiryAddress`	Address that receives expired messages. Type: string Example: myExpiryAddress Default value: None
	`expiryDelay`	Expiration time, in milliseconds, applied to messages that are using the default expiration time. Type: integer Example: 100 Default value: -1 (no expiration time applied)
	`expiryQueuePrefix`	Prefix that the broker applies to the name of an automatically-created expiry queue. Type: string Example: myExp. Default value: EXP.
	`expiryQueueSuffix`	Suffix that the broker applies to the name of an automatically-created expiry queue. Type: string Example: .EXP Default value: None
	`lastValueQueue`	Specify whether a queue uses only last values or not. Type: Boolean Example: true Default value: false
	`managementBrowsePageSize`	Specify how many messages a management resource can browse. Type: integer Example: 100 Default value: 200
	`match`*	String that matches address settings to addresses configured on the broker. You can specify an exact address name or use a wildcard expression to match the address settings to a set of addresses. If you use a wildcard expression as a value for the `match` property, you must enclose the value in single quotation marks, for example, `'myAddresses'`. Type: string Example: 'myAddresses' Default value: None
	`maxDeliveryAttempts`	Specifies how many times the broker attempts to deliver a message before sending the message to the configured dead letter address. Type: integer Example: 20 Default value: 10
	`maxExpiryDelay`	Expiration time, in milliseconds, applied to messages that are using an expiration time greater than this value. Type: integer Example: 20 Default value: -1 (no maximum expiration time applied)
	`maxRedeliveryDelay`	Maximum value, in milliseconds, between message redelivery attempts made by the broker. Type: integer Example: 100 Default value: The default value is ten times the value of `redeliveryDelay`, which has a default value of `0`.
	`maxSizeBytes`	Maximum memory size, in bytes, for an address. Used when `addressFullPolicy` is set to `PAGING`, `BLOCK`, or `FAIL`. Also supports byte notation such as "K", "Mb", and "GB". Type: string Example: 10Mb Default value: -1 (no limit)
	`maxSizeBytesRejectThreshold`	Maximum size, in bytes, that an address can reach before the broker begins to reject messages. Used when the `address-full-policy` is set to `BLOCK`. Works in combination with `maxSizeBytes` for the AMQP protocol only. Type: integer Example: 500 Default value: -1 (no maximum size)
	`messageCounterHistoryDayLimit`	Number of days for which a broker keeps a message counter history for an address. Type: integer Example: 5 Default value: 0
	`minExpiryDelay`	Expiration time, in milliseconds, applied to messages that are using an expiration time lower than this value. Type: integer Example: 20 Default value: -1 (no minimum expiration time applied)
	`pageMaxCacheSize`	Number of page files to keep in memory to optimize I/O during paging navigation. Type: integer Example: 10 Default value: 5
	`pageSizeBytes`	Paging size in bytes. Also supports byte notation such as `K`, `Mb`, and `GB`. Type: string Example: 20971520 Default value: 10485760 (approximately 10.5 MB)
	`redeliveryDelay`	Time, in milliseconds, that the broker waits before redelivering a cancelled message. Type: integer Example: 100 Default value: 0
	`redistributionDelay`	Time, in milliseconds, that the broker waits after the last consumer is closed on a queue before redistributing any remaining messages. Type: integer Example: 100 Default value: -1 (not set)
	`retroactiveMessageCount`	Number of messages to keep for future queues created on an address. Type: integer Example: 100 Default value: 0
	`sendToDlaOnNoRoute`	Specify whether a message will be sent to the configured dead letter address if it cannot be routed to any queues. Type: Boolean Example: true Default value: false
	`slowConsumerCheckPeriod`	How often, in seconds, that the broker checks for slow consumers. Type: integer Example: 15 Default value: 5
	`slowConsumerPolicy`	Specifies what happens when a slow consumer is identified. Valid options are `KILL` or `NOTIFY`. `KILL` kills the consumer’s connection, which impacts any client threads using that same connection. `NOTIFY` sends a `CONSUMER_SLOW` management notification to the client. Type: string Example: KILL Default value: NOTIFY
	`slowConsumerThreshold`	Minimum rate of message consumption, in messages per second, before a consumer is considered slow. Type: integer Example: 100 Default value: -1 (not set)
`env`	`<variable name>=<value>`	Set environment variables for the broker. Type: array Example: name: TZ value: Europe/Vienna Default value: Not applicable
`brokerProperties`		Configure broker properties that are not exposed in the broker’s Custom Resource Definitions (CRDs) and are, otherwise, not configurable in a Custom Resource(CR).
	`<property name>=<value>`	A list of property names and values to configure for the broker. Type: string Example: globalMaxSize=512m Default value: Not applicable
`version`		Specify the version of the AMQ Broker container images that you want the Operator to deploy. For example, if you change the value of `version` from `7.11.1` to `7.12.0`, the Operator upgrades the broker images to 7.12.0. You can omit the micro and minor digits from the version number to automatically upgrade to the broker images that are available for the latest micro or minor release. For example, if you specify a version of `7.11`, the Operator upgrades to the images for the latest 7.11.x release. Or, if you specify a version of `7`, the Operator upgrades to the images for the latest 7.x.x release. Type: string Example: 7.12.3 Default value: Current version of AMQ Broker

8.1.2. Address Custom Resource configuration reference

A CR instance based on the address CRD enables you to define addresses and queues for the brokers in your deployment. The following table details the items that you can configure.

Important

Table 8.2. Address CR reference
Entry	Description and usage
`addressName*`	Address name to be created on broker. Type: string Example: address0 Default value: Not specified
`queueName`	Queue name to be created on broker. If `queueName` is not specified, the CR creates only the address. Type: string Example: queue0 Default value: Not specified
`removeFromBrokerOnDelete*`	Specify whether the Operator removes existing addresses for all brokers in a deployment when you remove the address CR instance for that deployment. The default value is `false`, which means the Operator does not delete existing addresses when you remove the CR. Type: Boolean Example: true Default value: false
`routingType*`	Routing type to be used; `anycast` or `multicast`. Type: string Example: anycast Default value: multicast

8.1.3. Security Custom Resource configuration reference

A CR instance based on the security CRD enables you to define the security configuration for the brokers in your deployment, including:

users and roles
login modules, including propertiesLoginModule, guestLoginModule and keycloakLoginModule
role based access control
console access control

Note

Many of the options require you understand the broker security concepts described in Securing brokers

The following table details the items that you can configure.

Important

Table 8.3. Security CR reference
Entry	Sub-entry	Description and usage
loginModules		One or more login module configurations. A login module can be one of the following types: `propertiesLoginModule` - allows you define broker users directly. `guestLoginModule` - for a user who does not have login credentials, or whose credentials fail authentication, you can grant limited access to the broker using a guest account. `keycloakLoginModule`. - allows you secure brokers using Red Hat Single Sign-On.
propertiesLoginModule	name*	Name of login module. Type: string Example: my-login Default value: Not applicable
	users.name*	Name of user. Type: string Example: jdoe Default value: Not applicable
	users.password*	password of user. Type: string Example: password Default value: Not applicable
	users.roles	Names of roles. Type: string Example: viewer Default value: Not applicable
guestLoginModule	name*	Name of guest login module. Type: string Example: guest-login Default value: Not applicable
	guestUser	Name of guest user. Type: string Example: myguest Default value: Not applicable
	guestRole	Name of role for guest user. Type: string Example: guest Default value: Not applicable
keycloakLoginModule	name	Name for KeycloakLoginModule Type: string Example: sso Default value: Not applicable
	moduleType	Type of KeycloakLoginModule (directAccess or bearerToken) Type: string Example: bearerToken Default value: Not applicable
	configuration	The following configuration items are related to Red Hat Single Sign-On and detailed information is available from the OpenID Connect documentation.
	configuration.realm*	Realm for KeycloakLoginModule Type: string Example: myrealm Default value: Not applicable
	configuration.realmPublicKey	Public key for the realm Type: string Default value: Not applicable
	configuration.authServerUrl*	URL of the keycloak authentication server Type: string Default value: Not applicable
	configuration.sslRequired	Specify whether SSL is required Type: string Valid values are 'all', 'external' and 'none'.
	configuration.resource*	Resource Name The client-id of the application. Each application has a client-id that is used to identify the application.
	configuration.publicClient	Specify whether it is public client. Type: Boolean Default value: false Example: false
	configuration.credentials.key	Specify the credentials key. Type: string Default value: Not applicable Type: string Default value: Not applicable
	configuration.credentials.value	Specify the credentials value Type: string Default value: Not applicable
	configuration.useResourceRoleMappings	Specify whether to use resource role mappings Type: Boolean Example: false
	configuration.enableCors	Specify whether to enable Cross-Origin Resource Sharing (CORS) It will handle CORS preflight requests. It will also look into the access token to determine valid origins. Type: Boolean Default value: false
	configuration.corsMaxAge	CORS max age If CORS is enabled, this sets the value of the Access-Control-Max-Age header.
	configuration.corsAllowedMethods	CORS allowed methods If CORS is enabled, this sets the value of the Access-Control-Allow-Methods header. This should be a comma-separated string.
	configuration.corsAllowedHeaders	CORS allowed headers If CORS is enabled, this sets the value of the Access-Control-Allow-Headers header. This should be a comma-separated string.
	configuration.corsExposedHeaders	CORS exposed headers If CORS is enabled, this sets the value of the Access-Control-Expose-Headers header. This should be a comma-separated string.
	configuration.exposeToken	Specify whether to expose access token Type: Boolean Default value: false
	configuration.bearerOnly	Specify whether to verify bearer token Type: Boolean Default value: false
	configuration.autoDetectBearerOnly	Specify whether to only auto-detect bearer token Type: Boolean Default value: false
	configuration.connectionPoolSize	Size of the connection pool Type: Integer Default value: 20
	configuration.allowAnyHostName	Specify whether to allow any host name Type: Boolean Default value: false
	configuration.disableTrustManager	Specify whether to disable trust manager Type: Boolean Default value: false
	configuration.trustStore*	Path of a trust store This is REQUIRED unless ssl-required is none or disable-trust-manager is true.
	configuration.trustStorePassword*	Truststore password This is REQUIRED if truststore is set and the truststore requires a password.
	configuration.clientKeyStore	Path of a client keystore Type: string Default value: Not applicable
	configuration.clientKeyStorePassword	Client keystore password Type: string Default value: Not applicable
	configuration.clientKeyPassword	Client key password Type: string Default value: Not applicable
	configuration.alwaysRefreshToken	Specify whether to always refresh token Type: Boolean Example: false
	configuration.registerNodeAtStartup	Specify whether to register node at startup Type: Boolean Example: false
	configuration.registerNodePeriod	Period for re-registering node Type: string Default value: Not applicable
	configuration.tokenStore	Type of token store (session or cookie) Type: string Default value: Not applicable
	configuration.tokenCookiePath	Cookie path for a cookie store Type: string Default value: Not applicable
	configuration.principalAttribute	OpenID Connect ID Token attribute to populate the UserPrincipal name with OpenID Connect ID Token attribute to populate the UserPrincipal name with. If token attribute is null, defaults to sub. Possible values are sub, preferred_username, email, name, nickname, given_name, family_name.
	configuration.proxyUrl	The proxy URL
	configuration.turnOffChangeSessionIdOnLogin	Specify whether to change session id on a successful login Type: Boolean Example: false
	configuration.tokenMinimumTimeToLive	Minimum time to refresh an active access token Type: Integer Default value: 0
	configuration.minTimeBetweenJwksRequests	Minimum interval between two requests to Keycloak to retrieve new public keys Type: Integer Default value: 10
	configuration.publicKeyCacheTtl	Maximum interval between two requests to Keycloak to retrieve new public keys Type: Integer Default value: 86400
	configuration.ignoreOauthQueryParameter	Whether to turn off processing of the access_token query parameter for bearer token processing Type: Boolean Example: false
	configuration.verifyTokenAudience	Verify whether the token contains this client name (resource) as an audience Type: Boolean Example: false
	configuration.enableBasicAuth	Whether to support basic authentication Type: Boolean Default value: false
	configuration.confidentialPort	The confidential port used by the Keycloak server for secure connections over SSL/TLS Type: Integer Example: 8443
	configuration.redirectRewriteRules.key	The regular expression used to match the Redirect URI. Type: string Default value: Not applicable
	configuration.redirectRewriteRules.value	The replacement String Type: string Default value: Not applicable
	configuration.scope	The OAuth2 scope parameter for DirectAccessGrantsLoginModule Type: string Default value: Not applicable
securityDomains		Broker security domains
	brokerDomain.name	Broker domain name Type: string Example: activemq Default value: Not applicable
	brokerDomain.loginModules	One or more login modules. Each entry must be previously defined in the `loginModules` section above.
	brokerDomain.loginModules.name	Name of login module Type: string Example: prop-module Default value: Not applicable
	brokerDomain.loginModules.flag	Same as propertiesLoginModule, `required`, `requisite`, `sufficient` and `optional` are valid values. Type: string Example: sufficient Default value: Not applicable
	brokerDomain.loginModules.debug	Debug
	brokerDomain.loginModules.reload	Reload
	consoleDomain.name	Broker domain name Type: string Example: activemq Default value: Not applicable
	consoleDomain.loginModules	A single login module configuration.
	consoleDomain.loginModules.name	Name of login module Type: string Example: prop-module Default value: Not applicable
	consoleDomain.loginModules.flag	Same as propertiesLoginModule, `required`, `requisite`, `sufficient` and `optional` are valid values. Type: string Example: sufficient Default value: Not applicable
	consoleDomain.loginModules.debug	Debug Type: Boolean Example: false
	consoleDomain.loginModules.reload	Reload Type: Boolean Example: true Default: false
securitySettings		Additional security settings to add to `broker.xml` or `management.xml`
	broker.match	The address match pattern for a security setting section. See AMQ Broker wildcard syntax for details about the match pattern syntax.
	broker.permissions.operationType	The operation type of a security setting, as described in Setting permissions. Type: string Example: createAddress Default value: Not applicable
	broker.permissions.roles	The security settings are applied to these roles, as described in Setting permissions. Type: string Example: root Default value: Not applicable
securitySettings.management		Options to configure `management.xml`.
	hawtioRoles	The roles allowed to log into the Broker console. Type: string Example: root Default value: Not applicable
	connector.host	The connector host for connecting to the management API. Type: string Example: myhost Default value: localhost
	connector.port	The connector port for connecting to the management API. Type: integer Example: 1099 Default value: 1099
	connector.jmxRealm	The JMX realm of the management API. Type: string Example: activemq Default value: activemq
	connector.objectName	The JMX object name of the management API. Type: String Example: connector:name=rmi Default: connector:name=rmi
	connector.authenticatorType	The management API authentication type. Type: String Example: password Default: password
	connector.secured	Whether the management API connection is secured. Type: Boolean Example: true Default value: false
	connector.keyStoreProvider	The keystore provider for the management connector. Required if you have set connector.secured="true". The default value is JKS.
	connector.keyStorePath	Location of the keystore. Required if you have set connector.secured="true".
	connector.keyStorePassword	The keystore password for the management connector. Required if you have set connector.secured="true".
	connector.trustStoreProvider	The truststore provider for the management connector Required if you have set connector.secured="true". Type: String Example: JKS Default: JKS
	connector.trustStorePath	Location of the truststore for the management connector. Required if you have set connector.secured="true". Type: string Default value: Not applicable
	connector.trustStorePassword	The truststore password for the management connector. Required if you have set connector.secured="true". Type: string Default value: Not applicable
	connector.passwordCodec	The password codec for management connector The fully qualified class name of the password codec to use as described in Encrypting a password in a configuration file.
	authorisation.allowedList.domain	The domain of allowedList Type: string Default value: Not applicable
	authorisation.allowedList.key	The key of allowedList Type: string Default value: Not applicable
	authorisation.defaultAccess.method	The method of defaultAccess List Type: string Default value: Not applicable
	authorisation.defaultAccess.roles	The roles of defaultAccess List Type: string Default value: Not applicable
	authorisation.roleAccess.domain	The domain of roleAccess List Type: string Default value: Not applicable
	authorisation.roleAccess.key	The key of roleAccess List Type: string Default value: Not applicable
	authorisation.roleAccess.accessList.method	The method of roleAccess List Type: string Default value: Not applicable
	authorisation.roleAccess.accessList.roles	The roles of roleAccess List Type: string Default value: Not applicable
	applyToCrNames	Apply this security config to the brokers defined by the named CRs in the current namespace. A value of * or empty string means applying to all brokers. Type: string Example: my-broker Default value: All brokers defined by CRs in the current namespace.

8.2. Example JAAS login module configurations

The following example shows a JAAS login module configuration that has both a properties login module and an LDAP login module configured. The properties login module references the default login module that contains the credentials used by the Operator to authenticate with the broker.

	activemq {
  		org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule required
     		debug=true
	   		initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
	    	connectionURL="LDAP://localhost:389"
	    	connectionUsername="CN=Administrator,CN=Users,OU=System,DC=example,DC=com"
	   		connectionPassword=redhat.123
	    	connectionProtocol=s
	    	connectionTimeout="5000"
	    	authentication=simple
     		userBase="dc=example,dc=com"
	    	userSearchMatching="(CN={0})"
    		userSearchSubtree=true
	    	readTimeout="5000"
     		roleBase="dc=example,dc=com"
     		roleName=cn
     		roleSearchMatching="(member={0})"
     		roleSearchSubtree=true;

		org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule
			reload=true
			org.apache.activemq.jaas.properties.user="artemis-users.properties"
			org.apache.activemq.jaas.properties.role="artemis-roles.properties"
			baseDir="/home/jboss/amq-broker/etc";
};

The following example shows a JAAS login module configuration that has two properties login modules in separate realms.

The default properties login module is in a realm named console and has the properties files that are used by the Operator and AMQ Management Console to authenticate with the broker.
The login module in the activemq realm has new properties files, which, for example, could contain the credentials to authenticate users for messaging.

You might want to create separate realms to, for example, apply specific security controls to the realm that contains the login module used by the Operator to authenticate with the broker.

activemq {
 	org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule
	 	reload=true
		org.apache.activemq.jaas.properties.user="new-users.properties"
		org.apache.activemq.jaas.properties.role="new-roles.properties"
};

console {
org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule
		reload=true
 		org.apache.activemq.jaas.properties.user="artemis-users.properties"
		org.apache.activemq.jaas.properties.role="artemis-roles.properties"
		baseDir="/home/jboss/amq-broker/etc";
};

Note

By default, AMQ Management Console uses the default properties login module in the activemq realm for authentication. If the default properties login module is configured in another realm, as in the example, you must set an environment variable in the broker CR to configure AMQ Management Console to use that realm. For example:

spec:
  ...
  env:
  - name: JAVA_ARGS_APPEND
    value: --Hawtio.realm=console
  ...

For more information about setting environment variables in a CR, see Section 4.9, “Setting environment variables for the broker containers”.

8.3. Example: configuring AMQ Broker to use Red Hat Single Sign-On

This example shows how to configure AMQ Broker to use Red Hat Single Sign-On for authentication and authorization by using JAAS login modules.

Prerequisites

A Red Hat Single Sign-On instance integrated with an LDAP directory.
- The LDAP directory is populated with users and role information for AMQ Broker.
- Red Hat Single Sign-On is configured to federate users from the LDAP server.
- Red Hat Single Sign-On is configured to use the role-ldap-mapper to map role information from LDAP to Red Hat Single Sign-On.
A Red Hat Single Sign-On realm that has:
- A client configured with the following settings for applications, such as AMQ Management Console, that can use the oAuth protocol to obtain a token:
  Authentication flow: Standard flow
  Valid Redirect URIs: An OpenShift Container Platform route for AMQ Management Console. For example, http://artemis-wconsj-0-svc-rte-kc-ldap-tests-0eae49.apps.redhat-412t.broker.app-services-dev.net/console/*
- A separate client configured with the following settings if you have messaging client applications that cannot use the oAuth protocol to obtain a token:
  Authentication flow: Direct Access Grants
  Valid Redirect URIs: *

Note

Each realm in Red Hat Single Sign-On includes a client named Broker. This client is not related to AMQ Broker.

Procedure

Create a text file named login.config and add the JAAS login module configuration to connect AMQ Broker with Red Hat Single Sign-On. For example:

console {
    // ensure the operator can connect to the broker by referencing the existing properties config
    org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule sufficient
        org.apache.activemq.jaas.properties.user="artemis-users.properties"
        org.apache.activemq.jaas.properties.role="artemis-roles.properties"
        baseDir="/home/jboss/amq-broker/etc";

   org.keycloak.adapters.jaas.BearerTokenLoginModule sufficient
        keycloak-config-file="/amq/extra/secrets/sso-jaas-config/_keycloak-bearer-token.json"
        role-principal-class=org.apache.activemq.artemis.spi.core.security.jaas.RolePrincipal;
};
activemq {
    org.keycloak.adapters.jaas.BearerTokenLoginModule sufficient
        keycloak-config-file="/amq/extra/secrets/sso-jaas-config/_keycloak-bearer-token.json"
        role-principal-class=org.apache.activemq.artemis.spi.core.security.jaas.RolePrincipal;

    org.keycloak.adapters.jaas.DirectAccessGrantsLoginModule sufficient
        keycloak-config-file="/amq/extra/secrets/sso-jaas-config/_keycloak-direct-access.json"
        role-principal-class=org.apache.activemq.artemis.spi.core.security.jaas.RolePrincipal;

    org.apache.activemq.artemis.spi.core.security.jaas.PrincipalConversionLoginModule required
       principalClassList=org.keycloak.KeycloakPrincipal;
};

Note

The path to the .json configuration files must be in the format /amq/extra/secrets/name-jaas-config. For name, specify a string value. You must use the same string value and a -jaas-config suffix to name the secret that you create later in this procedure.
In the example login.config file, a realm named console is used to authenticate AMQ Management Console users and a realm named activemq to authenticate messaging clients.

The following login modules are configured in the example login.config file.

Table 8.4. Login modules
Login module	Description and usage
org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule	This is the default login module and contains the `artemis-users.properties` file, which contains a default user that is required by the Operator to authenticate with the broker.
org.keycloak.adapters.jaas.BearerTokenLoginModule	This login module is for applications, for example, AMQ Management Console, that can use the oAuth protocol to obtain a token. When a user opens AMQ Management Console in a browser window, they are redirected to the Red Hat Single Sign-On console to log in to obtain a bearer token.
org.keycloak.adapters.jaas.DirectAccessGrantsLoginModule	This login module is required for non-HTTP applications, such as messaging clients, which cannot use the oAuth protocol. Using this login module, the broker first authenticates the client using a secret that is configured in Red Hat Single Sign-On and then obtains a token on behalf of the client.
org.apache.activemq.artemis.spi.core.security.jaas.PrincipalConversionLoginModule	This login module is required to convert the Keycloak principal received into a JAAS principal that can be used by AMQ Broker.

Note

In the login.config file example, each .json properties file name has an underscore prefix. The Operator ignores files prefixed with an underscore when it reports the status of the JaasPropertiesApplied condition. If the file names do not have an underscore prefix, the status of the JaasPropertiesApplied condition shows OutofSync permanently because the broker does not recognize properties files used by third party login modules. For more information about status reporting, see Section 4.3.2.1, “Configuring the default JAAS login module using the Security Custom Resource (CR)”.

Create text files for each of the .json properties files that are referenced in the login modules and configure the details required to connect AMQ Broker to Red Hat Single Sign-On. For example:
_keycloak-bearer-token.json
```
{
    "realm": "amq-broker-ldap",
    "resource": "amq-console",
    "auth-server-url": "https://keycloak-svc-rte-kc-ldap-tests-0eae49.apps.412t.broker.app-services-dev.net",
    "principal-attribute": "preferred_username",
    "use-resource-role-mappings": false,
    "ssl-required": "external",
    "confidential-port": 0
}
```
_keycloak-direct-access.json
```
{
    "realm": "amq-broker-ldap",
    "resource": "amq-broker",
    "auth-server-url": "https://keycloak-svc-rte-kc-ldap-tests-0eae49.apps.412t.broker.app-services-dev.net",
    "principal-attribute": "preferred_username",
    "use-resource-role-mappings": false,
    "ssl-required": "external",
    "credentials": {
        "secret": "Lfk6g1ZKlGzNT6eRkz0d1scM4M29Ohmn"
    }
}
```
realm
The realm configured to authenticate the AMQ Broker applications and services in Red Hat Single Sign-On.
resource
The client ID of a client that is configured in Red Red Hat Single Sign-On.
auth-server-url
The base URL of the Red Hat Single Sign-On server.
principal-attribute
The token attribute with which to populate the UserPrincipal name.
use-resource-role-mappings
If set to true, Red Hat Single Sign-On looks inside the token for application level role mappings for the user. If false, it looks at the realm level for user role mappings. The default value is false.
ssl-required
Ensures that all communication to and from the Red Hat Single Sign-On server is over HTTPS. The default value is external, which means that HTTPS is required by default for external requests.
credentials
A secret configured in Red Hat Single Sign-On which the broker uses to log in to Red Hat Single Sign-On and obtain a token on behalf of the client.
Create a text file named _keycloak-js-client.json and add the configuration required for AMQ Management Console to redirect users to the URL of the Red Hat Single Sign-On Admin Console, where they enter their credentials. For example:
```
{
  "realm": "amq-broker-ldap",
  "clientId": "amq-console",
  "url": "https://keycloak-svc-rte-kc-ldap-tests-0eae49.apps.412t.broker.app-services-dev.net"
}
```
Use the oc create secret command to create a secret that contains the files that are referenced in the login module configuration. For example:
```
oc create secret generic sso-jaas-config --from-file=login.config --from-file=artemis-users.properties --from-file=artemis-roles.properties --from-file=_keycloak-bearer-token.json --from-file=_keycloak-direct-access.json --from-file=_keycloak-js-client.json
```
Note
- The secret name must have a suffix of -jaas-config so the Operator can recognize that the secret contains login module configuration and propagate any updates to each broker Pod.
- The secret name must match the last directory name in the path to the .json configuration files, which you specified in the login.config file. For example, if the path to the configuration files is /amq/extra/secrets/sso-jaas-config, you must specify a secret name of sso-jaas-config.
For more information about how to create secrets, see Secrets in the Kubernetes documentation.
Add the secret you created to the ActiveMQArtemis Custom Resource (CR) instance for your broker deployment.
1. Using the OpenShift command-line interface:
  1. Log in to OpenShift as a user that has privileges to deploy CRs in the project for the broker deployment.
  2. Edit the CR for your deployment.
    oc edit ActiveMQArtemis <CR instance name> -n <namespace>
2. Using the OpenShift Container Platform web console:
  1. Log in to the console as a user that has privileges to deploy CRs in the project for the broker deployment.
  2. In the left pane, click Operators Installed Operator.
  3. Click the Red Hat Integration - AMQ Broker for RHEL 8 (Multiarch) operator.
  4. Click the AMQ Broker tab.
  5. Click the name of the ActiveMQArtemis instance name.
  6. Click the YAML tab.
    Within the console, a YAML editor opens, enabling you to configure a CR instance.
Create an extraMounts attribute and a secrets attribute and add the name of the secret. The following example adds a secret named custom-jaas-config to the CR.
```
deploymentPlan:
  ...
  extraMounts:
    secrets:
    - "sso-jaas-config"
  ...
```
In the ActiveMQArtemis CR, create an environment variable that contains the hawtio settings required by AMQ Management Console to use Red Hat Single Sign-On for authentication. The contents of the environment variable are passed as arguments to the Java application launcher when the JVM that hosts a broker is started. For example:
```
env:
- name: JAVA_ARGS_APPEND
  value: -Dhawtio.rolePrincipalClasses=org.apache.activemq.artemis.spi.core.security.jaas.RolePrincipal
      -Dhawtio.keycloakEnabled=true -Dhawtio.keycloakClientConfig=/amq/extra/secrets/sso-jaas-config/_keycloak-js-client.json
      -Dhawtio.authenticationEnabled=true -Dhawtio.realm=console
```
For more information on hawtio settings, see the hawtio documentation.
In the spec section of the ActiveMQArtemis CR, add a brokerProperties attribute and add permissions for the roles configured in the LDAP directory. You can grant a role permissions to a single address. Or, you can specify a wildcard match using the # sign to grant a role permissions to all addresses. For example:
```
spec:
  ...
  brokerProperties:
  - securityRoles.#.producers.send=true
  - securityRoles.#.consumers.consume=true
  ...
```
Save the CR.
The Operator mounts the files in the secret in a /amq/extra/secrets/secret name directory on each Pod and configures the broker JVM to read the mounted login.config file, which contains the SSO configuration, instead of the default login.config file.

8.4. Logging

In addition to viewing the OpenShift logs, you can troubleshoot a running AMQ Broker on OpenShift Container Platform image by viewing the AMQ logs that are output to the container’s console.

Procedure

At the command line, run the following command:

$ oc logs -f <pass:quotes[<pod-name>]> <pass:quotes[<container-name>]>

Revised on 2024-11-07 15:46:24 UTC

Chapter 8. Reference

8.1. Custom Resource configuration reference

8.1.1. Broker Custom Resource configuration reference

8.1.2. Address Custom Resource configuration reference

8.1.3. Security Custom Resource configuration reference

8.4. Logging

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links