Merge pull request #2163 from rabbitmq/support-forward-proxy-in-oauth2

Support forward proxy in oauth2

Author: RichardJJG

docs/oauth2-examples-forward-proxy.md

@@ -0,0 +1,121 @@
+---
+title: Use an explicit forward proxy and Keycloak as OAuth 2.0 server
+displayed_sidebar: docsSidebar
+---
+<!--
+Copyright (c) 2005-2024 Broadcom. All Rights Reserved. The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries.
+
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the under the Apache License,
+Version 2.0 (the "License”); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Use an explicit forward proxy and Keycloak as OAuth 2.0 server
+
+:::warning
+To run this example you need to use the commercial [Tanzu RabbitMQ docker image](https://techdocs.broadcom.com/us/en/vmware-tanzu/data-solutions/tanzu-rabbitmq-oci/4-0/tanzu-rabbitmq-oci-image/overview.html). Support for **forward proxy** is a commercial feature.
+:::
+
+This guide explains how to set up OAuth 2.0 for RabbitMQ to access the Authorization Server via an explicit forward proxy. 
+
+* Access the RabbitMQ Management UI using a browser through OAuth2 Proxy
+
+```plain
+                    [ Keycloak ]  
+                        /|\  
+                         |   
+     2.http request (*)  |                                            [ RabbitMQ ]
+                [ forward-proxy ]      <----1. http request (*)---    [  http    ]
+            
+```
+
+RabbitMQ establishes an HTTP connection with Keycloak via the forward-proxy in any of 
+these situations:
+
+- You have configured `auth_oauth2.issuer` so that RabbitMQ downloads the OpenID configuration via the OpenID discovery endpoint.
+- You have configured `auth_oauth2.issuer` or `auth_oauth2.jwks_url` so that RabbitMQ downloads the tokens' signing keys. 
+
+## Prerequisites for Using OAuth 2 vith a forward proxy
+
+* Docker
+* make
+* A local clone of a [GitHub repository](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/next) for branch `next` that contains all the configuration files and scripts used on this example.
+* The following entries in your /etc/hosts file. Without these entries you will get DNS errors in the browser. 
+```
+localhost keycloak rabbitmq forward-proxy
+```
+
+:::info
+`make start-keycloak` will
+generate the TLS certificate and private keys as necessary. These certificates have an expiration date.
+
+In you see any error messages that hint at expired or invalid certificates, stop Keycloak, run `make clean-certs` to regenerate the certificates and private keys,
+and then restart Keycloak and the proxy.
+:::
+
+## Deploy Keycloak
+
+Deploy keycloak on its own network called `keycloak_net` by running:
+
+```bash
+PROVIDER_NETWORK=keycloak_net make start-keycloak
+```
+ 
+To access Keycloak Management UI, go to https://keycloak:8443/ and enter `admin` as the username and password.
+
+There is a dedicated **Keycloak realm** called `Test` configured as follows:
+
+* [rsa](https://keycloak:8443/admin/master/console/#/realms/test/keys) signing-key
+* [rsa provider]https://keycloak:8443/admin/master/console/#/realms/test/keys/providers)
+* `rabbitmq-proxy-client` client
+
+## Start Forward Proxy
+
+Deploy and start the forward-proxy in two networks, `keycloak_net` and `rabbitmq_net`, by running:
+
+```bash
+PROVIDER_NETWORK=keycloak_net make start-forward-proxy
+```
+
+The forward proxy is configured by using [httpd.conf](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/next/conf/forward-proxy/httpd/httpd.conf). This type of configuration inserts the access token into the HTTP **Authorization** header.
+
+
+## Start RabbitMQ
+
+Deploy RabbitMQ in its own network `rabbitmq_net` and start it by running:
+
+```
+export IMAGE=<Tanzu RabbitMQ OCI image name>
+export IMAGE_TAG=<Tanzu RabbitMQ OCI image tag>
+MODE=forward-proxy OAUTH_PROVIDER=keycloak make start-rabbitmq
+```
+
+## Access [management UI](./management/)
+
+Go to https://rabbitmq:15671/, proceed to login, and enter the credentials
+`rabbit_admin` as the username and `rabbit_admin` as the password when Keycloak prompts you. 
+You will be redirected back to RabbitMQ management UI.
+
+The management UI running in the browser goes straight to keycloak. 
+In other words, it does not go via the forward-proxy. If you want the management UI to
+go via the forward-proxy, you must configure the browser. That is beyond 
+the scope of this example.
+
+However, in order to validate the token the management UI received from keycloak, RabbitMQ has to connect to keycloak via the forward-proxy. This is necessary in order to download the signing keys and to download the OpenID configuration if you only configured the `issuer` URL.
+
+## Access Management API
+
+To access the management API run the following command. It uses the client [mgt_api_client](https://keycloak:8443/admin/master/console/#/test/clients/c5be3c24-0c88-4672-a77a-79002fcc9a9d/settings), which has the scope [rabbitmq.tag:administrator](https://keycloak:8443/admin/master/console/#/test/client-scopes/f6e6dd62-22bf-4421-910e-e6070908764c/settings).
+
+```bash
+make curl-keycloak url=https://localhost:15671/api/overview client_id=mgt_api_client secret=LWOuYqJ8gjKg3D2U8CJZDuID3KiRZVDa realm=test
+```

docs/oauth2-examples-keycloak.md

@@ -74,7 +74,7 @@ RabbitMQ is deployed with TLS enabled and Keycloak is configured with the corres
 To access the management api run the following command. It uses the client [mgt_api_client](https://keycloak:8443/admin/master/console/#/test/clients/c5be3c24-0c88-4672-a77a-79002fcc9a9d/settings) which has the scope [rabbitmq.tag:administrator](https://keycloak:8443/admin/master/console/#/test/client-scopes/f6e6dd62-22bf-4421-910e-e6070908764c/settings).
 
 ```bash
-make curl-keycloak url=https://localhost:15671/api/overview client_id=mgt_api_client secret=LWOuYqJ8gjKg3D2U8CJZDuID3KiRZVDa
+make curl-keycloak url=https://localhost:15671/api/overview client_id=mgt_api_client secret=LWOuYqJ8gjKg3D2U8CJZDuID3KiRZVDa realm=test
 ```
 
 ## Application authentication and authorization with PerfTest

docs/oauth2-examples/index.md

@@ -70,6 +70,10 @@ The guide is accompanied by [a public GitHub repository](https://github.com/rabb
  * [Google](./oauth2-examples-google)  **NOT SUPPORTED**
  * [Multiple OAuth 2.0 servers and/or audiences](./oauth2-examples-multiresource)
 
+### Examples for Tanzu RabbitMQ (commercial-only feature)
+
+ * [Forward proxy](./oauth2-examples-forward-proxy)
+
 ## Prerequisites Used by the Examples in This Guide {#prerequisites}
 
  * Docker must be installed

docs/oauth2.md

@@ -159,6 +159,7 @@ In chronological order, here is the sequence of events that occur when a client
 | `auth_oauth2.https.fail_if_no_peer_cert`   | Used together with `auth_oauth2.https.peer_verification = verify_peer`. When set to `true`, TLS connection will be rejected if the client fails to provide a certificate. The default value is `false`.
 | `auth_oauth2.https.hostname_verification`  | Enable wildcard-aware hostname verification for key server. Available values: `wildcard`, `none`. The default value is `none`.
 | `auth_oauth2.https.crl_check`              | [Perform CRL verification](https://www.erlang.org/doc/man/ssl#type-crl_check) (Certificate Revocation List) verification. Default value is false.
+| `auth_oauth2.proxy`                        | Configures explicit [forward proxy](https://techdocs.broadcom.com/us/en/vmware-tanzu/data-solutions/tanzu-rabbitmq-oci/4-0/tanzu-rabbitmq-oci-image/overview.html) used to connect to the `auth_oauth2.issuer` URL. **This is a commercial-only feature**. More information on how to use it can be found on [this example](./oauth2-examples-forward-proxy).
 | `auth_oauth2.algorithms`                   | Restrict [the usable algorithms](https://github.com/potatosalad/erlang-jose#algorithm-support).
 | `auth_oauth2.verify_aud`                   | Whether to verify the [token's `aud`](#token-validation) field or not. The default value is `true`.
 | `auth_oauth2.resource_servers`             | [Multiple OAuth 2.0 resources configuration](#multiple-resource-servers-configuration).
@@ -277,7 +278,6 @@ auth_oauth2.algorithms.1 = HS256
 auth_oauth2.algorithms.2 = RS256
 ```
 
-
 ## Multiple Resource Servers Сonfiguration {#multiple-resource-servers-configuration}
 
 Each `auth_oauth2.resource_servers.<id/index>.` entry has the following variables shown in the table below. Except for the variables `id` and `oauth_provider_id`, if a resource does not configure a variable, RabbitMQ uses the variable configured at the root level. For instance, if the resource `auth_oauth2.resource_servers.prod` does not configure `preferred_username_claims` variable, RabbitMQ uses the value configured in `auth_oauth2.preferred_username_claims` for the resource `prod`.
@@ -322,8 +322,9 @@ Each `auth_oauth2.oauth_providers.{id/index}` entry has the following sub-keys.
 | `https.depth`                | The maximum number of non-self-issued intermediate certificates that may follow the peer certificate in a valid [certification path](ssl#peer-verification-depth). The default value is 10.
 | `https.verify`               | Configures [peer verification](ssl#peer-verification). Available values: `verify_none`, `verify_peer`. The default value is `verify_peer` if there are trusted CA installed in the OS or `auth_oauth2.https.cacertfile` is set.
 | `https.fail_if_no_peer_cert` | Used together with `auth_oauth2.https.peer_verification = verify_peer`. When set to `true`, TLS connection will be rejected if the client fails to provide a certificate. The default value is `false`.
-| `https.hostname_verification` | Enable wildcard-aware hostname verification for key server. Available values: `wildcard`, `none`. The default value is `none`.
-| `https.crl_check`              | [Perform CRL verification](https://www.erlang.org/doc/man/ssl#type-crl_check) (Certificate Revocation List) verification. Default value is false.
+| `https.hostname_verification`| Enable wildcard-aware hostname verification for key server. Available values: `wildcard`, `none`. The default value is `none`.
+| `https.crl_check`            | [Perform CRL verification](https://www.erlang.org/doc/man/ssl#type-crl_check) (Certificate Revocation List) verification. Default value is false.
+| `auth_oauth2.proxy`          | Configures explicit [forward proxy](https://techdocs.broadcom.com/us/en/vmware-tanzu/data-solutions/tanzu-rabbitmq-oci/4-0/tanzu-rabbitmq-oci-image/overview.html) used to connect to the `issuer` URL. **This is a commercial-only feature**. More information on how to use it can be found on [this example](./oauth2-examples-forward-proxy).
 | `signing_keys`               | Local filesystem paths to the [signing key files](#signing-key-files). The files must exist and be readable.
 | `default_key`                | ID of the default signing key.
 | `algorithms`                 | Used to restrict [the list of enabled algorithms](https://github.com/potatosalad/erlang-jose#algorithm-support).