SAML, LDAP, OIDC/SSO, Proxies, TLS, and Network Security: Diagnostics, Failure Modes, and Production Practices

1. Evidence-first diagnostic sequence

1. Preserve browser/proxy/SonarQube logs, HTTP status/redirects, certificate details, and exact timestamps.
2. Confirm Community Build/Server edition and version plus proxy, Java, LDAP/IdP, and plugin versions.
3. Confirm external Server base URL, DNS, certificate SAN/expiry, and proxy Host/forwarded headers.
4. Confirm SAML/LDAP/HTTP-header configuration and callback/issuer/bind/search state.
5. Confirm the authenticated SonarQube identity and group synchronization result.
6. Confirm SonarQube global/project permissions from Chapter 21.
7. If scanners/CI are also failing, inspect their separate token, TLS trust, report upload, ceTaskId, CE, and gate path.
8. Apply the least destructive correction and repeat the smallest equivalent login/request.

2. Failure: “certificate error — just disable verification”

Reject this shortcut. A certificate failure can mean an expired certificate, wrong hostname/SAN, untrusted CA, incomplete chain, intercepted TLS, or wrong endpoint. Disabling verification converts a diagnostic signal into a silent man-in-the-middle risk.

openssl s_client -connect sonarqube.example.test:443 \
  -servername sonarqube.example.test -showcerts </dev/null

curl -v https://sonarqube.example.test/api/system/status

For self-signed/local labs, explicitly supply the CA/certificate. For production, repair the chain/hostname and distribute the correct trusted CA to scanners/Java runtimes as needed.

3. Failure: trusting arbitrary proxy/identity headers

Header-authentication and forwarded-header deployments are safe only when SonarQube receives those headers exclusively from a trusted upstream. If port 9000 is Internet-accessible, a client may bypass the proxy and supply identity/forwarding headers directly.

Repair by restricting backend network access and configuring the proxy to strip/overwrite sensitive headers. Do not “fix” this by adding another header name while leaving the bypass path open.

4. Failure: callback and Server base URL disagree

Fix the Server base URL to the externally reachable HTTPS origin after preserving the old value. Do not change the IdP to point at an internal HTTP backend merely to make the strings match.

5. Failure: a broad external group maps to administrator

This is an authorization design failure, not an authentication success story. Preserve the user’s incoming group claim and resulting SonarQube groups. Remove or narrow the privileged mapping through the authoritative group source and SonarQube group permission design.

6. Failure: the only local administrator was removed before validation

This is an operational lockout risk. The safe pattern is to keep a tested local recovery account until the delegated path, group mapping, certificate renewal process, and rollback have all been validated. Store recovery credentials under your organization’s privileged-access controls; do not put them in sonar.properties, source repositories, screenshots, or wiki pages.

7. Failure: IdP or LDAP secrets stored in source

Configuration examples often show fields such as LDAP bind passwords, SAML SP private keys, or OIDC client secrets. Those values are runtime secrets. Use SonarQube secured settings/system-property secret handling, an approved secret manager, environment injection where supported, or deployment secret primitives. Never commit the actual values.

8. Failure: testing against a production identity provider first

Production IdP testing can create real user accounts, real group grants, audit noise, callback changes, or administrative exposure. The mandatory chapter path uses fake metadata/claims and local TLS. If a real IdP integration must be tested, use an authorized nonproduction tenant/application with synthetic groups and users.

9. Intentionally broken example: wrong external origin

Preserve this mismatch as the first-failure packet:

public_url = https://localhost:9443
server_base_url = https://localhost:9444          # broken
saml_reply_url = https://localhost:9443/oauth2/callback/saml
proxy_x_forwarded_proto = https
local_recovery_admin = verified

# validate_origin.py — offline, non-secret preflight
from urllib.parse import urlparse
public = "https://localhost:9443"
base = "https://localhost:9444"
reply = "https://localhost:9443/oauth2/callback/saml"

def origin(u):
    p = urlparse(u)
    return (p.scheme, p.hostname, p.port or (443 if p.scheme == "https" else 80))

assert origin(public) == origin(base), f"base URL mismatch: {origin(public)} != {origin(base)}"
assert origin(reply) == origin(base), "SAML callback origin does not match Server base URL"
print("origin contract OK")

The script fails before any IdP change. Repair only the base URL to https://localhost:9443, rerun the validator, then continue. This demonstrates configuration-as-evidence without touching a real identity provider.

10. Failure: login succeeds but project access is denied

Do not keep changing SAML or LDAP. Successful login proves the authentication path. Return to Chapter 21 evidence: which SonarQube groups does the user now have, which permissions do those groups have, and is the project private? A 403/hidden project after successful login is an authorization problem unless the group synchronization itself is wrong.

11. Failure: SSO works, scanner does not

Scanners do not normally “log in through the browser SSO flow.” They authenticate with SonarQube tokens/technical accounts. If the scanner fails after a proxy/TLS change:

1. Verify the scanner trusts the proxy certificate/CA.
2. Verify SONAR_HOST_URL points to the correct external URL.
3. Verify token type/permission independently.
4. Preserve scanner logs and report-task.txt if upload occurred.
5. Do not create an administrator token as a shortcut.

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.