Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 37 ยท Administration

SonarQube Authentication: LDAP, SAML, GitHub Login and Tokens

Configure SonarQube sign-in with local accounts, LDAP, SAML and GitHub, understand user, project and global analysis tokens, and handle token rotation safely.

Who can log in to SonarQube, and how do scanners and scripts prove who they are? Two separate mechanisms answer those questions: authentication for people (a login form or single sign-on) and tokens for machines and scripts. This lesson covers both, shows the settings that matter, and ends with token hygiene.

The server is not runnable on this site; settings are described by their menu and property names, and the TryIts are stand-ins that model the ideas.

Authentication methods

Method Typical use Where
Local accounts Evaluation, small teams, the initial admin Administration > Security > Users
LDAP / Active Directory Company directory, groups synced sonar.properties (sonar.security.realm=LDAP and ldap.* keys)
SAML 2.0 SSO with an identity provider such as Entra ID, Okta, Keycloak Administration > Configuration > Authentication > SAML
GitHub, GitLab, Bitbucket, Azure DevOps login Developers already live in the code host Administration > Configuration > Authentication, or the DevOps Platform Integration
HTTP header authentication A reverse proxy authenticates and passes identity sonar.web.sso.* properties (edition dependent)

Only enable what you will maintain. Leave local login available for at least one break-glass administrator in case the identity provider is down; note that exact controls for disabling the login form vary by version.

LDAP

LDAP settings live in sonar.properties and need a restart:

PROPERTIES
sonar.security.realm=LDAP
ldap.url=ldaps://ldap.example.com:636
ldap.bindDn=cn=sonar,ou=service,dc=example,dc=com
ldap.bindPassword=<from a secret store>
ldap.user.baseDn=ou=people,dc=example,dc=com
ldap.user.request=(&(objectClass=inetOrgPerson)(uid={login}))
ldap.group.baseDn=ou=groups,dc=example,dc=com
ldap.group.request=(&(objectClass=groupOfUniqueNames)(uniqueMember={dn}))

With a group request, LDAP group names map to SonarQube groups of the same name, which is handy for permission templates. Use LDAPS or StartTLS so credentials are never sent in clear text. Keep the bind password out of version control.

SAML

In Authentication > SAML you enter the provider's Application ID, Provider ID, Provider Name, the login URL, the certificate, and the attribute names for login, name, email and (optionally) groups. In the identity provider you register SonarQube with a callback URL of the form https://sonar.example.com/oauth2/callback/saml. The server's public URL (sonar.core.serverBaseURL) must match the one the provider expects, or logins fail with a redirect mismatch. Turn on "synchronize groups" only if the provider sends a groups attribute.

Code host login

For GitHub, create a GitHub App, then enter its client ID and secret in SonarQube. Users get a Log in with GitHub button, can be limited to organisation members, and can have their org teams mapped to groups. GitLab, Bitbucket and Azure DevOps have similar options.

Tokens

A token is a long random string used instead of a password. It is sent as the user name in HTTP basic authentication (with an empty password) or in a Bearer header, and the scanner reads it from SONAR_TOKEN or the sonar.token property. (Older tutorials use sonar.login; that property has been replaced in current versions.)

Type Scope Use
User token Everything the user can do Personal scripts, IDE connection (SonarQube for IDE)
Project analysis token Run analysis on one project only CI pipelines (preferred)
Global analysis token Run analysis on any project Bulk automation; use with care

Create tokens in My Account > Security. A token is shown once; copy it into your secret store immediately. Tokens can have an expiry date (30 days, 90 days, 1 year or no expiration, depending on version). Administrators can list and revoke other users' tokens in Administration > Security > Users, and the Web API has api/user_tokens/generate, search and revoke.

Terminal
# Is my token valid? Returns {"valid":true} for a good one
curl -s -u "$SONAR_TOKEN:" "$SONAR_HOST_URL/api/authentication/validate"

Token hygiene

  • Use a project analysis token in CI; it can analyse but cannot browse other projects or change settings.
  • Create tokens for a service account, not for a person who may leave.
  • Set an expiry and track it; a token that expires silently breaks the pipeline on a random morning.
  • Revoke immediately if one leaks (committed to a repo, printed in logs). CI systems mask secrets, but only exact matches.
  • Never put tokens in URLs or sonar-project.properties.

Stand-in: token expiry monitor

Teams that forget tokens find out when CI fails. This stand-in lists tokens with their expiry and flags the ones that need rotation soon.

JS Stand-in: token expiry report

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: building an Authorization header

Scripts talk to the Web API with a token as the basic-auth user name. Here is exactly how that header is made. The token below is a made-up placeholder, not a real credential.

JS Stand-in: basic auth with a token

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Troubleshooting sign-in

  • Redirect loop after SAML login: the base URL (sonar.core.serverBaseURL) does not match the URL users open, often because of a reverse proxy that terminates TLS. Make the proxy send X-Forwarded-Proto and X-Forwarded-Host headers.
  • Users land in no groups: the group attribute name or LDAP group request does not match.
  • 401 in CI: wrong token type, expired token, or the token owner lacks Execute Analysis on the project.
  • Locked out: an administrator with database access can reset a local admin password through documented procedures; a pre-created break-glass account avoids that.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which token type is best for a CI pipeline that analyses one project?

    A project analysis token has the narrowest scope that still allows the scan.
  2. 2. How is a token sent in basic authentication?

    SonarQube treats the user name field as the token when the password is empty.
  3. 3. A token is leaked in a build log. What do you do first?

    Revocation is immediate and stops the leaked credential from working.
  4. 4. Why keep one local administrator even with SAML?

    An emergency local account lets you log in when SSO is down or misconfigured.

Summary

  • People log in with local accounts, LDAP, SAML or a code host; machines use tokens.
  • Prefer project analysis tokens, service accounts and expiry dates.
  • Mind the public base URL for SAML and proxy headers.
  • Treat tokens like passwords: store in secrets, revoke on leak.

Next: Database, backups and upgrades