Merge branch 'use-docusaurus-style-in-oauth2-docs'

michaelklishin · michaelklishin · commit 69344de95135 · 2024-09-09T22:13:52.000-04:00
diff --git a/docs/oauth2-examples-entra-id/index.md b/docs/oauth2-examples-entra-id/index.md
@@ -75,14 +75,18 @@ 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
 
 App roles are defined by using the [Entra ID portal](https://portal.azure.com) during the app registration process. When a user signs in to your application, Entra ID emits a `roles` claim for each role that the user or service principal has been granted (you will have a look at it at the end of this tutorial).
 
-<g-emoji class="g-emoji" alias="blue_book" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/1f4d8.png">📘</g-emoji> 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).
+:::info
+
+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)
+
+:::
 
 1. Still in [Entra ID Portal](https://portal.azure.com), go back to **Entra ID** home page.
 
@@ -94,7 +98,12 @@ App roles are defined by using the [Entra ID portal](https://portal.azure.com) d
 
 2. Then, click on **Create App Role** to create an OAuth 2.0 role that will be used to give access to the RabbitMQ Management UI.
 
-    <g-emoji class="g-emoji" alias="blue_book" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/1f4d8.png">📘</g-emoji> 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).
+:::info
+
+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)
+
+:::
 
 3. On the right menu that has just opened, provide the requested information:
 
@@ -141,7 +150,11 @@ Now that some roles have been created for your application, you still need to as
 
 7. Back to the **Add assignment** pane, below **Select a Role**, click on *None Selected* and, on the **Select a role** pane that has just opened on the right, search and select the role you want to assign to the selected users.
 
-    <g-emoji class="g-emoji" alias="bulb" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/1f4a1.png">💡</g-emoji> If only one role is available for your application, it would be automatically selected and greyed by default.
+    :::tip
+
+    If only one role is available for your application, it would be automatically selected and greyed by default.
+
+    :::
 
 8. Choose a role (only a single role can be selected at a time), click on the **Select** button, and click on the **Assign** button to finalize the assignment of users and groups to the app.
 
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
@@ -82,7 +82,11 @@ When using **Entra ID as OAuth 2.0 server**, your client app (in our case Rabbit
 
 App roles are defined by using the [Entra ID portal](https://portal.azure.com) during the app registration process. When a user signs in to your application, Entra ID emits a `roles` claim for each role that the user or service principal has been granted (you will have a look at it at the end of this tutorial).
 
-<g-emoji class="g-emoji" alias="blue_book" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/1f4d8.png">📘</g-emoji> 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).
+:::info
+
+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)
+
+:::
 
 1. Still in [Entra ID Portal](https://portal.azure.com), go back to **Entra ID** home page.
 
@@ -94,7 +98,12 @@ App roles are defined by using the [Entra ID portal](https://portal.azure.com) d
 
 2. Then, click on **Create App Role** to create an OAuth 2.0 role that will be used to give access to the RabbitMQ Management UI.
 
-    <g-emoji class="g-emoji" alias="blue_book" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/1f4d8.png">📘</g-emoji> 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).
+:::info
+
+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)
+
+:::
 
 3. On the right menu that has just opened, provide the requested information:
 
@@ -141,7 +150,11 @@ Now that some roles have been created for your application, you still need to as
 
 7. Back to the **Add assignment** pane, below **Select a Role**, click on *None Selected* and, on the **Select a role** pane that has just opened on the right, search and select the role you want to assign to the selected users.
 
-    <g-emoji class="g-emoji" alias="bulb" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/1f4a1.png">💡</g-emoji> If only one role is available for your application, it would be automatically selected and greyed by default.
+    :::tip
+
+    If only one role is available for your application, it would be automatically selected and greyed by default.
+
+    :::
 
 8. Choose a role (only a single role can be selected at a time), click on the **Select** button, and click on the **Assign** button to finalize the assignment of users and groups to the app.
 
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}
