SSO with SAML in SonarQube (Microsoft Entra ID)

By David Dominguez·September 8, 2026·Updated September 10, 2026

Complete step-by-step guide to integrating Single Sign-On (SSO) authentication via SAML 2.0 in SonarQube Community and Developer Edition with Microsoft Entra ID (formerly Azure AD).

1. Introduction

SonarQube is a leading platform for continuous inspection of code quality and security. Until recently, SSO authentication via SAML was limited to the commercial editions (Developer, Enterprise, and Data Center). However, starting with version 26.9.0, the Community edition also includes native support for SAML 2.0.

This guide documents the full process for configuring SSO with Microsoft Entra ID (Azure AD) in both editions: Community and Developer.

Why SSO with Entra ID?

Centralization: A single authentication point for all developers.
Security: Leverages MFA, Conditional Access, and Entra ID policies.
Automation: Users are provisioned automatically on first login.
Group synchronization: Permissions are assigned automatically based on group membership.

2. Prerequisites

Before you begin, make sure you have:

In SonarQube

SonarQube instance reachable over HTTPS (required by SAML)
Version 26.9.0+ for Community Edition
Administrator access to SonarQube
Public URL configured (Server Base URL)

In Microsoft Entra ID

An Azure Active Directory / Microsoft Entra ID tenant
Permissions to create Enterprise Applications
Security groups created for SonarQube users

Network

SonarQube reachable from the internet (to receive SAML responses)
Valid SSL certificate (Let’s Encrypt, commercial certificate, etc.)

3. Solution Architecture

┌─────────────────────────────────────────────────────────────────┐
│                          User                                    │
│                  (cdominguez@company.com)                        │
└──────────────────────┬──────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────────┐
│              Microsoft Entra ID (Azure AD)                       │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  Enterprise Application: "SonarQube Developer"           │   │
│  │  Enterprise Application: "SonarQube Community"           │   │
│  │                                                          │   │
│  │  Groups:                                                 │   │
│  │  • sonar-administrators                                  │   │
│  │  • sonar-developers                                      │   │
│  │  • sonar-viewers                                         │   │
│  └─────────────────────────────────────────────────────────┘   │
└──────────────────────┬──────────────────────────────────────────┘
                       │ SAML 2.0 Assertion
                       ▼
┌─────────────────────────────────────────────────────────────────┐
│              Application Load Balancer (AWS)                     │
│              HTTPS:443 → sonar-dev.company.com                   │
│              HTTPS:443 → sonar-community.company.com             │
└──────────────────────┬──────────────────────────────────────────┘
                       │
         ┌─────────────┴─────────────┐
         ▼                           ▼
┌─────────────────┐       ┌──────────────────┐
│ SonarQube Dev   │       │ SonarQube Comm   │
│ EC2 t3.xlarge   │       │ EC2 t3.large     │
│ Port 9000       │       │ Port 9000        │
└─────────────────┘       └──────────────────┘

4. Step 1: Create Groups in SonarQube

Groups are essential for role-based access control (RBAC). SonarQube automatically synchronizes group membership from Entra ID via SAML.

4.1 Access group administration

Sign in to SonarQube as an administrator.
Navigate to Administration → Security → Groups.
Click Create Group.

4.2 Create the required groups

Create the following groups (the names must match those in Entra ID exactly):

SonarQube Group	Description	Purpose
`sonar-administrators`	Platform administrators	Full administrative access
`sonar-developers`	Development teams	Create projects, run analysis
`sonar-viewers`	Read-only users	View metrics and reports

4.3 Assign global permissions

Navigate to Administration → Security → Global Permissions and assign:

Group	Administer System	Administer Projects	Create Projects	Execute Analysis
`sonar-administrators`	✅	✅	✅	✅
`sonar-developers`	❌	❌	✅	✅
`sonar-viewers`	❌	❌	❌	❌

5. Step 2: Register the Application in Microsoft Entra ID

5.1 Create the Enterprise Application

Go to the Azure Portal.
Navigate to Microsoft Entra ID → Enterprise applications.
Click New application.
Select Create your own application.
Configure:
- Name: SonarQube Developer (or SonarQube Community)
- Select: Integrate any other application you don’t find in the gallery (Non-gallery)
- Click Create.

5.2 Configure basic SAML

In the created application, go to Manage → Single sign-on.
Select SAML.
In the Basic SAML Configuration section, click Edit.
Fill in the following values:

For SonarQube Developer:

Field	Value
Identifier (Entity ID)	`https://sonar-dev.yourdomain.com`
Reply URL (Assertion Consumer Service URL)	`https://sonar-dev.yourdomain.com/oauth2/callback/saml`
Sign on URL	`https://sonar-dev.yourdomain.com`
Logout URL (Optional)	`https://sonar-dev.yourdomain.com/sessions/logout`

