From 9f98c4d15df2184fc6087c243312de89ab1e7c33 Mon Sep 17 00:00:00 2001 From: Marcial Rosales Date: Wed, 3 Dec 2025 14:33:36 +0100 Subject: [PATCH 1/6] Explain that resources are ordered as they were configured. --- docs/management/index.md | 3 ++- versioned_docs/version-4.2/management/index.md | 1 + 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/management/index.md b/docs/management/index.md index d100dcbb5..77224d35c 100644 --- a/docs/management/index.md +++ b/docs/management/index.md @@ -575,7 +575,8 @@ The next sections configure these resources in the management UI. #### How OAuth 2.0 resources are presented to users -When there are more than one OAuth 2.0 resource configured in the management UI, RabbitMQ shows a drop-down list in addition to the button with the label *Click here to logon*. The drop-down list has one option per resource. The label of the option is by default the resource's id however you can ovrride it. +When there are more than one OAuth 2.0 resource configured in the management UI, RabbitMQ shows a drop-down list in addition to the button with the label *Click here to logon*. The drop-down list has one option per resource. The label of the option is by default the resource's id however you can override it. +Resources are listed in the same order as they were configured. It is possible to have some resources configured with `sp_initiated` logon and others with `idp_initiated` logon. And it is also possible to disable a resource, in other words, the resource does not appear as an option in the drop-down. diff --git a/versioned_docs/version-4.2/management/index.md b/versioned_docs/version-4.2/management/index.md index d100dcbb5..38598e53a 100644 --- a/versioned_docs/version-4.2/management/index.md +++ b/versioned_docs/version-4.2/management/index.md @@ -576,6 +576,7 @@ The next sections configure these resources in the management UI. #### How OAuth 2.0 resources are presented to users When there are more than one OAuth 2.0 resource configured in the management UI, RabbitMQ shows a drop-down list in addition to the button with the label *Click here to logon*. The drop-down list has one option per resource. The label of the option is by default the resource's id however you can ovrride it. +Resources are listed in the same order as they were configured. It is possible to have some resources configured with `sp_initiated` logon and others with `idp_initiated` logon. And it is also possible to disable a resource, in other words, the resource does not appear as an option in the drop-down. From 64338285a707dae6aacf24a37186fa7c85441985 Mon Sep 17 00:00:00 2001 From: Marcial Rosales Date: Wed, 10 Dec 2025 16:27:00 +0100 Subject: [PATCH 2/6] Predetermine authentication methods --- docs/management/index.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/management/index.md b/docs/management/index.md index 77224d35c..3cfefc51f 100644 --- a/docs/management/index.md +++ b/docs/management/index.md @@ -658,6 +658,41 @@ And this is the management UI with Basic Authentication activated (`management.o ![More than one OAuth 2.0 resource, with oauth_disable_basic_auth = false](./management-oauth-many-with-basic-auth.png) +### Preselect or predetermine authentication mechanism {#preselect-auth-mechanism} + +By default, when users navigate to the management UI home page, they see all available authentication mechanisms and can choose which one to use. +However, in some scenarios, users may be routed to the management UI with an authentication mechanism already preselected or predefined. This allows external systems to guide users to a specific authentication flow. + +To preselect or predetermine the authentication mechanism, users must sent to the `/login` endpoint with the +appropriate request parameters. And the management ui redirects them back to the home page configured according +to their preferred authentication mechanism. + +The following request parameters control the behaviour: + +#### Preselection Mode (preferred_auth_mechanism) + +Use the `preferred_auth_mechanism` parameter to preselect an authentication method while still showing all options. + +- **OAuth 2.0 resource**: `preferred_auth_mechanism=oauth2:rabbit_dev` + - Preselects the OAuth 2.0 resource server, e.g. `rabbit_dev` + - Expands the OAuth 2.0 section and collapses the basic authentication section in the home page + +- **Basic authentication**: `preferred_auth_mechanism=basic` + - Preselects basic authentication + - Expands the basic authentication section and collapses the OAuth 2.0 section + +#### Strict Mode (strict_auth_mechanism) + +Use the `strict_auth_mechanism parameter` to show only the specified authentication method. Other methods are hidden. + +- **OAuth 2.0 resource only**: `/login?strict_auth_mechanism=oauth2:rabbit_dev` + - Shows only the "Click here to login" button for the `rabbit_dev` resource server + - No other authentication options are displayed + +- **Basic authentication only**: `/login?strict_auth_mechanism=basic` + - Shows only the basic authentication form + - No OAuth 2.0 options are displayed + ### Troubleshooting {#troubleshooting} [Troubleshooting management UI access in OAuth 2-enabled clusters](./troubleshooting-oauth2#management-ui) is a companion guide From 010d3267f3730c687865573cca7710546cada45a Mon Sep 17 00:00:00 2001 From: Marcial Rosales Date: Wed, 10 Dec 2025 16:43:54 +0100 Subject: [PATCH 3/6] Minor corrections --- docs/management/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/management/index.md b/docs/management/index.md index 3cfefc51f..778e76e97 100644 --- a/docs/management/index.md +++ b/docs/management/index.md @@ -380,6 +380,7 @@ To configure OAuth 2.0 in the management UI you need a [minimum configuration](# * [Special attention to CSP header `connect-src`](#csp-header) * [Identity-Provider initiated logon](#idp-initiated-logon) * [Support multiple OAuth 2.0 resources](#support-multiple-resources) + * [Preselect or predetermine authentication mechanism](#preselect-auth-mechanism) ### Minimum configuration {#minimum-configuration} @@ -664,21 +665,20 @@ By default, when users navigate to the management UI home page, they see all ava However, in some scenarios, users may be routed to the management UI with an authentication mechanism already preselected or predefined. This allows external systems to guide users to a specific authentication flow. To preselect or predetermine the authentication mechanism, users must sent to the `/login` endpoint with the -appropriate request parameters. And the management ui redirects them back to the home page configured according +appropriate request parameters. And the management UI redirects them back to the home page configured according to their preferred authentication mechanism. The following request parameters control the behaviour: #### Preselection Mode (preferred_auth_mechanism) -Use the `preferred_auth_mechanism` parameter to preselect an authentication method while still showing all options. +Use the `preferred_auth_mechanism` request parameter to preselect an authentication method while still showing all options. - **OAuth 2.0 resource**: `preferred_auth_mechanism=oauth2:rabbit_dev` - - Preselects the OAuth 2.0 resource server, e.g. `rabbit_dev` - Expands the OAuth 2.0 section and collapses the basic authentication section in the home page + - Preselects the OAuth 2.0 resource server, e.g. `rabbit_dev` - **Basic authentication**: `preferred_auth_mechanism=basic` - - Preselects basic authentication - Expands the basic authentication section and collapses the OAuth 2.0 section #### Strict Mode (strict_auth_mechanism) From b3e516f37e1ea350716d60720bad624cead243fd Mon Sep 17 00:00:00 2001 From: RichardJJG Date: Wed, 10 Dec 2025 19:13:40 +0000 Subject: [PATCH 4/6] [TNZDOC-1594] General edits --- docs/management/index.md | 165 +++++++++++------- .../version-4.2/management/index.md | 12 +- 2 files changed, 110 insertions(+), 67 deletions(-) diff --git a/docs/management/index.md b/docs/management/index.md index 778e76e97..e4c4eade2 100644 --- a/docs/management/index.md +++ b/docs/management/index.md @@ -45,28 +45,31 @@ core RabbitMQ features and do not require or rely on this plugin. This guide covers: - * [Basic usage](#usage) of management UI - * The [HTTP API](#http-api) provided by the management plugin - * General plugin [configuration](#configuration) - * [Reverse proxy (Nginx or Apache)](#http-api-proxy) in front of the HTTP API - * How to [enable HTTPS for management UI](#single-listener-https) and its underlying API - * How this plugin [operates in multi-node clusters](#clustering) - * How to [disable metric collection](#disable-stats) to use [Prometheus](./prometheus) exclusively for monitoring - * How to create [a user with limited permissions for monitoring purposes](#monitoring-permissions) only - * [Authenticating with OAuth 2](#oauth2-authentication) - * [Strict transport security](#hsts), [Content security policy](#csp), [cross-origin resource sharing](#cors), and [other security-related header](#other-security-headers) control - * [Statistics collection interval](#statistics-interval) - * [Message rate mode](#rates-mode) (rate fidelity) and [data retention intervals](#sample-retention) - * [HTTP API request logging](#http-logging) - * How to set a [management UI login session timeout](#login-session-timeout) - * How to [reset statistics database](#reset-stats) used by this plugin +- [Basic usage](#usage) of management UI +- The [HTTP API](#http-api) provided by the management plugin +- General plugin [configuration](#configuration) +- [Reverse proxy (Nginx or Apache)](#http-api-proxy) in front of the HTTP API +- How to [enable HTTPS for management UI](#single-listener-https) and its underlying API +- How this plugin [operates in multi-node clusters](#clustering) +- How to [disable metric collection](#disable-stats) to use [Prometheus](../prometheus/index.md) + exclusively for monitoring +- How to create [a user with limited permissions for monitoring purposes](#monitoring-permissions) + only +- [Authenticating with OAuth 2](#oauth2-authentication) +- [Strict transport security](#hsts), [Content security policy](#csp), + [cross-origin resource sharing](#cors), and [other security-related header](#other-security-headers) + control +- [Statistics collection interval](#statistics-interval) +- [Message rate mode](#rates-mode) (rate fidelity) and [data retention intervals](#sample-retention) +- [HTTP API request logging](#http-logging) +- How to set a [management UI login session timeout](#login-session-timeout) +- How to [reset statistics database](#reset-stats) used by this plugin The plugin also provides extension points that other plugins, such as [rabbitmq-top](https://github.com/rabbitmq/rabbitmq-server/tree/main/deps/rabbitmq_top) or [rabbitmq-shovel-management](https://github.com/rabbitmq/rabbitmq-shovel-management), use to extend the UI. - ## Management UI and External Monitoring Systems {#external-monitoring} :::important @@ -359,34 +362,49 @@ rabbitmqctl set_permissions --vhost "vhost-name" "monitoring" "^$" "^$" "^$" You can configure RabbitMQ to use [JWT-encoded OAuth 2.0 access tokens](https://github.com/rabbitmq/rabbitmq-server/tree/main/deps/rabbitmq_auth_backend_oauth2) to authenticate client applications, however, to use OAuth 2.0 authentication in the management UI, you have to configure it separately. There are two ways to initiate OAuth 2.0 authentication in the management UI: -- *Service-Provided Initiated login*. The is the OAuth method and the default way to initiate authentication in the management UI. It uses the [OAuth 2.0 Authorization Code Flow with PKCE](https://datatracker.ietf.org/doc/html/rfc7636) to redirect users to the configured OAuth 2.0 provider to authenticate. When they are authenticated, users get an access token, and are then returned back to the management UI where they are automatically logged in. The management UI is tested against these OAuth 2.0 providers: - - * [UAA](https://github.com/cloudfoundry/uaa) - * [Keycloak](https://www.keycloak.org/) - * [Auth0](https://auth0.com/) - * [Azure](https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/auth-oauth2) - * [OAuth2 Proxy](https://oauth2-proxy.github.io/oauth2-proxy/) - * [Okta](https://www.okta.com) - -- *Identity-Provider Initiated login*. For this type of login, users must come to RabbitMQ with an access token.This type of authentication is typical in portals which offers access to various applications/services to authenticated users. One of those services could be one or many RabbitMQ clusters. When a user requests access to a RabbitMQ cluster, the portal forwards the user to RabbitMQ's management UI with an access token issued for the user and RabbitMQ cluster. This type of authentication is covered in the sub-section [Identity-Provider initiated logon](#idp-initiated-logon). - -To configure OAuth 2.0 in the management UI you need a [minimum configuration](#minimum-configuration). However, you may require additional configuration depending on your use case: - * [Client secret](#configure-client-secret) - * [Allow Basic and OAuth 2 authentication for management HTTP API](#allow-basic-auth-for-http-api) - * [Allow Basic and OAuth 2 authentication for management UI](#allow-basic-auth-for-mgt-ui) - * [Logging out of the management UI](#about-logout-workflow) - * [Configure extra parameters for authorization and token endpoints](#extra-endpoint-params) - * [Special attention to CSP header `connect-src`](#csp-header) - * [Identity-Provider initiated logon](#idp-initiated-logon) - * [Support multiple OAuth 2.0 resources](#support-multiple-resources) - * [Preselect or predetermine authentication mechanism](#preselect-auth-mechanism) +- *Service-Provided Initiated login*. The is the OAuth method and the default way to initiate + authentication in the management UI. It uses the + [OAuth 2.0 Authorization Code Flow with PKCE](https://datatracker.ietf.org/doc/html/rfc7636) to + redirect users to the configured OAuth 2.0 + provider to authenticate. When they are authenticated, users get an access token, and are then + returned back to the management UI where they are automatically logged in. The management UI is + tested against these OAuth 2.0 providers: + + - [UAA](https://github.com/cloudfoundry/uaa) + - [Keycloak](https://www.keycloak.org/) + - [Auth0](https://auth0.com/) + - [Azure](https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/auth-oauth2) + - [OAuth2 Proxy](https://oauth2-proxy.github.io/oauth2-proxy/) + - [Okta](https://www.okta.com) + +- *Identity-Provider Initiated login*. For this type of login, users must come to RabbitMQ with an + access token.This type of authentication is typical in portals which offers access to various + applications/services to authenticated users. One of those services could be one or many RabbitMQ + clusters. When a user requests access to a RabbitMQ cluster, the portal forwards the user to + RabbitMQ's management UI with an access token issued for the user and RabbitMQ cluster. This type + of authentication is covered in the sub-section + [Identity-Provider initiated logon](#idp-initiated-logon). + +To configure OAuth 2.0 in the management UI you need a +[minimum configuration](#minimum-configuration). However, you may require additional configuration +depending on your use case: + +- [Client secret](#configure-client-secret) +- [Allow Basic and OAuth 2 authentication for management HTTP API](#allow-basic-auth-for-http-api) +- [Allow Basic and OAuth 2 authentication for management UI](#allow-basic-auth-for-mgt-ui) +- [Logging out of the management UI](#about-logout-workflow) +- [Configure extra parameters for authorization and token endpoints](#extra-endpoint-params) +- [Special attention to CSP header `connect-src`](#csp-header) +- [Identity-Provider initiated logon](#idp-initiated-logon) +- [Support multiple OAuth 2.0 resources](#support-multiple-resources) +- [Preselect or predetermine authentication mechanism](#preselect-auth-mechanism) ### Minimum configuration {#minimum-configuration} The first section is the minimum configuration required to use OAuth 2.0 authentication in the management UI. The following sections explain how to further configure OAuth 2.0 depending of the use cases. -Given the following configuration of the [OAuth 2.0 plugin](./oauth2): +Given the following configuration of the [OAuth 2.0 plugin](../oauth2.md): ```ini auth_oauth2.resource_server_id = new_resource_server_id @@ -402,11 +420,21 @@ management.oauth_scopes = ``` - `oauth_enabled` is a mandatory field -- `oauth_client_id` is a mandatory field. It is the OAuth Client Id associated with this RabbitMQ cluster in the OAuth Provider, and it is used to request a token on behalf of the user. -- `oauth_scopes` is a mandatory field which must be set at all times except in the case when OAuth providers automatically grant scopes associated to the `oauth_client_id`. `oauth_scopes` is a list of space-separated strings that indicate which permissions the application is requesting. Most OAuth providers only issue tokens with the scopes requested during the user authentication. RabbitMQ sends this field along with its `oauth_client_id` during the user authentication. If this field is not set, RabbitMQ defaults to `openid profile`. + +- `oauth_client_id` is a mandatory field. It is the OAuth Client Id associated with this RabbitMQ + cluster in the OAuth Provider, and it is used to request a token on behalf of the user. + +- `oauth_scopes` is a mandatory field which must be set at all times except in the case when OAuth + providers automatically grant scopes associated to the `oauth_client_id`. `oauth_scopes` is a list + of space-separated strings that indicate which permissions the application is requesting. Most + OAuth providers only issue tokens with the scopes requested during the user authentication. + RabbitMQ sends this field along with its `oauth_client_id` during the user authentication. If this + field is not set, RabbitMQ defaults to `openid profile`. Given above configuration, when a user visits the management UI, the following two events take place: -1. RabbitMQ uses the URL found in `auth_oauth2.issuer` to download the OpenID Provider configuration. Learn more in the [OAuth 2.0 guide](./oauth2#discovery-endpoint-params) + +1. RabbitMQ uses the URL found in `auth_oauth2.issuer` to download the OpenID Provider + configuration. Learn more in the [OAuth 2.0 guide](../oauth2.md#discovery-endpoint-params) :::warning If RabbitMQ cannot download the OpenID provider configuration, it shows an error message and the OAuth 2.0 authentication option will be disabled in the management UI @@ -421,7 +449,9 @@ Given above configuration, when a user visits the management UI, the following t If you used to configure `auth_oauth2.metadata_url` because your provider used a slightly different OpenId Discovery endpoint url, since RabbitMQ 4.1 you should instead configure the correct path and/or include any additional parameters. Please read [this section of the documentation](./oauth2#discovery-endpoint-params) where it is explained how to do it. `auth_oauth2.metadata_url` may be deprecated in future versions. ::: -2. RabbitMQ displays a button with the label "Click here to login". When the user clicks on the button, the management UI initiates the OAuth 2.0 Authorization Code Flow, which redirects the user to the identity provider to authenticate and get a token. +2. RabbitMQ displays a button with the label "Click here to login". When the user clicks on the + button, the management UI initiates the OAuth 2.0 Authorization Code Flow, which redirects the + user to the identity provider to authenticate and get a token. ### Configure client secret {#configure-client-secret} @@ -576,10 +606,14 @@ The next sections configure these resources in the management UI. #### How OAuth 2.0 resources are presented to users -When there are more than one OAuth 2.0 resource configured in the management UI, RabbitMQ shows a drop-down list in addition to the button with the label *Click here to logon*. The drop-down list has one option per resource. The label of the option is by default the resource's id however you can override it. -Resources are listed in the same order as they were configured. +When there is more than one OAuth 2.0 resource configured in the management UI, RabbitMQ shows a +drop-down menu in addition to the button with the label **Click here to logon**. The drop-down menu +has one option per resource. The label of the option is the resource's ID by default, but you can +override it. Resources are listed in the order in which they were configured. -It is possible to have some resources configured with `sp_initiated` logon and others with `idp_initiated` logon. And it is also possible to disable a resource, in other words, the resource does not appear as an option in the drop-down. +You can have some resources configured with `sp_initiated` log-on and others with `idp_initiated` +log-on. You can disable a resource so that the resource does not appear as an option in the +drop-down menu. #### Optionally set common settings for all resources @@ -622,6 +656,7 @@ management.oauth_resource_servers.1.label = RabbitMQ Production With this configuration, when the user chooses to option `RabbitMQ Production`, RabbitMQ initiates the *Authorization Code flow* which takes the user to the URL configured in `auth_oauth2.issuer` with the following settings: + - `client_id` : `rabbit_prod_mgt_ui` - `resource` : `rabbit_prod` - `scopes` : `openid rabbitmq.tag:management rabbitmq.read:*/*` @@ -661,35 +696,42 @@ And this is the management UI with Basic Authentication activated (`management.o ### Preselect or predetermine authentication mechanism {#preselect-auth-mechanism} -By default, when users navigate to the management UI home page, they see all available authentication mechanisms and can choose which one to use. -However, in some scenarios, users may be routed to the management UI with an authentication mechanism already preselected or predefined. This allows external systems to guide users to a specific authentication flow. +By default, when users navigate to the management UI home page they see all available authentication +mechanisms and can choose which one to use. However, in some scenarios, users might be routed to the +management UI with an authentication mechanism already preselected or predefined. This allows +external systems to guide users to a specific authentication flow. -To preselect or predetermine the authentication mechanism, users must sent to the `/login` endpoint with the -appropriate request parameters. And the management UI redirects them back to the home page configured according -to their preferred authentication mechanism. +To preselect or predetermine the authentication mechanism, users must send to the `/login` endpoint +with the appropriate request parameters. The management UI then redirects them back to the home page +configured according to their preferred authentication mechanism. The following request parameters control the behaviour: -#### Preselection Mode (preferred_auth_mechanism) +#### Preselection Mode (`preferred_auth_mechanism`) -Use the `preferred_auth_mechanism` request parameter to preselect an authentication method while still showing all options. +Use the `preferred_auth_mechanism` request parameter to preselect an authentication method while +still showing all options. - **OAuth 2.0 resource**: `preferred_auth_mechanism=oauth2:rabbit_dev` + - Expands the OAuth 2.0 section and collapses the basic authentication section in the home page - - Preselects the OAuth 2.0 resource server, e.g. `rabbit_dev` + - Preselects the OAuth 2.0 resource server, such as `rabbit_dev` - **Basic authentication**: `preferred_auth_mechanism=basic` + - Expands the basic authentication section and collapses the OAuth 2.0 section - -#### Strict Mode (strict_auth_mechanism) + +#### Strict Mode (`strict_auth_mechanism`) Use the `strict_auth_mechanism parameter` to show only the specified authentication method. Other methods are hidden. - **OAuth 2.0 resource only**: `/login?strict_auth_mechanism=oauth2:rabbit_dev` - - Shows only the "Click here to login" button for the `rabbit_dev` resource server + + - Shows only the **Click here to login** button for the `rabbit_dev` resource server - No other authentication options are displayed - **Basic authentication only**: `/login?strict_auth_mechanism=basic` + - Shows only the basic authentication form - No OAuth 2.0 options are displayed @@ -698,7 +740,6 @@ Use the `strict_auth_mechanism parameter` to show only the specified authenticat [Troubleshooting management UI access in OAuth 2-enabled clusters](./troubleshooting-oauth2#management-ui) is a companion guide dedicated to common OAuth 2-specific issues. - ## HTTP API {#http-api} ### API Endpoints {#http-api-endpoints} @@ -710,10 +751,9 @@ See [HTTP API reference](./http-api-reference/). The API is intended to be used for basic observability tasks. [Prometheus and Grafana](./prometheus) are recommended for long term metric storage, alerting, anomaly detection, and so on. -Any cluster node with `rabbitmq-management` plugin activated can be -used for management UI access or HTTP API access. -It will reach out to other nodes and collect their stats, then aggregate and return a response -to the client. +Any cluster node with `rabbitmq-management` plugin activated can be used for management UI access or +HTTP API access. It will reach out to other nodes and collect their stats, then aggregate and return +a response to the client. When using the API in a cluster of nodes, there is no need to contact each node via HTTP API individually. Instead, contact a random node or a load balancer that sits in front @@ -721,8 +761,7 @@ of the cluster. ### HTTP API Clients and Tooling {#http-api-clients} -[`rabbitmqadmin` v2](./management-cli) is a command line tool -that interacts with the HTTP API. +[rabbitmqadmin v2](./management-cli) is a command-line tool that interacts with the HTTP API. For HTTP API clients in several languages, see [Developer Tools](/client-libraries/devtools). diff --git a/versioned_docs/version-4.2/management/index.md b/versioned_docs/version-4.2/management/index.md index 38598e53a..b0a7aeca8 100644 --- a/versioned_docs/version-4.2/management/index.md +++ b/versioned_docs/version-4.2/management/index.md @@ -575,10 +575,14 @@ The next sections configure these resources in the management UI. #### How OAuth 2.0 resources are presented to users -When there are more than one OAuth 2.0 resource configured in the management UI, RabbitMQ shows a drop-down list in addition to the button with the label *Click here to logon*. The drop-down list has one option per resource. The label of the option is by default the resource's id however you can ovrride it. -Resources are listed in the same order as they were configured. - -It is possible to have some resources configured with `sp_initiated` logon and others with `idp_initiated` logon. And it is also possible to disable a resource, in other words, the resource does not appear as an option in the drop-down. +When there are more than one OAuth 2.0 resource configured in the management UI, RabbitMQ shows a +drop-down menu in addition to the button with the label **Click here to logon**. The drop-down menu +has one option per resource. The label of the option is by default the resource's id however you can +override it. Resources are listed in the order that they were configured. + +It is possible to have some resources configured with `sp_initiated` logon and others with +`idp_initiated` logon. And it is also possible to disable a resource so that the resource does not +appear as an option in the drop-down menu. #### Optionally set common settings for all resources From bea8290a429d456f2904f9e68296aa5720b949d6 Mon Sep 17 00:00:00 2001 From: Marcial Rosales Date: Thu, 11 Dec 2025 11:05:57 +0100 Subject: [PATCH 5/6] Copy oauth2 section from next to 4.2 version --- docs/management/index.md | 9 +++- .../version-4.2/management/index.md | 49 ++++++++++++++++++- 2 files changed, 55 insertions(+), 3 deletions(-) diff --git a/docs/management/index.md b/docs/management/index.md index e4c4eade2..272bdcbc8 100644 --- a/docs/management/index.md +++ b/docs/management/index.md @@ -399,6 +399,7 @@ depending on your use case: - [Identity-Provider initiated logon](#idp-initiated-logon) - [Support multiple OAuth 2.0 resources](#support-multiple-resources) - [Preselect or predetermine authentication mechanism](#preselect-auth-mechanism) +- [Troubleshooting](#troubleshooting) ### Minimum configuration {#minimum-configuration} @@ -609,7 +610,11 @@ The next sections configure these resources in the management UI. When there is more than one OAuth 2.0 resource configured in the management UI, RabbitMQ shows a drop-down menu in addition to the button with the label **Click here to logon**. The drop-down menu has one option per resource. The label of the option is the resource's ID by default, but you can -override it. Resources are listed in the order in which they were configured. +override it. + +:::info +Resources are listed in the order in which they were configured. +::: You can have some resources configured with `sp_initiated` log-on and others with `idp_initiated` log-on. You can disable a resource so that the resource does not appear as an option in the @@ -701,7 +706,7 @@ mechanisms and can choose which one to use. However, in some scenarios, users mi management UI with an authentication mechanism already preselected or predefined. This allows external systems to guide users to a specific authentication flow. -To preselect or predetermine the authentication mechanism, users must send to the `/login` endpoint +To preselect or predetermine the authentication mechanism, users must be sent to the `/login` endpoint with the appropriate request parameters. The management UI then redirects them back to the home page configured according to their preferred authentication mechanism. diff --git a/versioned_docs/version-4.2/management/index.md b/versioned_docs/version-4.2/management/index.md index b0a7aeca8..fc80271ec 100644 --- a/versioned_docs/version-4.2/management/index.md +++ b/versioned_docs/version-4.2/management/index.md @@ -380,6 +380,8 @@ To configure OAuth 2.0 in the management UI you need a [minimum configuration](# * [Special attention to CSP header `connect-src`](#csp-header) * [Identity-Provider initiated logon](#idp-initiated-logon) * [Support multiple OAuth 2.0 resources](#support-multiple-resources) + * [Preselect or predetermine authentication mechanism](#preselect-auth-mechanism) + * [Troubleshooting](#troubleshooting) ### Minimum configuration {#minimum-configuration} @@ -578,7 +580,11 @@ The next sections configure these resources in the management UI. When there are more than one OAuth 2.0 resource configured in the management UI, RabbitMQ shows a drop-down menu in addition to the button with the label **Click here to logon**. The drop-down menu has one option per resource. The label of the option is by default the resource's id however you can -override it. Resources are listed in the order that they were configured. +override it. + +:::info +Resources are listed in the order in which they were configured. +::: It is possible to have some resources configured with `sp_initiated` logon and others with `idp_initiated` logon. And it is also possible to disable a resource so that the resource does not @@ -662,6 +668,47 @@ And this is the management UI with Basic Authentication activated (`management.o ![More than one OAuth 2.0 resource, with oauth_disable_basic_auth = false](./management-oauth-many-with-basic-auth.png) +### Preselect or predetermine authentication mechanism {#preselect-auth-mechanism} + +By default, when users navigate to the management UI home page they see all available authentication +mechanisms and can choose which one to use. However, in some scenarios, users might be routed to the +management UI with an authentication mechanism already preselected or predefined. This allows +external systems to guide users to a specific authentication flow. + +To preselect or predetermine the authentication mechanism, users must be sent to the `/login` endpoint +with the appropriate request parameters. The management UI then redirects them back to the home page +configured according to their preferred authentication mechanism. + +The following request parameters control the behaviour: + +#### Preselection Mode (`preferred_auth_mechanism`) + +Use the `preferred_auth_mechanism` request parameter to preselect an authentication method while +still showing all options. + +- **OAuth 2.0 resource**: `preferred_auth_mechanism=oauth2:rabbit_dev` + + - Expands the OAuth 2.0 section and collapses the basic authentication section in the home page + - Preselects the OAuth 2.0 resource server, such as `rabbit_dev` + +- **Basic authentication**: `preferred_auth_mechanism=basic` + + - Expands the basic authentication section and collapses the OAuth 2.0 section + +#### Strict Mode (`strict_auth_mechanism`) + +Use the `strict_auth_mechanism parameter` to show only the specified authentication method. Other methods are hidden. + +- **OAuth 2.0 resource only**: `/login?strict_auth_mechanism=oauth2:rabbit_dev` + + - Shows only the **Click here to login** button for the `rabbit_dev` resource server + - No other authentication options are displayed + +- **Basic authentication only**: `/login?strict_auth_mechanism=basic` + + - Shows only the basic authentication form + - No OAuth 2.0 options are displayed + ### Troubleshooting {#troubleshooting} [Troubleshooting management UI access in OAuth 2-enabled clusters](./troubleshooting-oauth2#management-ui) is a companion guide From da43b8331d45d43f91001336f96124efff8dc04c Mon Sep 17 00:00:00 2001 From: Marcial Rosales Date: Thu, 11 Dec 2025 11:16:20 +0100 Subject: [PATCH 6/6] Minor edits --- docs/management/index.md | 4 ++-- versioned_docs/version-4.2/management/index.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/management/index.md b/docs/management/index.md index 272bdcbc8..07f6ef087 100644 --- a/docs/management/index.md +++ b/docs/management/index.md @@ -717,12 +717,12 @@ The following request parameters control the behaviour: Use the `preferred_auth_mechanism` request parameter to preselect an authentication method while still showing all options. -- **OAuth 2.0 resource**: `preferred_auth_mechanism=oauth2:rabbit_dev` +- **OAuth 2.0 resource**: `/login?preferred_auth_mechanism=oauth2:rabbit_dev` - Expands the OAuth 2.0 section and collapses the basic authentication section in the home page - Preselects the OAuth 2.0 resource server, such as `rabbit_dev` -- **Basic authentication**: `preferred_auth_mechanism=basic` +- **Basic authentication**: `/login?preferred_auth_mechanism=basic` - Expands the basic authentication section and collapses the OAuth 2.0 section diff --git a/versioned_docs/version-4.2/management/index.md b/versioned_docs/version-4.2/management/index.md index fc80271ec..52aecf1ea 100644 --- a/versioned_docs/version-4.2/management/index.md +++ b/versioned_docs/version-4.2/management/index.md @@ -686,12 +686,12 @@ The following request parameters control the behaviour: Use the `preferred_auth_mechanism` request parameter to preselect an authentication method while still showing all options. -- **OAuth 2.0 resource**: `preferred_auth_mechanism=oauth2:rabbit_dev` +- **OAuth 2.0 resource**: `/login?preferred_auth_mechanism=oauth2:rabbit_dev` - Expands the OAuth 2.0 section and collapses the basic authentication section in the home page - Preselects the OAuth 2.0 resource server, such as `rabbit_dev` -- **Basic authentication**: `preferred_auth_mechanism=basic` +- **Basic authentication**: `/login?preferred_auth_mechanism=basic` - Expands the basic authentication section and collapses the OAuth 2.0 section