Configuration Management - Clustered Deployments with AMQP
This is one option for broadcasting change events to CAS nodes. RabbitMQ is open source message broker software (sometimes called message-oriented middleware) that implements the Advanced Message Queuing Protocol (AMQP).
Support is enabled by including the following dependency in the final overlay:
1
2
3
4
5
<dependency>
<groupId>org.apereo.cas</groupId>
<artifactId>cas-server-support-configuration-cloud-amqp</artifactId>
<version>${cas.version}</version>
</dependency>
1
implementation "org.apereo.cas:cas-server-support-configuration-cloud-amqp:${project.'cas.version'}"
1
2
3
4
5
6
7
8
9
dependencyManagement {
imports {
mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
}
}
dependencies {
implementation "org.apereo.cas:cas-server-support-configuration-cloud-amqp"
}
1
2
3
4
5
6
7
8
9
10
dependencies {
/*
The following platform references are included automatically and are listed for reference only.
implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
*/
implementation "org.apereo.cas:cas-server-support-configuration-cloud-amqp"
}
The following settings and properties are available from the CAS configuration catalog:
spring.rabbitmq.address-shuffle-modeMode used to shuffle configured addresses.
noneMode used to shuffle configured addresses.
spring.rabbitmq.addressesList of addresses to which the client should connect.
List of addresses to which the client should connect. When set, the host and port are ignored.
spring.rabbitmq.cache.channel.checkout-timeoutDuration to wait to obtain a channel if the cache size has been reached.
Duration to wait to obtain a channel if the cache size has been reached. If 0, always create a new channel.
spring.rabbitmq.cache.channel.sizeNumber of channels to retain in the cache.
Number of channels to retain in the cache. When "check-timeout" > 0, max channels per connection.
spring.rabbitmq.cache.connection.modeConnection factory cache mode.
channelConnection factory cache mode.
spring.rabbitmq.cache.connection.sizeNumber of connections to cache.
Number of connections to cache. Only applies when mode is CONNECTION.
spring.rabbitmq.channel-rpc-timeoutContinuation timeout for RPC calls in channels.
10mContinuation timeout for RPC calls in channels. Set it to zero to wait forever.
spring.rabbitmq.connection-timeoutConnection timeout.
Connection timeout. Set it to zero to wait forever.
spring.rabbitmq.dynamicWhether to create an AmqpAdmin bean.
trueWhether to create an AmqpAdmin bean.
spring.rabbitmq.hostRabbitMQ host.
localhostRabbitMQ host. Ignored if an address is set.
spring.rabbitmq.listener.direct.acknowledge-modeAcknowledge mode of container.
Acknowledge mode of container.
spring.rabbitmq.listener.direct.auto-startupWhether to start the container automatically on startup.
trueWhether to start the container automatically on startup.
spring.rabbitmq.listener.direct.consumers-per-queueNumber of consumers per queue.
Number of consumers per queue.
spring.rabbitmq.listener.direct.de-batching-enabledWhether the container should present batched messages as discrete messages or call the listener with the batch.
trueWhether the container should present batched messages as discrete messages or call the listener with the batch.
spring.rabbitmq.listener.direct.default-requeue-rejectedWhether rejected deliveries are re-queued by default.
Whether rejected deliveries are re-queued by default.
spring.rabbitmq.listener.direct.force-stopWhether the container (when stopped) should stop immediately after processing the current message or stop after processing all pre-fetched messages.
falseWhether the container (when stopped) should stop immediately after processing the current message or stop after processing all pre-fetched messages.
spring.rabbitmq.listener.direct.idle-event-intervalHow often idle container events should be published.
How often idle container events should be published.
spring.rabbitmq.listener.direct.missing-queues-fatalWhether to fail if the queues declared by the container are not available on the broker.
falseWhether to fail if the queues declared by the container are not available on the broker.
spring.rabbitmq.listener.direct.observation-enabledWhether to enable observation.
falseWhether to enable observation.
spring.rabbitmq.listener.direct.prefetchMaximum number of unacknowledged messages that can be outstanding at each consumer.
Maximum number of unacknowledged messages that can be outstanding at each consumer.
spring.rabbitmq.listener.direct.retry.enabledWhether publishing retries are enabled.
falseWhether publishing retries are enabled.
spring.rabbitmq.listener.direct.retry.initial-intervalDuration between the first and second attempt to deliver a message.
1000msDuration between the first and second attempt to deliver a message.
spring.rabbitmq.listener.direct.retry.max-attempts
spring.rabbitmq.listener.direct.retry.max-intervalMaximum duration between attempts.
10000msMaximum duration between attempts.
spring.rabbitmq.listener.direct.retry.max-retriesMaximum number of retry attempts to deliver a message.
3Maximum number of retry attempts to deliver a message.
spring.rabbitmq.listener.direct.retry.multiplierMultiplier to apply to the previous retry interval.
1Multiplier to apply to the previous retry interval.
spring.rabbitmq.listener.direct.retry.statelessWhether retries are stateless or stateful.
trueWhether retries are stateless or stateful.
spring.rabbitmq.listener.simple.acknowledge-modeAcknowledge mode of container.
Acknowledge mode of container.
spring.rabbitmq.listener.simple.auto-startupWhether to start the container automatically on startup.
trueWhether to start the container automatically on startup.
spring.rabbitmq.listener.simple.batch-sizeBatch size, expressed as the number of physical messages, to be used by the container.
Batch size, expressed as the number of physical messages, to be used by the container.
spring.rabbitmq.listener.simple.concurrencyMinimum number of listener invoker threads.
Minimum number of listener invoker threads.
spring.rabbitmq.listener.simple.consumer-batch-enabledWhether the container creates a batch of messages based on the 'receive-timeout' and 'batch-size'.
falseWhether the container creates a batch of messages based on the 'receive-timeout' and 'batch-size'. Coerces 'de-batching-enabled' to true to include the contents of a producer created batch in the batch as discrete records.
spring.rabbitmq.listener.simple.de-batching-enabledWhether the container should present batched messages as discrete messages or call the listener with the batch.
trueWhether the container should present batched messages as discrete messages or call the listener with the batch.
spring.rabbitmq.listener.simple.default-requeue-rejectedWhether rejected deliveries are re-queued by default.
Whether rejected deliveries are re-queued by default.
spring.rabbitmq.listener.simple.force-stopWhether the container (when stopped) should stop immediately after processing the current message or stop after processing all pre-fetched messages.
falseWhether the container (when stopped) should stop immediately after processing the current message or stop after processing all pre-fetched messages.
spring.rabbitmq.listener.simple.idle-event-intervalHow often idle container events should be published.
How often idle container events should be published.
spring.rabbitmq.listener.simple.max-concurrencyMaximum number of listener invoker threads.
Maximum number of listener invoker threads.
spring.rabbitmq.listener.simple.missing-queues-fatalWhether to fail if the queues declared by the container are not available on the broker and/or whether to stop the container if one or more queues are deleted at runtime.
trueWhether to fail if the queues declared by the container are not available on the broker and/or whether to stop the container if one or more queues are deleted at runtime.
spring.rabbitmq.listener.simple.observation-enabledWhether to enable observation.
falseWhether to enable observation.
spring.rabbitmq.listener.simple.prefetchMaximum number of unacknowledged messages that can be outstanding at each consumer.
Maximum number of unacknowledged messages that can be outstanding at each consumer.
spring.rabbitmq.listener.simple.retry.enabledWhether publishing retries are enabled.
falseWhether publishing retries are enabled.
spring.rabbitmq.listener.simple.retry.initial-intervalDuration between the first and second attempt to deliver a message.
1000msDuration between the first and second attempt to deliver a message.
spring.rabbitmq.listener.simple.retry.max-attempts
spring.rabbitmq.listener.simple.retry.max-intervalMaximum duration between attempts.
10000msMaximum duration between attempts.
spring.rabbitmq.listener.simple.retry.max-retriesMaximum number of retry attempts to deliver a message.
3Maximum number of retry attempts to deliver a message.
spring.rabbitmq.listener.simple.retry.multiplierMultiplier to apply to the previous retry interval.
1Multiplier to apply to the previous retry interval.
spring.rabbitmq.listener.simple.retry.statelessWhether retries are stateless or stateful.
trueWhether retries are stateless or stateful.
spring.rabbitmq.listener.simple.transaction-size
spring.rabbitmq.listener.stream.native-listenerWhether the container will support listeners that consume native stream messages instead of Spring AMQP messages.
falseWhether the container will support listeners that consume native stream messages instead of Spring AMQP messages.
spring.rabbitmq.listener.stream.observation-enabledWhether to enable observation.
falseWhether to enable observation.
spring.rabbitmq.listener.typeListener container type.
simpleListener container type.
spring.rabbitmq.max-inbound-message-body-sizeMaximum size of the body of inbound (received) messages.
64MBMaximum size of the body of inbound (received) messages.
spring.rabbitmq.passwordLogin to authenticate against the broker.
guestLogin to authenticate against the broker.
spring.rabbitmq.portRabbitMQ port.
RabbitMQ port. Ignored if an address is set. Default to 5672, or 5671 if SSL is enabled.
spring.rabbitmq.publisher-confirm-typeType of publisher confirms to use.
Type of publisher confirms to use.
spring.rabbitmq.publisher-confirms
spring.rabbitmq.publisher-returnsWhether to enable publisher returns.
falseWhether to enable publisher returns.
spring.rabbitmq.requested-channel-maxNumber of channels per connection requested by the client.
2047Number of channels per connection requested by the client. Use 0 for unlimited.
spring.rabbitmq.requested-heartbeatRequested heartbeat timeout; zero for none.
Requested heartbeat timeout; zero for none. If a duration suffix is not specified, seconds will be used.
spring.rabbitmq.ssl.algorithmSSL algorithm to use.
SSL algorithm to use. By default, configured by the Rabbit client library.
spring.rabbitmq.ssl.bundleSSL bundle name.
SSL bundle name.
spring.rabbitmq.ssl.enabledWhether to enable SSL support.
Whether to enable SSL support. Determined automatically if an address is provided with the protocol (amqp:// vs. amqps://).
spring.rabbitmq.ssl.key-storePath to the key store that holds the SSL certificate.
Path to the key store that holds the SSL certificate.
spring.rabbitmq.ssl.key-store-algorithmKey store algorithm.
SunX509Key store algorithm.
spring.rabbitmq.ssl.key-store-passwordPassword used to access the key store.
Password used to access the key store.
spring.rabbitmq.ssl.key-store-typeKey store type.
PKCS12Key store type.
spring.rabbitmq.ssl.trust-storeTrust store that holds SSL certificates.
Trust store that holds SSL certificates.
spring.rabbitmq.ssl.trust-store-algorithmTrust store algorithm.
SunX509Trust store algorithm.
spring.rabbitmq.ssl.trust-store-passwordPassword used to access the trust store.
Password used to access the trust store.
spring.rabbitmq.ssl.trust-store-typeTrust store type.
JKSTrust store type.
spring.rabbitmq.ssl.validate-server-certificateWhether to enable server side certificate validation.
trueWhether to enable server side certificate validation.
spring.rabbitmq.ssl.verify-hostnameWhether to enable hostname verification.
trueWhether to enable hostname verification.
spring.rabbitmq.stream.hostHost of a RabbitMQ instance with the Stream plugin enabled.
localhostHost of a RabbitMQ instance with the Stream plugin enabled.
spring.rabbitmq.stream.nameName of the stream.
Name of the stream.
spring.rabbitmq.stream.passwordLogin password to authenticate to the broker.
Login password to authenticate to the broker. When not set spring.rabbitmq.password is used.
spring.rabbitmq.stream.portStream port of a RabbitMQ instance with the Stream plugin enabled.
Stream port of a RabbitMQ instance with the Stream plugin enabled.
spring.rabbitmq.stream.ssl.bundleSSL bundle name.
SSL bundle name.
spring.rabbitmq.stream.ssl.enabledWhether to enable SSL support.
Whether to enable SSL support. Enabled automatically if "bundle" is provided.
spring.rabbitmq.stream.usernameLogin user to authenticate to the broker.
Login user to authenticate to the broker. When not set, spring.rabbitmq.username is used.
spring.rabbitmq.stream.virtual-hostVirtual host of a RabbitMQ instance with the Stream plugin enabled.
Virtual host of a RabbitMQ instance with the Stream plugin enabled. When not set, spring.rabbitmq.virtual-host is used.
spring.rabbitmq.template.allowed-list-patternsSimple patterns for allowable packages/classes for deserialization.
Simple patterns for allowable packages/classes for deserialization.
spring.rabbitmq.template.default-receive-queueName of the default queue to receive messages from when none is specified explicitly.
Name of the default queue to receive messages from when none is specified explicitly.
spring.rabbitmq.template.exchangeName of the default exchange to use for send operations.
Name of the default exchange to use for send operations.
spring.rabbitmq.template.mandatoryWhether to enable mandatory messages.
Whether to enable mandatory messages.
spring.rabbitmq.template.observation-enabledWhether to enable observation.
falseWhether to enable observation.
spring.rabbitmq.template.queue
spring.rabbitmq.template.receive-timeoutTimeout for receive() operations.
Timeout for receive() operations.
spring.rabbitmq.template.reply-timeoutTimeout for sendAndReceive() operations.
Timeout for sendAndReceive() operations.
spring.rabbitmq.template.retry.enabledWhether publishing retries are enabled.
falseWhether publishing retries are enabled.
spring.rabbitmq.template.retry.initial-intervalDuration between the first and second attempt to deliver a message.
1000msDuration between the first and second attempt to deliver a message.
spring.rabbitmq.template.retry.max-attempts
spring.rabbitmq.template.retry.max-intervalMaximum duration between attempts.
10000msMaximum duration between attempts.
spring.rabbitmq.template.retry.max-retriesMaximum number of retry attempts to deliver a message.
3Maximum number of retry attempts to deliver a message.
spring.rabbitmq.template.retry.multiplierMultiplier to apply to the previous retry interval.
1Multiplier to apply to the previous retry interval.
spring.rabbitmq.template.routing-keyValue of a default routing key to use for send operations.
Value of a default routing key to use for send operations.
spring.rabbitmq.usernameLogin user to authenticate to the broker.
guestLogin user to authenticate to the broker.
spring.rabbitmq.virtual-hostVirtual host to use when connecting to the broker.
Virtual host to use when connecting to the broker.
Required settings may be needed to activate or affect the feature; review them even when they have a default. Optional settings only need to be set to change a default or to turn on the behavior they control. Third party settings belong to libraries such as Spring Boot that CAS builds on; their own documentation may have more detail.
Notes on configuration
Configuration Metadata
The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.
Be Selective
This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.
YAGNI
Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.
Naming Convention
Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all
forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where
this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those
that might be presented to the system via an external library or framework such as Spring Boot, etc.
Note
When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value.
The only possible exception to this rule is when naming actuator endpoints; The name of the
actuator endpoints (i.e. ssoSessions) MUST remain in camelCase mode.
Settings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided
to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with
the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition
or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the
way you intend.
Validation
Configuration properties are automatically validated on CAS startup to report issues with configuration binding, especially if defined CAS settings cannot be recognized or validated by the configuration schema. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.
Indexed Settings
CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be
incremented by the adopter to allow for distinct multiple configuration blocks.
Troubleshooting
To enable additional logging, modify the logging configuration file to add the following:
1
2
3
4
<Logger name="org.springframework.amqp" level="debug" additivity="false">
<AppenderRef ref="casConsole"/>
<AppenderRef ref="casFile"/>
</Logger>