For SonarQube Community:

Field	Value
Identifier (Entity ID)	`https://sonar-community.yourdomain.com`
Reply URL (Assertion Consumer Service URL)	`https://sonar-community.yourdomain.com/oauth2/callback/saml`
Sign on URL	`https://sonar-community.yourdomain.com`
Logout URL (Optional)	`https://sonar-community.yourdomain.com/sessions/logout`

Save the changes.

5.3 Retrieve the configuration values

In the Set up SonarQube Developer (or Community) section, copy the following values:

Value	Description	Example
Login URL	Entra ID authentication URL	`https://login.microsoftonline.com/{tenant-id}/saml2`
Microsoft Entra Identifier	IdP Entity ID	`https://sts.windows.net/{tenant-id}/`
Logout URL	Sign-out URL	`https://login.microsoftonline.com/{tenant-id}/saml2`
Certificate (Base64)	X.509 certificate	Download and copy the contents

6. Step 3: Configure Claims and Groups in Entra ID

6.1 Configure Attributes & Claims

In the Entra ID application, go to Single sign-on → Attributes & Claims → Edit.

Make sure you have the following claims configured:

Claim Name	Value	Purpose
`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`	`user.userprincipalname`	Unique user identifier
`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`	`user.mail`	Email address
`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`	`user.givenname`	User’s first name
`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`	`user.surname`	User’s last name

6.2 Configure the Group Claim (critical for group mapping)

This step is essential for SonarQube to synchronize groups automatically.

In Attributes & Claims, find the “Add a group claim” option.
Select:
- Which groups: Groups assigned to the application (recommended) or All groups
- Source attribute: Cloud-only group display names (if available) or sAMAccountName
Under Customize, configure:
- Name: http://schemas.xmlsoap.org/claims/Group
Save the claim.

6.3 Assign groups to the application

In the Entra ID application, go to Manage → Users and groups.
Click Add user/group.
Select the groups that will have access:
- sonar-administrators
- sonar-developers
- sonar-viewers
Click Assign.

7. Step 4: Configure SAML in SonarQube

7.1 Access the SAML configuration

Sign in to SonarQube as an administrator.
Navigate to Administration → Configuration → Authentication → SAML.
Enable Enabled.

7.2 Configure the Identity Provider

Fill in the fields with the values obtained in Step 2:

SonarQube Field	Entra ID Value	Example
Application ID	SonarQube Entity ID	`https://sonar-dev.yourdomain.com`
Provider Name	Descriptive name	`azure`
Provider ID	Microsoft Entra Identifier	`https://sts.windows.net/{tenant-id}/`
SAML login url	Login URL	`https://login.microsoftonline.com/{tenant-id}/saml2`
Identity provider certificate	Certificate (Base64)	Paste the full certificate
SAML logout url	Logout URL	`https://login.microsoftonline.com/{tenant-id}/saml2`

7.3 Configure user attribute mapping

Field	Entra ID Claim
SAML user login attribute	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`
SAML user name attribute	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`
SAML user email attribute	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`

7.4 Configure group attribute mapping

Field	Value
SAML group attribute	`http://schemas.xmlsoap.org/claims/Group`

7.5 Configure the Server Base URL

Navigate to Administration → Configuration → General → Server base URL.

Make sure it is exactly your instance’s public URL:

https://sonar-dev.yourdomain.com

7.6 Save and test

Click Save.
Click Test configuration.
If everything is correct, you will be redirected to Microsoft to authenticate.

8. Step 5: Group and Permission Mapping

8.1 Verify group synchronization

After a successful first SSO login:

Go to Administration → Security → Users.
Find the user who authenticated.
Verify they appear in the correct groups:
- sonar-users (default group, automatic)
- sonar-administrators, sonar-developers, or sonar-viewers (based on Entra ID)

8.2 Troubleshoot group mapping

If the user only appears in sonar-users:

Verify that the names match exactly between Entra ID and SonarQube.
Review the group claim in Entra ID (Step 6.2).
Confirm the user is in the group in Entra ID.
Check the SonarQube logs to see the claims received.

8.3 Assign additional permissions

If sonar-developers users get “You are not authorized to access this page”:

Go to Administration → Security → Global Permissions.
Assign to the sonar-developers group:
- ✅ Create Projects
- ✅ Execute Analysis
- ✅ Administer Projects (if they need to see all projects)

9. Common Troubleshooting

Error: `AADSTS50105: Your administrator has configured the application to block users...`

Cause: The application requires explicit assignment and the user is not assigned.

Solution:

In Entra ID, go to the application → Users and groups.
Add the corresponding user or group.
Alternative: Go to Properties and set “Assignment required?” to No (less secure).

Error: `AADSTS50011: The reply URL specified in the request does not match...`

Cause: The Server Base URL in SonarQube does not match the Reply URL in Entra ID.

