SAML, LDAP, OIDC/SSO, Proxies, TLS, and Network Security: Core Concepts and Mental Model

1. The practical problem: SSO, TLS, and authorization fail in different places

Chapter 21 established the identity-to-permission model: authentication tells SonarQube who an actor is, while groups and permissions decide what that actor may do. Chapter 22 adds the network and delegated-authentication boundaries around that model.

When an SSO login fails, the cause can be a browser-to-proxy TLS problem, a wrong external base URL, a missing forwarded header, an IdP callback mismatch, an invalid SAML certificate, an LDAP bind/trust failure, a group-claim mismatch, or a perfectly authenticated user who simply lacks SonarQube permission. Treating all of those as “SSO is broken” produces dangerous troubleshooting shortcuts.

2. Mental model: six trust boundaries, not one login screen

flowchart TD
  C[Browser / Scanner / IDE] -->|HTTPS| P[Controlled reverse proxy]
  P -->|HTTP on trusted hop| S[SonarQube web process]
  S -->|LDAP / SAML / supported provider| I[Identity provider]
  I -->|identity + optional groups| S
  S --> A[Authenticated SonarQube user]
  A --> G[Groups / JIT synchronization]
  G --> R[Global + project permissions]
  R --> O[UI / API / scanner action]

The proxy terminates transport security. The IdP proves identity. SonarQube persists the user identity and, when configured, synchronizes group membership. SonarQube permissions then authorize actions. A successful TLS handshake says nothing about group mapping, and a successful SAML assertion says nothing about Administer System permission.

3. Current authentication support: verify the built-in list before choosing a protocol

As of the 2026-09-08 course baseline, current Community Build documentation lists these delegated authentication methods: HTTP header, LDAP, SAML, GitHub, Bitbucket Cloud, and GitLab. LDAP and SAML are therefore valid Community Build learning paths.

4. SonarQube inbound TLS model: HTTPS ends at a reverse proxy

Current SonarQube documentation states that the application accepts plain HTTP for inbound traffic. Production HTTPS is therefore normally implemented by a reverse proxy, ingress controller, load balancer, or equivalent trusted edge that terminates TLS and forwards HTTP to SonarQube.

Restrict the backend SonarQube port so ordinary clients cannot bypass the proxy. On a single host, binding the SonarQube web listener to loopback or firewalling port 9000 to the proxy is materially safer than exposing both HTTPS and raw HTTP paths.

5. Forwarded headers: transport facts must come from a trusted proxy

For HTTPS and SAML, current documentation requires the proxy to set:

• X-Forwarded-Proto — typically https.
• X-Forwarded-For — the client address chain.

The proxy should also preserve the intended Host value. SonarSource additionally documents Sonar-MD5, used by scanners to validate downloaded plugins, as a header that must not be accidentally stripped when analyses pass through the proxy.

6. Server base URL: external identity of the SonarQube instance

The Server base URL is the canonical external URL that SonarQube uses for authentication/integration links. Current Community Build documentation says it must be configured or authentication/integration features may not work correctly.

Internal backend: http://127.0.0.1:9000
External/base URL: https://sonarqube.example.test
SAML Reply/ACS URL: https://sonarqube.example.test/oauth2/callback/saml

The callback URL belongs to the externally visible origin—not the internal backend URL. A mismatch among browser URL, proxy Host/proto, Server base URL, and IdP callback registration is a classic redirect-loop or assertion-recipient failure.

7. SAML: browser-mediated trust with signed assertions

SonarQube Community Build currently supports SAML 2.0 using a service-provider-initiated flow. SonarQube sends the browser to the IdP; the IdP authenticates the user and returns a signed SAML response/assertion; SonarQube validates that assertion using the configured IdP certificate and maps identity attributes.

Do not remove local recovery access merely because a SAML test succeeds once. Test multiple representative users/groups and preserve a rollback path before enforcing delegated login operationally.

8. LDAP: bind/search/group synchronization is a different protocol model

LDAP authentication is configured through SonarQube system properties. Current Community Build can validate user passwords against LDAP/Active Directory LDAP and optionally synchronize group membership at login. LDAPS introduces Java trust-store requirements: the LDAP server certificate must be trusted by the SonarQube Java runtime.

# Illustrative fake/local configuration only
sonar.security.realm=LDAP
ldap.url=ldaps://ldap.example.invalid:636
ldap.bindDn=cn=sonarqube-reader,ou=svc,dc=example,dc=invalid
ldap.bindPassword=<secret from runtime configuration, not Git>
ldap.user.baseDn=ou=people,dc=example,dc=invalid
ldap.group.baseDn=ou=groups,dc=example,dc=invalid

Simple LDAP authentication over unencrypted ldap:// is not appropriate for production credentials. Use LDAPS or another approved secure LDAP mechanism and validate certificate identity instead of disabling verification.

9. Group synchronization changes the owner of membership state

With JIT group synchronization, the delegated identity source supplies group membership at login, while the SonarQube groups themselves must exist and hold the intended permissions. Once external group synchronization owns a user’s membership, manual membership edits are not a durable source of truth.

10. Recovery path is part of the authentication design

Before enabling or changing external authentication, write down:

• Which local administrator account remains available.
• How that account is stored and tested securely.
• How to reach the internal/local SonarQube endpoint if the external proxy is broken.
• How to revert the Server base URL and authentication properties.
• Which config files, environment variables, certificates, proxy files, and IdP objects were changed.

A recovery account is not a convenience; it is a control against lockout during IdP, DNS, certificate, proxy, or group-mapping failure.

11. Read-only inspection before configuration changes

# Local baseline
curl -fsS http://localhost:9000/api/system/status

# Record certificate identity on an existing HTTPS endpoint without disabling verification.
openssl s_client -connect sonarqube.example.test:443 \
  -servername sonarqube.example.test -showcerts </dev/null

# Inspect DNS and route separately from application authentication.
nslookup sonarqube.example.test
curl -I https://sonarqube.example.test/

In the UI, capture Server base URL, enabled authentication mechanisms, group synchronization state, and a list of local administrator/recovery identities. Do not export secrets, private keys, SAML session contents, or tokens into the evidence packet.

Knowledge check

Official references and version notes

• Community Build — authentication and provisioning overview — current native delegated-authentication list and JIT/group-synchronization model.
• Community Build — LDAP — LDAP/AD authentication, group synchronization, LDAPS/trust guidance, logs and migration notes.
• Community Build — SAML overview — SP-initiated SAML, IdP certificate, attributes and group synchronization.
• Community Build — Server base URL — canonical external URL required for authentication/integration correctness.
• Community Build — securing behind a proxy — inbound HTTP model, TLS termination, required forwarded headers, and proxy examples.
• Community Build — networking requirements — external systems, base-URL reachability, HTTPS/proxy topology, and network rules.
• Community Build — SAML with Microsoft Entra ID — Reply URL format /oauth2/callback/saml and base-URL dependency.
• Community OIDC plugin (third party) — optional generic OIDC path; explicitly not a first-party SonarSource native authentication guarantee.