Chapter 22Lesson 03~130 minutes

SAML, LDAP, OIDC/SSO, Proxies, TLS, and Network Security: Configuration, Design Patterns, and Trade-Offs

Choose among LDAP, SAML, HTTP-header/SSO and optional OIDC approaches while designing TLS termination, group synchronization, local recovery, and internal/Internet-facing topology deliberately.

AuthenticationSSOTLSReverse proxyNetwork security

Learning objectives

Choose TLS termination and backend network topology that matches SonarQube’s actual HTTP listener model.
Compare LDAP, SAML, HTTP-header SSO, and optional OIDC/plugin approaches by trust ownership and operational cost.
Choose JIT group synchronization versus manual authorization without creating two conflicting sources of truth.
Design local recovery identities and external-authentication rollout sequencing.
Separate authentication mechanism choice from SonarQube permission policy.

1. TLS at the proxy versus “end-to-end TLS”

The prompt asks you to compare TLS termination patterns, but SonarQube’s current inbound architecture constrains the decision: the SonarQube web process accepts HTTP, so the normal supported design is TLS at a proxy/ingress/load balancer followed by a protected HTTP backend hop.

Pattern	Fit	Trade-off
Client HTTPS → proxy → SonarQube HTTP on loopback/private network	Native/documented pattern	Backend hop relies on host/private-network isolation.
Client HTTPS → proxy → protected tunnel/service-mesh sidecar → SonarQube HTTP	Possible infrastructure pattern when policy requires encrypted transport across hosts	Extra certificates, routing, health checks and ownership outside SonarQube.
Direct HTTPS on SonarQube application listener	Not the documented inbound model	Do not invent unsupported web-TLS properties.

“End-to-end encryption” can therefore be achieved only by surrounding infrastructure on the proxy-to-backend segment, not by pretending SonarQube itself exposes an HTTPS application socket.

2. LDAP versus SAML: same goal, different trust mechanics

Dimension	LDAP	SAML
Interaction	SonarQube connects to directory/binds/searches	Browser redirects between SonarQube SP and IdP
Primary trust	LDAP server identity + bind/search configuration	IdP entity/certificate + signed assertion + callback/base URL
TLS concern	LDAPS/secure LDAP and Java trust store	HTTPS reverse proxy, IdP certificate, optional SP signing/encryption keys
Group sync	LDAP group lookup at login	SAML group attribute at login
Typical failure	Bind DN, base DN/filter, referrals, LDAPS trust	ACS/callback mismatch, issuer/entity, certificate, attribute mapping

Choose the protocol your identity platform can operate reliably and auditably. Do not select SAML merely because it is “more enterprise” or LDAP merely because it looks simpler.

3. OIDC: separate protocol preference from product support

OIDC is common in modern identity systems, but current Community Build authentication documentation does not list generic OIDC as a first-party native method. If your organization requires OIDC, you have three governance choices:

Use the IdP’s SAML support with SonarQube’s native SAML integration.
Use another first-party supported authentication path where appropriate.
Adopt a third-party OIDC plugin only after compatibility, maintenance, security review, restart/upgrade testing, and rollback planning.

Plugin boundary. A community plugin may be functional and useful, but it changes the supported component set. Pin its version, verify compatibility on every SonarQube upgrade, and never present it as a built-in SonarSource guarantee.

4. Local accounts versus external identity

Local accounts

Smallest external dependency and best emergency recovery path, but poor lifecycle scalability for large organizations.

Delegated identity

Central password/MFA/lifecycle ownership and group sync, but depends on IdP, network, certificates, claims, and callback correctness.

Hybrid operational pattern

External identity for routine users plus tightly controlled local break-glass/recovery identity.

The hybrid pattern is usually safer during rollout because external identity failure does not immediately become administrative lockout.

5. Group synchronization versus manual authorization

Community Build supports JIT provisioning and optional group synchronization. SonarQube groups still own SonarQube permissions; the external source supplies membership. This creates a clean separation:

IdP/LDAP membership → SonarQube group membership → SonarQube
              permission template/global/project permissions

When synchronization is configured, do not fight it with manual user membership edits. Change the external group source or change the SonarQube permission attached to the mapped group, depending on which policy is actually wrong.

6. JIT versus automatic provisioning

Current Community Build documentation states that Community Build provisions users through Just-in-Time login. Server editions can add automatic provisioning capabilities for certain providers/SCIM scenarios. Keep the mandatory path JIT-compatible and treat SCIM/automatic provisioning as an edition/provider-specific extension.

Ownership rule. Once an external provider owns a user/group field through synchronization, local edits may be overwritten or restricted. Record which system is authoritative before troubleshooting “changes that do not stick.”

7. Internal-only versus Internet-facing topology