Solution:

Verify Server base URL in SonarQube (Administration → General).
Make sure it is https:// (not http://).
Confirm the Reply URL in Entra ID includes /oauth2/callback/saml.

Error: `You're not authorized to access this page`

Cause: The user authenticated but does not have sufficient permissions.

Solution:

Verify the user is in the correct groups.
Assign global permissions to the groups (Administration → Security → Global Permissions).
If the sonar-developers group has no permissions, add Administer Projects.

Error: The user is not created in SonarQube

Cause: The login claim is not configured correctly.

Solution:

Verify that SAML user login attribute is http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name.
Review the SonarQube logs to see the claims received.
Make sure the name claim is sending a valid value.

Problem: Groups don’t synchronize

Cause: The group claim is not configured or the names don’t match.

Solution:

In Entra ID, verify the Group claim is configured (Step 6.2).
Confirm the group names are identical in both systems.
Verify the user is actually in the group in Entra ID.
Verify the groups are assigned to the application in Entra ID.

10. Final Verification

Verification checklist

User can authenticate via SSO in SonarQube Developer
User can authenticate via SSO in SonarQube Community
User is created automatically in SonarQube on first login
User is assigned automatically to the correct groups
sonar-administrators users have full access
sonar-developers users can create projects and analyze code
sonar-viewers users can view projects (with project-level permissions)
Logout signs out of both SonarQube and Entra ID

Useful diagnostic commands

# Tail SonarQube logs in real time
sudo docker logs -f sonarqube 2>&1 | grep -i "saml\|auth\|group"

# View received SAML claims (requires DEBUG enabled)
sudo docker logs sonarqube --tail 500 2>&1 | grep -i "attribute\|claim"

# Check SonarQube status
curl -s https://sonar-dev.yourdomain.com/api/system/status | python3 -m json.tool

11. Conclusion

Configuring SSO with SAML in SonarQube through Microsoft Entra ID provides a robust and secure solution for centralized authentication. Starting with version 26.9.0, both the Community and Developer editions support this integration natively.

Key points to remember

HTTPS is mandatory: SAML requires secure communication.
Exact name matching: Groups must be named identically in both systems.
Server Base URL: Must be the public URL, never localhost.
Assignment in Entra ID: Groups must be assigned to the application.
Correct claims: Use the full claim URIs, not login URLs.

Additional resources

K3s Cluster on Proxmox — build the Kubernetes cluster you can run SonarQube (and its SSO) on.
About NinjaSRE — more about this lab environment and the engineer behind it.

Appendix: Configuration for Multiple Instances

If you manage multiple SonarQube instances (Developer and Community), repeat steps 2–4 for each instance, making sure to:

Instance	Entity ID	Reply URL
Developer	`https://sonar-dev.yourdomain.com`	`https://sonar-dev.yourdomain.com/oauth2/callback/saml`
Community	`https://sonar-community.yourdomain.com`	`https://sonar-community.yourdomain.com/oauth2/callback/saml`

Both applications can share the same Entra ID tenant and the same security groups.

SSO with SAML in SonarQube (Microsoft Entra ID)

1. Introduction

Why SSO with Entra ID?

2. Prerequisites

In SonarQube

In Microsoft Entra ID

Network

3. Solution Architecture

4. Step 1: Create Groups in SonarQube

4.1 Access group administration

4.2 Create the required groups

4.3 Assign global permissions

5. Step 2: Register the Application in Microsoft Entra ID

5.1 Create the Enterprise Application

5.2 Configure basic SAML

For SonarQube Developer:

For SonarQube Community:

5.3 Retrieve the configuration values

6. Step 3: Configure Claims and Groups in Entra ID

6.1 Configure Attributes & Claims

6.2 Configure the Group Claim (critical for group mapping)

6.3 Assign groups to the application

7. Step 4: Configure SAML in SonarQube

7.1 Access the SAML configuration

7.2 Configure the Identity Provider

7.3 Configure user attribute mapping

7.4 Configure group attribute mapping

7.5 Configure the Server Base URL

7.6 Save and test

8. Step 5: Group and Permission Mapping

8.1 Verify group synchronization

8.2 Troubleshoot group mapping

8.3 Assign additional permissions

9. Common Troubleshooting

Error: AADSTS50105: Your administrator has configured the application to block users...

Error: AADSTS50011: The reply URL specified in the request does not match...

Error: You're not authorized to access this page

Error: The user is not created in SonarQube

Problem: Groups don’t synchronize

10. Final Verification

Verification checklist

Useful diagnostic commands

11. Conclusion

Key points to remember

Additional resources

Related guides

Appendix: Configuration for Multiple Instances

Error: `AADSTS50105: Your administrator has configured the application to block users...`

Error: `AADSTS50011: The reply URL specified in the request does not match...`

Error: `You're not authorized to access this page`