Version: Next

Troubleshooting OAuth 2

Overview

This guide covers the most common errors encountered using OAuth 2.0 and management plugin and how to diagnose them.

Troubleshooting OAuth 2 in the management UI

OpenId Discovery endpoint not reachable

Steps to reproduce the issue

Open the root URL of the management UI in the browser, not authenticated yet. Rather than getting the button "Click here to login" you see the following error message:

OAuth resource [rabbitmq] not available. OpenId Discovery endpoint https://<the_issuer_url>/.well-known/openid-configuration not reachable

Troubleshoot the issue

These are the most common reasons for this issue:

The endpoint is either down or is not reachable (e.g. there is a firewall which blocks access)
The endpoint has a TLS certificate not trusted by the browser
The browser is blocking access due to CORS policy

The quickest way to identity the root cause is by opening the browser's javascript console and searching for net::ERR_. These are the two most likely errors:

net::ERR_CONNECTION_REFUSED: the endpoint is down or is not reachable
net::ERR_CERT_AUTHORITY_INVALID: the endpoint's TLS certificate is not trusted by the browser. To trust the certificate, click on the URL in the error message and follow the prompt

If there are no errors found for net::ERR search instead for CORS. An error similar to the one shown below means that the browser is blocking the response returned by the endpoint and therefore it is not being delivered it to the management UI. This is due to the CORS policy. Contact the administrator of the Identity Provider to add the management UI's URL to the list of allowed origins.

Access to fetch at 'https://<the_issuer_url>>/.well-known/openid-configuration' from origin
'<rabbitmq_url_to_management_ui>' has been blocked by CORS policy`.

OpenId Discovery endpoint not compliant

Steps to reproduce the issue

Open the root url of the management UI in the browser, not authenticated yet. Rather than getting the button "Click here to login" you see the following error message:

OAuth resource [rabbitmq] not available. OpenId Discovery endpoint https://<the_issuer_url>/.well-known/openid-configuration not compliant

Troubleshoot the issue

This error means that the endpoint does not return a JSON payload which matches with the OpenId Connect Discovery Configuration format.

There are several the possible causes:

The payload returned by the endpoint is not compliant because it is empty or it is missing some critical information. To identify the root cause, you open the browser's javascript console and search for one of these possible error messages:

Payload does not contain openid configuration This error occurs when the payload is empty or it is not a JSON payload
Missing authorization_endpoint This error occurs when the JSON attribute authorization_endpoint is missing
Missing token_endpoint This error occurs when the JSON attribute token_endpoint is missing
Missing jwks_uri This error occurs when the JSON attribute jwks_uri is missing

The url is incorrect. Contact the maintainers of the Identity Provider to get the correct URL for the OpenID Connect discovery endpoint

Not authorized

Steps to reproduce the issue

Open the root url of the management UI in the browser, click on the buttoh "Click here to logon" and enter the credentials requested by your Identity Provider. You are redirected back to the management UI with the following error:

Not authorized

Troubleshoot the issue

This issue occurs when the token does not have enough scopes or permissions to access the management UI. You need at least one of these scopes or the equivalent scope:

rabbitmq.tag:administrator
rabbitmq.tag:management
rabbitmq.tag:monitoring
rabbitmq.tag:policymaker

Follow these steps to find out which scopes or permissions are carried in the token:

Open your browwser's developer tool (e.g. in Chrome or Firefox, right-click on the page and click on Inspect menu option)
Go to the tab Application
Select the option Storage > Local Storage in the left panel
Click on the tree option which matches the URL of the management UI
Select the Key rabbitmq.credentials in the right panel
Copy its value
Go to the url https://jwt.io
Paste the value into the text field Encoded
Look at the payload's text field Decoded
Search for the token attribute scope in the tokens' payload or for the value configured in auth_oauth2.additional_scopes_key, if any.
Once you found the appropriate token's scope attribute, find within the attribute's value any of the scopes listed above. If auth_oauth2.scope_prefix is used, it must be taken into account: the scopes will be named like myprefix_tag:administrator. If scope aliases are used, find the scope alias that maps to one of the scopes listed above

OpenId Discovery Endpoint not Reachable Due to a Certificate SAN (or CN) and Target Hostname Mismatch

This issue is not necessarily specific to the management UI, it may also occur when an application is authenticating via one of the messaging protocols. It occurs when RabbitMQ has to download the OpenID Connect configuration via the URL configured in auth_oauth2.issuer and the certificate used by the issuer uses a wildcard certificate. This means that the certificate's SAN (Subject Alternative Name) or CN certificate attributes does not match the issuer's domain name exactly. This is a very common situation in SaaS deployments.

Steps to reproduce the issue

Open the root URL of the management UI in the browser.
Click on "Click here to login".
Enter your credentials.
You are redirected back to RabbitMQ but with an error "No Authorized"

Troubleshoot the issue

Access RabbitMQ logs
Look up for {bad_cert,hostname_check_failed}
Look for an entry it says that RabbitMQ tried to contact the url found in auth_oauth2.issuer and the issuer presented a wildcard certificate
To fix this issue, add the following line to your RabbitMQ configuration auth_oauth2.https.hostname_verification = wildcard. Or auth_oauth2.oauth_providers.<my_oauth_provider_name>.https.hostname_verification = wildcard if you are using multiple OAuth providers

Overview​