How to set up Azure AD
The following content may be useful if you're using Azure AD as a SAML identity provider.
To integrate Azure AD (identity provider) with SonarQube (service provider), both sides need to be configured.
For SonarQube, navigate to Administration > Authentication > SAML and click Create. This will open a pop-up window with all the fields that you'll need during the procedure. For Azure AD, login to Azure and navigate to Azure AD.
Set up the SonarQube application in Azure AD
Step 1: In Azure AD, navigate to Enterprise applications and add a New Application.
![The Azure navigation path to create a new application for your SonarQube SAML authentication.](https://assets-eu-01.kc-usercontent.com:443/5e986e54-339c-01a9-7c7c-26cbc5a344d5/ea15449a-0d73-4035-918d-d81b31471e88/azure-saml-new-enterprise-application.jpg?w=1842&h=893&auto=format&fit=crop)
Step 2: Create your own application and fill in the name.
![Create a new Enterprise application for SonarQube when setting up SAML authentication in Azure.](https://assets-eu-01.kc-usercontent.com:443/5e986e54-339c-01a9-7c7c-26cbc5a344d5/eb7bd153-1a24-4ba1-a2f6-1cda1b1081fe/azure-create-saml-application.jpg?w=1842&h=893&auto=format&fit=crop)
Link SonarQube with Azure AD
Step 1: Navigate to Single sign-on and select SAML.
![Navigate to Single sign-on in Azure and select SAML to begin the authentication process.](https://assets-eu-01.kc-usercontent.com:443/5e986e54-339c-01a9-7c7c-26cbc5a344d5/8c2d0346-08df-433c-9d91-9b845cdc52e8/azure-saml-sso-method.jpg?w=1804&h=1154&auto=format&fit=crop)
Step 2: Edit the Basic SAML Configuration and fill in the Identifier and the Reply URL fields. The Identifier has to be the same as the Application ID in SonarQube. The Reply URL must have the format <Your SonarQube URL>/oauth2/callback/saml
. The Reply URL uses the Server base URL provided in SonarQube under Administration > General.
![When setting up your SSO with SAML, edit the Basic SAML Configuration and fill in the Identifier and the Reply URL.](https://assets-eu-01.kc-usercontent.com:443/5e986e54-339c-01a9-7c7c-26cbc5a344d5/d4b3f7a4-49d2-436b-8110-89c46d703978/azure-single-sign-on-with-saml.jpg?w=1218&h=488&auto=format&fit=crop)
Step 3: Make sure that the Application ID in SonarQube has the same value as the Identifier in the Identity Provider.
![Confirm that the Application ID in SonarQube has the same value as the Identifier in the Identity provider.](https://assets-eu-01.kc-usercontent.com:443/5e986e54-339c-01a9-7c7c-26cbc5a344d5/a9cbaffe-8e4c-416c-b24b-e6b6f5f28cdb/azure-saml-sonarqube-application-id.png?w=836&h=125&auto=format&fit=crop)
Step 4: In the Azure AD SAML configuration, navigate to Set up and copy the Login URL and Azure AD Identifier.
![In the Azure AD SAML configuration, navigate to Set up and copy the Login URL and Azure AD Identifier.](https://assets-eu-01.kc-usercontent.com:443/5e986e54-339c-01a9-7c7c-26cbc5a344d5/295a1383-cdc4-4624-91a3-7211e10aecda/azure-saml-login-url-and-identifier.jpg?w=1056&h=268&auto=format&fit=crop)
Step 5: Paste the Login URL into the SAML login url and the Azure AD Identifier into the Provider ID field in the SonarQube SAML configuration.
![Paste the Azure AD Identifier into the Provider ID field and the Login URL into the SAML login url into your SonarQube SAML configuration.](https://assets-eu-01.kc-usercontent.com:443/5e986e54-339c-01a9-7c7c-26cbc5a344d5/30903136-95b5-42ce-bc75-195dba6b7dd8/azure-saml-authentication-and-provider-id.png?w=1038&h=234&auto=format&fit=crop)
Attributes and claims
Step 1: In the Azure AD SAML configuration, edit Attributes & Claims to view, edit or add attributes.
![Edit Attributes & Claims to view, edit or add attributes when configuring SAML authentication in Azure.](https://assets-eu-01.kc-usercontent.com:443/5e986e54-339c-01a9-7c7c-26cbc5a344d5/a736c030-de65-4d3c-b23a-ad922624df0b/azure-saml-attributes-and-claims.jpg?w=1211&h=665&auto=format&fit=crop)
SonarQube uses the following attributes:
- Login (required) A unique name to identify the user in SonarQube. The default Azure AD attribute
emailaddress
is used in the example. You can also use theobjectID
attribute. - Name (required) The full name of the user. The default Azure AD attribute
givenname
is used in the example. - Email (optional) The email of the user.
- Group (optional) Supports mapping to group names in SonarQube. Group name passed by Azure AD and the group name in SonarQube should match. Otherwise, the default sonar-users group is assigned.
The NameID attribute is not used in SonarQube.
Step 2: Corresponding configuration in SonarQube. The namespace + name of the attribute should be used, as defined in Azure AD.
![The corresponding configuration in SonarQube uses the Azure namespace + name of the attribute to be used.](https://assets-eu-01.kc-usercontent.com:443/5e986e54-339c-01a9-7c7c-26cbc5a344d5/a27e48de-654f-4634-8428-8ab509c4d4a7/azure-saml-user-login-and-name-attribute.png?w=963&h=233&auto=format&fit=crop)
Certificates and signatures
Step 1: Navigate to SAML Certificates and download Certificate (Base64).
![Navigate to SAML Certificates and download Certificate (Base64).](https://assets-eu-01.kc-usercontent.com:443/5e986e54-339c-01a9-7c7c-26cbc5a344d5/3f22e509-942b-4855-940b-432a41d77d25/azure-saml-certificates-base64.jpg?w=1051&h=537&auto=format&fit=crop)
Step 2: The certificate should be copied into the Identity provider certificate field in the SonarQube SAML configuration.
Step 3 (Optional): Encryption for SonarQube requests can be activated by generating an asymmetric key pair. (For more information, see SAML token encryption in Azure) Add the private key in SonarQube.
![Copied the Service provider private key field value to add to your SonarQube SAML configuration.](https://assets-eu-01.kc-usercontent.com:443/5e986e54-339c-01a9-7c7c-26cbc5a344d5/6e0236be-6742-4f54-b33a-a920be5eddd7/azure-saml-service-provider-private-key.png?w=736&h=128&auto=format&fit=crop)
Import the public key certificate (.cer) file in Azure AD and activate token encryption.
![Import the public key certificate (.cer) file in Azure AD and activate token encryption for your SonarQube SAML authentication.](https://assets-eu-01.kc-usercontent.com:443/5e986e54-339c-01a9-7c7c-26cbc5a344d5/05f3291d-9278-4e67-b935-dedd97fa79be/azure-saml-public-key-certificate.jpg?w=1376&h=484&auto=format&fit=crop)
Step 4 (Optional): Azure AD supports signed SAML requests from the Service Provider (under Preview). Edit the Verification certificates, upload a certificate, and enable the Require verification certificates option.
![To edit the Verification certificates, upload a certificate and enable the Require verification certificates option.](https://assets-eu-01.kc-usercontent.com:443/5e986e54-339c-01a9-7c7c-26cbc5a344d5/4322c35f-acd9-4554-ae44-6eed8367c82b/azure-saml-based-sso-verification-certificate.jpg?w=1494&h=552&auto=format&fit=crop)
In SonarQube, fill in the corresponding private key and the same certificate and enable the Sign requests option.
![In SonarQube, fill in the corresponding private key and the same certificate and enable the Sign requests option.](https://assets-eu-01.kc-usercontent.com:443/5e986e54-339c-01a9-7c7c-26cbc5a344d5/d0740368-5101-4bf8-bfb2-7e0a230febd5/azure-saml-sign-requests.png?w=766&h=333&auto=format&fit=crop)
Users and groups
In the Azure AD SonarQube application, navigate to Users and groups and assign users or groups to the application.
![Add SonarQube users and groups when setting up your SAML authentication in Azure.](https://assets-eu-01.kc-usercontent.com:443/5e986e54-339c-01a9-7c7c-26cbc5a344d5/d1e59fa8-8e87-4ab9-b429-e118697ea3be/azure-add-saml-users-and-groups.jpg?w=1644&h=586&auto=format&fit=crop)
Enabling and testing SAML authentication
Step 1: Save the SAML configuration by clicking Save configuration.
![](https://assets-eu-01.kc-usercontent.com:443/5e986e54-339c-01a9-7c7c-26cbc5a344d5/791fe14c-e520-457d-ad60-767760a3d9bb/saml-configuration.png?w=1600&h=1381&auto=format&fit=crop)
Step 2: Before enabling SAML authentication on SonarQube, you can verify that the configuration is correct by clicking Test Configuration. This will initiate a SAML login and return useful information about the SAML response obtained from the identity provider.
Step 3: Click Enable configuration.
Step 4: In the login form, the new Log in with Azure button (or a custom name specified in the Provider Name field) allows users to connect with their SAML account.
![](https://assets-eu-01.kc-usercontent.com:443/5e986e54-339c-01a9-7c7c-26cbc5a344d5/9f71995f-d8b1-481b-b08a-cde8d1970ef8/login-azure.png?w=230&h=148&auto=format&fit=crop)
Group synchronization
Group synchronization between Azure AD and SonarQube can be achieved either by using the Azure AD roles or the Azure AD groups. For either case, the corresponding group name should exist in SonarQube under the Provisioning section of the SAML configuration. Group synchronization only works with the Just-in-Time user and group provisioning (default) option.
- For synchronization with the Azure AD groups, a group claim must be added with
sAMAccountName
as a source attribute.
According to Azure, this source attribute only works for groups synchronized from an on-premises Active Directory using AAD Connect Sync 1.2.70.0 or above.
![Where to map your SAML groups in Azure before you can add a group claim.](https://assets-eu-01.kc-usercontent.com:443/5e986e54-339c-01a9-7c7c-26cbc5a344d5/981d018d-c5b4-4b1f-8028-651cc8dc7363/azure-saml-group-claims.jpg?w=1813&h=720&auto=format&fit=crop)
![Where to enter the key in SonarQube](https://assets-eu-01.kc-usercontent.com:443/5e986e54-339c-01a9-7c7c-26cbc5a344d5/e22f2c77-a9ee-4863-8fb3-3a25e9156399/jit-groups.png?w=1056&h=394&auto=format&fit=crop)
- For mapping with the Azure AD app roles, an application role should be assigned to the user. Azure AD sends the role claim automatically with
http://schemas.microsoft.com/ws/2008/06/identity/claims/role
as a key. Enter it as SAML group attribute in SonarQube.
Enabling SCIM provisioning
Starting in Enterprise Edition, once you’ve set up Azure AD as your SAML identity provider, you can set up SCIM provisioning to automate user and group provisioning within Azure AD.
For more information, see SCIM provisioning with Azure AD.
Troubleshooting
Group limit for SAML tokens
Azure SAML tokens have a limit regarding the number of groups a user can belong to (see the description of groups
in the Claims in SAML Token table). In such cases, you might need to reduce the number of groups the user is in.
Was this page helpful?