Improve Azure AD/Entra Documentation

[iinuwa]

Is your feature request related to a problem? Please describe.

Thanks for a great project!

Getting RabbitMQ set up with Azure in the way that I'd like took a lot of work to understand and get working correctly. I ran into a few issues I ran into (on RabbitMQ 3.13.7), that I think could have been avoided with documentation changes, so I thought I'd share. (I created PRs for some other doc changes, but these may be more extensive/intentional, so I'm creating an issue instead.

Describe the solution you'd like

• The Azure AD sample uses the advanced.config, which is hard for me to generate via Ansible/Jinja templates. I'd like to be able to use the modern config format. I was able to accomplish this with the modern config format, so I think this is just a documentation issue.
• The sample references v2.0 in a few places (for the OIdC metadata URL and JWKS URI), but silently uses v1 for the issuer/authorize endpoint. This is actually required for management login, since the setup will not work with the v2.0 authorize endpoint, as RabbitMQ adds the resource parameter to the authorize URL, which will throw AADSTS901002: The 'resource' request parameter isn't supported. on the v2.0 authorize endpoint. It would be best to make all of the URLs point to the v1 endpoints (https://login.microsoftonline.com/{tenant-id} for the issuer and https://login.microsoftonline.com/common/discovery/keys for the JWKS URI), and add an explicit warning that says that v1 endpoints are required, mentioning the above Azure error code so that it can be easily searched.
• A note shuold be added saying that the resource server ID must be the same as the client_id, otherwise, this doesn't work. (Else, the admin must set the identifierUris property in the manifest to whatever value they want to set the resource_server_id to.)
• Microsoft Azure AD has been renamed (again) to Microsoft Entra, so it may be useful to reference that somewhere in the document for searching online.
• This is not an Azure AD config problem per se, but I had trouble setting the scope_prefix to an empty string auth_oauth2.scope_prefix = ""; it didn't seem to recognize my claims when I set it that way. I decided to set it to rabbitmq. so that I could use the same values across multiple different Azure AD applications without having to inject the client_id (which does not exist until the Azure AD application is created.) (Similar problem to Enable use different identifier of role id and resource id in OAuth flow rabbitmq-server#7861.) I guess this isn't really actionable without more data, but just thought I'd mention it anyway.

Describe alternatives you've considered

No response

Additional context

No response

[michaelklishin]

Two specific improvements were contributed in #2040 #2041.

[michaelklishin]

@iinuwa thank you for taking the time to contribute/provide feedback. You are welcome to continue with the specific changes you have in mind. If we have to edit your changes, that's fine with the members of the core team.

Note that you must update both the 4.0 version under docs (available at /docs/next/{guide} when you run a local copy with npm start) and the 3.13 (live) one under versioned_docs (available at /docs/{guide}).

Or I can do a couple of these changes where I understand both the intent and where in the docs the changes should be made.

It's a good question on whether we can use v1 API URLs for long and what kind of changes would be necessary. @MarcialRosales would know better.

[MarcialRosales]

@iinuwa thank you for providing your feedback and for making contributions. Since the first edition of these instructions on how to configure RabbitMq with Azure/Entra, RabbitMQ has introduced a few changes which makes OAuth2's configuration simpler. You only need to configure the issuer url and if Authorization server is OpenID compliant -which Azure is- RabbitMQ discovers all the remaining urls such as the jwks url. I am updating the docs and the sample configuration (https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/main/conf/azure/rabbitmq.config). However, and as it is explained in our Azure example, if you configured a signing key for your application/tenant, you will have to set the jwks_url until this feature request is completed.

You will not need to configure oauth_provider_url in the management plugin if it matches with the oauth2.issuer url, which I believe they do match in Azure. This means you will only need to configure one single url, the issuer. And here you can choose any url , or any api version v1 or v2. RabbitMQ does not really have any opinion there. But I will make sure the docs refer to just one version.

[iinuwa]

Thanks for looking into this!

And here you can choose any url , or any api version v1 or v2. RabbitMQ does not really have any opinion there.

Azure AD has an opinion here, unfortunately, as it does not accept the resource parameter on the v2.0 authorize endpoint. (The content of the v1 and v2 JWKS URIs are the same though, so they're interchangeable for now.) So I think that needs to be called out.

(Regarding deprecation of the v1 endpoints: Microsoft has not announced any formal deprecation, though support sites have been ever since their original libraries for interacting with OAuth2 were deprecated back in Dec 2022. Whenever Microsoft does announce deprecation, we'll need to add a parameter to not set the resource parameter on the redirect to the authorize endpoint in order to remain compatible with Azure.)

[MarcialRosales]

You are right that we need to do something about the resource parameter . I will make sure it is configurable whether to include it or not. I do recall adding it when the majority -if not all- the oauth providers we tested RabbitMQ with did support this request parameter.
But when I meant that RabbitMQ does not have any opinion on the api version azure uses , I was really referring to the actual url itself .. Putting aside the resource request parameter, RabbitMQ does not really care whether the issuer url or jwks_url uses v1 or v2. For RabbitMQ is just a URL.

[iinuwa]

But when I meant that RabbitMQ does not have any opinion on the api version azure uses , I was really referring to the actual url itself .. Putting aside the resource request parameter, RabbitMQ does not really care whether the issuer url or jwks_url uses v1 or v2. For RabbitMQ is just a URL.

Ah, I see; yes, that makes sense.

I will make sure it is configurable whether to include it or not. I do recall adding it when the majority -if not all- the oauth providers we tested RabbitMQ with did support this request parameter.

Yeah, Microsoft is throwing around their weight by adding slight tweaks to the OAuth spec that makes just different enough not to work for many generic client implementations. Unfortunately, they're big enough that clients just have to workaround it. Thanks again for looking into it! I'm happy to test the resource parameter config whenever you get around to it.