Hey SonarQube Users!
When operating a SonarQube instance, the supported way to serve SonarQube over HTTPS is to secure the server behind a proxy. For those who host their SonarQube server on Windows, the reverse proxy of choice is often IIS.
The intent of this guide is not to elaborate on how to set up a reverse proxy with IIS. There are more than enough IIS gurus out there and tutorials in existence to get you started.
The goal is to focus on two tricky, and relatively new requirements to have SAML authentication work correctly when serving your SonarQube server behind an IIS reverse proxy.
We are not IIS experts, and we typically aren’t keen to advise on exact reverse-proxy configuration! However, more than a few users are struggling with this. In fact, we really welcome your feedback, in the likely event that one of you knows more than we do about this. And of course, consult your IIS admins (and use a test environment) before making any changes.
We will assume a few things:
- You have a SonarQube server on a Windows server on port 9000
- IIS is already proxying port 9000 to port 443 (HTTPS) using a URL rewrite (the standard config for an IIS reverse proxy)
- SAML Authentication is otherwise perfectly configured
Since SonarQube v8.4 (and v1.2.0 of the SAML Authentication Plugin for SonarQube v7.9 LTS users), additional checks are made on the SAML response when it’s returned to the SonarQube server.
One of these checks is that the SAML response is being received at its intended address (the URL of your SonarQube instance + /oauth2/callback/saml).
Because your SonarQube server and your Identity Provider are unaware of the reverse proxy, after successfully authenticating with your identity provider and being redirected to SonarQube, you can end up with a frustrating error message that looks like this:
The response was received at http://localhost:9000/oauth2/callback/saml instead of https://sonar.mydomain.com/oauth2/callback/saml
Two configuration changes should be done to overcome this.
First, your Identity Provider must be aware it should redirect to an HTTPS URL rather than HTTP. This can be accomplished by adding the server variable HTTP_X_FORWARDED_PROTO set to https in your Reverse Proxy Inbound Rule
Note that a Server Variable must first be included in Allowed Sever Variables or you may face a 500 error.
In IIS, the variables that set standard HTTP headers are prefixed with
HTTP
And finally, you need to be sure that host headers are preserved. This is set at the IIS server level, by executing the following command.
%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/proxy -preserveHostHeader:true /commit:apphost
And there you go! You should no longer be told that your SAML response has landed in the wrong place.
In some cases, some users who integrate IIS and SAML will encounter this error when logging in:
This probably occurs due to the Identity Provider (IdP) redirects back to SonarQube, but the rewrite of the host is reversed!
To correct this error:
- Uncheck the box
Reverse rewrite host in response headersfrom “Application Request Routing” > “Server proxy settings” set at the server level in IIS
- Apply the change
- Restart IIS
Do you have feedback on this post?
Please raise a new topic in Get Help > SonarQube