Topology	Security posture	Operational requirement
Developer/VPN internal	Smaller exposure; still requires TLS where credentials traverse networks	Private DNS, internal CA, proxy restrictions, CI/IdP reachability
Internet-facing	Higher attack surface	Public CA, hardened proxy/WAF/network rules, strict backend isolation, monitoring/rate controls
Cloud CI + private SonarQube	Reachability problem, not an auth shortcut	Approved network path/self-hosted runners; do not expose admin ports casually

The Server base URL must be reachable by external systems that need to call SonarQube, such as some SCIM or cloud CI integrations. Do not solve reachability by exposing internal search/database ports.

8. Proxy header design: overwrite, do not append blindly

A hardened proxy:

terminates TLS with a certificate valid for the public hostname;
sets Host, X-Forwarded-Proto, and X-Forwarded-For from observed connection state;
strips client-supplied identity/forwarding headers before setting trusted versions;
restricts direct backend access;
preserves headers such as Sonar-MD5 required by scanners;
logs request IDs/statuses without logging bearer tokens/cookies.

9. Administrative group mapping requires an explicit control

A common SSO mistake is mapping a broad enterprise group such as Engineering to sonar-administrators. That turns identity-provider group sprawl into SonarQube system administration.

Prefer narrow groups such as sq-platform-admins with explicit membership review. Preserve evidence that the IdP group name matches the intended SonarQube group exactly and that no wildcard/claim-transform accidentally widens it.

10. Safe rollout sequence

Capture current local authentication and permissions.
Establish TLS/proxy/base URL first.
Keep local recovery access.
Configure fake/sandbox IdP and test a nonadmin user.
Test group synchronization against nonprivileged groups.
Test privileged mapping separately with a dedicated test identity.
Test logout/session behavior and token/scanner behavior independently.
Document rollback; only then consider broader rollout.

11. Worked decision table

Requirement	Preferred approach	Evidence
Existing AD/LDAP, internal instance	LDAP/LDAPS with group sync if operationally supported	Bind/search success, trusted certificate, user/group mapping logs
Modern IdP supports SAML and OIDC	Native SAML first unless a reviewed reason requires OIDC	Base URL, ACS URL, IdP cert, attributes, test login
Organization mandates generic OIDC	Reviewed third-party plugin or identity broker; not a silent built-in assumption	Plugin compatibility matrix, pinned version, rollback/upgrade test
Internet-facing SonarQube	TLS reverse proxy + backend isolation + supported SSO	Certificate, headers, firewall rules, base URL, login/group test

Knowledge check

Can you configure direct HTTPS on SonarQube’s application listener instead of using a proxy?

Who owns permission after SAML group synchronization?

Why is a third-party OIDC plugin an upgrade concern?

What is safer than mapping all Engineering users to Sonar administrators?

When a synchronized membership “reappears,” what should you inspect?

Next lesson

Diagnose external-authentication failures without weakening trust

Lesson 4 engineers the certificate, callback, header, mapping, and authorization failures that commonly become unsafe shortcuts.

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.

Version and compatibility note

Rechecked 2026-09-08. Mandatory examples target Community Build 26.9.0.129388. Current Community Build documentation lists HTTP-header, LDAP, SAML, GitHub, Bitbucket Cloud, and GitLab authentication; LDAP and SAML are available in Community Build with JIT/group synchronization. Generic OIDC is not listed as a native method in the current Community Build authentication overview, so this chapter treats it as a configuration simulation or optional third-party-plugin path requiring independent compatibility/security review. SonarQube accepts inbound application traffic as HTTP; production HTTPS is terminated at a reverse proxy/ingress/load balancer. For HTTPS/SAML, X-Forwarded-Proto and X-Forwarded-For must be set by the trusted proxy. Server base URL must match the externally reachable origin/callback design. Automatic provisioning/SCIM and other enterprise identity lifecycle features are edition/provider-specific and are not required by the mandatory local path. Recheck authentication support, plugin compatibility, proxy headers, callback URLs, Java trust-store requirements, and provisioning ownership before applying this material to another release.

Trust-boundary evidence rule. Preserve external/base URL, certificate metadata, proxy configuration and headers, authentication mechanism/version, fake/sandbox IdP mapping, resulting SonarQube group/permission state, local recovery path, and rollback evidence separately. Never place private keys, IdP/LDAP client secrets, session cookies, real user passwords, or scanner tokens in the evidence packet.

Keep the academy open

Support free, practical DevOps education.

Every lesson is designed to remain readable in a browser, downloadable from GitHub, and usable without a paid learning platform. Contributions help expand and maintain the curriculum.

Ethereum / ERC-20

0x716c4Ab160C4B66F31a28AE2448BfF68fc3a2ef0Send only Ethereum/ERC-20 compatible assets to this address.