Skip to content

Commit

Permalink
Merge branch 'use-docusaurus-style-in-oauth2-docs'
Browse files Browse the repository at this point in the history
  • Loading branch information
michaelklishin committed Sep 10, 2024
2 parents a861962 + 3df0636 commit 69344de
Show file tree
Hide file tree
Showing 6 changed files with 99 additions and 61 deletions.
21 changes: 17 additions & 4 deletions docs/oauth2-examples-entra-id/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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:

Expand Down Expand Up @@ -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.

Expand Down
3 changes: 2 additions & 1 deletion docs/oauth2-examples-okta.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
57 changes: 31 additions & 26 deletions docs/oauth2.md
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down
19 changes: 16 additions & 3 deletions versioned_docs/version-3.13/oauth2-examples-entra-id/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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:

Expand Down Expand Up @@ -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.

Expand Down
3 changes: 2 additions & 1 deletion versioned_docs/version-3.13/oauth2-examples-okta.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
57 changes: 31 additions & 26 deletions versioned_docs/version-3.13/oauth2.md
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down

0 comments on commit 69344de

Please sign in to comment.