Some OAuth 2-related edits #2050

rabbitmq · Sep 10, 2024 · 3df0636 · 3df0636
1 parent 77848e1
commit 3df0636
Show file tree

Hide file tree

Showing 6 changed files with 73 additions and 59 deletions.
diff --git a/docs/oauth2-examples-entra-id/index.md b/docs/oauth2-examples-entra-id/index.md
@@ -75,7 +75,7 @@ When using **Entra ID as OAuth 2.0 server**, your client app (in our case Rabbit
     Note the value of the `jwks_uri` key (ex: `https://login.microsoftonline.com/{TENANT_ID}/discovery/v2.0/keys`), as you will also need it later to configure the `rabbitmq_auth_backend_oauth2` on RabbitMQ side.
 
     ![Entra ID JWKS URI](./entra-id-jwks-uri.png)
-8. If the **Endpoints** tab is not visible,     
+8. If the **Endpoints** tab is not visible,
 
 
 ## Create OAuth 2.0 roles for your app
@@ -84,7 +84,7 @@ App roles are defined by using the [Entra ID portal](https://portal.azure.com) d
 
 :::info
 
-More details about roles in Entra ID are available [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-add-app-roles-in-azure-ad-apps).
+To learn more about roles in Entra ID, see [Entra ID documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-add-app-roles-in-azure-ad-apps)
 
 :::
 
@@ -100,7 +100,8 @@ More details about roles in Entra ID are available [here](https://docs.microsoft
 
 :::info
 
-More details about how permissions are managed on RabbitMQ when using OAuth 2.0 are available [here](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial#about-permissions).
+To learn more about how permissions are managed when RabbitMQ is used together with OAuth 2.0,
+see [this portion of the OAuth 2 tutorial](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial#about-permissions)
 
 :::
 

diff --git a/docs/oauth2-examples-okta.md b/docs/oauth2-examples-okta.md
@@ -38,7 +38,8 @@ contains all the configuration files and scripts used on this example
 
 When using **Okta as OAuth 2.0 server**, your client app (in our case RabbitMQ) needs a way to trust the security tokens issued to it by the **Okta OIDC Sign-In Widget**.
 
-The first step in establishing that trust is by **creating your app** with the identity platform in Okta. More details about App registration in Okta are available [here](https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_OIDC.htm).
+The first step in establishing that trust is by **creating your app** with the identity platform in Okta. To learn more about App registration in Okta,
+please refer to [Okta documentation](https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_OIDC.htm).
 
 Once you have logged onto your account in [Okta](https://www.okta.com), follow below steps:
 

diff --git a/docs/oauth2.md b/docs/oauth2.md
@@ -26,32 +26,37 @@ This [RabbitMQ authentication/authorisation backend](./access-control) plugin le
 
 There's also a companion [troubleshooting guide for OAuth 2-specific problems](./troubleshooting-oauth2).
 
-This guide covers
-
- * [How it works](#how-it-works)
-    * [Prerequisites](#prerequisites)
-    * [Authorization Flow](#authorization-flow)
-    * [Variables configurable in rabbitmq.conf](#variables-configurable)
-    * [Token validation](#token-validation)
-    * [Token expiration and refresh](#token-expiration)
-    * [Scope-to-Permission translation](#scope-translation)
-    * [Topic Exchange scopes](#topic-exchange-scopes)
-    * [Scope and tags](#scope-and-tags)
-
- * [Basic usage](#basic-usage)
-    * [Configure OAuth 2.0 provider's issuer](#configure-issuer)
-    * [Configure signing keys](#configure-signing-keys)
-    * [Use a different token field for the scope](#use-different-token-field)
-    * [Preferred username claims](#preferred-username-claims)
-    * [Rich Authorization Request](#rich-authorization-request)
-
- * [Advanced usage](#advanced-usage)    
-    * [Use default OAuth 2.0 provider](#use-oauth-provider)
-    * [Configure OAuth 2.0 provider's end_session_endpoint](#configure-end-session-endpoint)
-    * [Configure multiple resource servers](#multiple-resource-servers)
-    * [Configure multiple OAuth 2.0 providers](#multiple-oauth-providers)
-
- * [Examples](#examples)
+## Table of Contents
+
+### [How it works](#how-it-works)
+
+* [Prerequisites](#prerequisites)
+* [Authorization Flow](#authorization-flow)
+* [Variables configurable in rabbitmq.conf](#variables-configurable)
+* [Token validation](#token-validation)
+* [Token expiration and refresh](#token-expiration)
+* [Scope-to-Permission translation](#scope-translation)
+* [Topic Exchange scopes](#topic-exchange-scopes)
+* [Scope and tags](#scope-and-tags)
+
+### [Basic usage](#basic-usage)
+
+* [Configure OAuth 2.0 provider's issuer](#configure-issuer)
+* [Configure signing keys](#configure-signing-keys)
+* [Use a different token field for the scope](#use-different-token-field)
+* [Preferred username claims](#preferred-username-claims)
+* [Rich Authorization Request](#rich-authorization-request)
+
+### [Advanced usage](#advanced-usage)
+
+* [Use default OAuth 2.0 provider](#use-oauth-provider)
+* [Configure OAuth 2.0 provider's end_session_endpoint](#configure-end-session-endpoint)
+* [Configure multiple resource servers](#multiple-resource-servers)
+* [Configure multiple OAuth 2.0 providers](#multiple-oauth-providers)
+
+### Examples for Specific Identity Providers
+
+ * How to [set up RabbitMQ with OAuth 2: examples](#examples)
 
 
 ## How it works {#how-it-works}

diff --git a/versioned_docs/version-3.13/oauth2-examples-entra-id/index.md b/versioned_docs/version-3.13/oauth2-examples-entra-id/index.md
@@ -84,7 +84,7 @@ App roles are defined by using the [Entra ID portal](https://portal.azure.com) d
 
 :::info
 
-More details about roles in Entra ID are available [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-add-app-roles-in-azure-ad-apps).
+To learn more about roles in Entra ID, see [Entra ID documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-add-app-roles-in-azure-ad-apps)
 
 :::
 
@@ -100,7 +100,8 @@ More details about roles in Entra ID are available [here](https://docs.microsoft
 
 :::info
 
-More details about how permissions are managed on RabbitMQ when using OAuth 2.0 are available [here](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial#about-permissions).
+To learn more about how permissions are managed when RabbitMQ is used together with OAuth 2.0,
+see [this portion of the OAuth 2 tutorial](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial#about-permissions)
 
 :::
 

diff --git a/versioned_docs/version-3.13/oauth2-examples-okta.md b/versioned_docs/version-3.13/oauth2-examples-okta.md
@@ -38,7 +38,8 @@ contains all the configuration files and scripts used on this example
 
 When using **Okta as OAuth 2.0 server**, your client app (in our case RabbitMQ) needs a way to trust the security tokens issued to it by the **Okta OIDC Sign-In Widget**.
 
-The first step in establishing that trust is by **creating your app** with the identity platform in Okta. More details about App registration in Okta are available [here](https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_OIDC.htm).
+The first step in establishing that trust is by **creating your app** with the identity platform in Okta. To learn more about App registration in Okta,
+please refer to [Okta documentation](https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_OIDC.htm).
 
 Once you have logged onto your account in [Okta](https://www.okta.com), follow below steps:
 

diff --git a/versioned_docs/version-3.13/oauth2.md b/versioned_docs/version-3.13/oauth2.md
@@ -26,32 +26,37 @@ This [RabbitMQ authentication/authorisation backend](./access-control) plugin le
 
 There's also a companion [troubleshooting guide for OAuth 2-specific problems](./troubleshooting-oauth2).
 
-This guide covers
-
- * [How it works](#how-it-works)
-    * [Prerequisites](#prerequisites)
-    * [Authorization Flow](#authorization-flow)
-    * [Variables configurable in rabbitmq.conf](#variables-configurable)
-    * [Token validation](#token-validation)
-    * [Token expiration and refresh](#token-expiration)
-    * [Scope-to-Permission translation](#scope-translation)
-    * [Topic Exchange scopes](#topic-exchange-scopes)
-    * [Scope and tags](#scope-and-tags)
-
- * [Basic usage](#basic-usage)
-    * [Configure OAuth 2.0 provider's issuer](#configure-issuer)
-    * [Configure signing keys](#configure-signing-keys)
-    * [Use a different token field for the scope](#use-different-token-field)
-    * [Preferred username claims](#preferred-username-claims)
-    * [Rich Authorization Request](#rich-authorization-request)
-
- * [Advanced usage](#advanced-usage)    
-    * [Use default OAuth 2.0 provider](#use-oauth-provider)
-    * [Configure OAuth 2.0 provider's end_session_endpoint](#configure-end-session-endpoint)
-    * [Configure multiple resource servers](#multiple-resource-servers)
-    * [Configure multiple OAuth 2.0 providers](#multiple-oauth-providers)
-
- * [Examples](#examples)
+## Table of Contents
+
+### [How it works](#how-it-works)
+
+* [Prerequisites](#prerequisites)
+* [Authorization Flow](#authorization-flow)
+* [Variables configurable in rabbitmq.conf](#variables-configurable)
+* [Token validation](#token-validation)
+* [Token expiration and refresh](#token-expiration)
+* [Scope-to-Permission translation](#scope-translation)
+* [Topic Exchange scopes](#topic-exchange-scopes)
+* [Scope and tags](#scope-and-tags)
+
+### [Basic usage](#basic-usage)
+
+* [Configure OAuth 2.0 provider's issuer](#configure-issuer)
+* [Configure signing keys](#configure-signing-keys)
+* [Use a different token field for the scope](#use-different-token-field)
+* [Preferred username claims](#preferred-username-claims)
+* [Rich Authorization Request](#rich-authorization-request)
+
+### [Advanced usage](#advanced-usage)
+
+* [Use default OAuth 2.0 provider](#use-oauth-provider)
+* [Configure OAuth 2.0 provider's end_session_endpoint](#configure-end-session-endpoint)
+* [Configure multiple resource servers](#multiple-resource-servers)
+* [Configure multiple OAuth 2.0 providers](#multiple-oauth-providers)
+
+### Examples for Specific Identity Providers
+
+ * How to [set up RabbitMQ with OAuth 2: examples](#examples)
 
 
 ## How it works {#how-it-works}