Skip to content

Setup

Jump to bottom
Michael Johnson edited this page Feb 27, 2023 · 8 revisions

Setting Up the Plugin

Note: Microsoft requires that you use HTTPS for applications communicating with their authentication system. You must have your SonarQube environment working over HTTPS before you can enable this plugin.

Before starting this process, it is recommended that you first install the plugin to your SonarQube environment. You can do this from the Marketplace inside SonarQube, or download the plugin jar file directly from the releases page and place inside the extensions/plugins directory in your SonarQube installation. After installing the plugin, you need to restart SonarQube to load the plugin.

Once installed, you can register the SonarQube application in your Azure Active Directory to gather the values needed to configure and enable AAD authentication.

Multi or Single Tenant

It is important to decide if you are going to be authenticating in a single tenant or a multiple tenant style.

A single tenant setup restricts login via Azure Active Directory to only those users that have accounts in or are guests in your Azure environment. This is the most common configuration and is the default for the plugin.

A multi-tenant setup allows users in different Azure Active Directories to authenticate and login to your SonarQube installation. This can be useful if, for example, you have contractors or customers that have their own Azure setup and want to login with these accounts. Group sync and national cloud support will not work with this setup.

Single Tenant Config

  1. Sign into the Azure Management Portal. (If you are using one of the "national cloud" Azure instances, log in using the correct portal URL for your country.)

  2. Open the Azure Active Directory blade from either the shortcut on the left sidebar or search in the search box at the top.

  3. Inside the blade, select Properties from the Manage category and copy down the "Tenant ID". You will enter this in the plugin settings.

Multi-Tenant Config

Note: In a multi-tenant configuration, anyone with an Azure login can authenticate, so you will need to take additional measures inside SonarQube to secure information there.

No steps are needed on the Azure Management Portal for a multi-tenant setup.

Creating the SonarQube Application in Azure

Note: While the below steps were current when written, the Azure Portal changes frequently. If things look different to you, you can reference the official docs linked at the end of this section for guidance.

  1. To begin, sign into the Azure Management Portal. (If you are using one of the "national cloud" Azure instances, log in using the correct portal URL for your country.)

  2. Open the Azure Active Directory blade from the shortcut on the left sidebar or search in the search box at the top.

  3. On the sidebar, under the Manage category, choose App registrations and then select New registration from the top bar.

  4. Fill in the form that appears and click the "Create" button once done.

    a. Name should be the name of your application. It may be shown to users in some cases, so pick something like "SonarQube" or "MyCompany SonarQube".

    b. Supported account types can be set to any option based on if you want to support multi-tenant logins or not. This can be changed later, so it is safe to start with the option for "Single Tenant"

    c. Redirect URI should be set to "Web" in the dropdown. For the URL field, you will put in the special authentication URL for this plugin. This URL is your main SonarQube URL with "/oauth2/callback/aad" at the end. For example, if your main URL is "https://sonarqube.example.com/", you would enter "https://sonarqube.example.com/oauth2/callback/aad".

    Once these are filled out, you can click Register to register the application.

  5. When the registration is complete, you should be taken to a screen with information on the new application. Copy down the "Application (client) ID", it's used as the "Client ID" in the plugin settings.

  6. Choose Authentication from the sidebar. In the section titled "Implicit grant and hybrid flows", look for the option titled "ID tokens (used for implicit and hybrid flows)" and check the box labeled. Click Save to save this change.

  7. Click on Certificates & secrets from the sidebar and click on New client secret. You can type anything you want in the "Key Description" field. Select the expiration length you want. Keep in mind that longer expiration times will lower security. Once done, click Add. Once the process finishes, you will see the new secret on the screen. Copy data for the "Value", it's used as the "Client Secret" in the plugin settings.

For more details on the application creation procedure, you can reference the Microsoft document How to: Use the portal to create an Azure AD application and service principal that can access resources

Configuring the Plugin in SonarQube

If you have not installed the plugin yet, you will need to do so before you continue with these steps.

Note: Each setting has its own save button when you modify it. Make sure to click the "Save" button after you change each setting.

  1. Log into your SonarQube install with a local account that has administrative permission.

  2. Make sure you have set Server base URL under Settings/General to the root of the SonarQube installation without a trailing slash (For example http://sonarqube.yourdomain.com).

  3. Click on the Administration header at the top, then select the Azure Active Directory tab from the general settings area. If you do not see this section, ensure the plugin is installed and that you have restarted SonarQube to load the plugin.

  4. Fill in the Client ID and Client Secret fields with the values you copied down from the Azure Management Portal.

  5. This step varies depending on if you are installing single or multiple tenant:

    Single-tenant: If you are setting up SonarQube as a single tenant application, fill in the Tenant ID field with the value you copied down.

    Multi-tenant: If you are setting up as a multi-tenant application, toggle the setting labeled Multi-tenant Azure Application to on/enabled.

  6. Toggle the setting labeled Enabled to on/enabled to activate the plugin.

At this point, any users on your Azure Active Directory can sign in to SonarQube. The login page will have changed slightly, looking much like the image:

A new button labeled "Log in with Microsoft" will allow users to use AAD to log in. The username and password fields for local accounts are now behind a link labeled "More options".

Advanced Options

This plugin supports group synchronization with your Azure Active Directory. If you want to set this up, you can look at the documentation on Group Synchronization.

Contents

Clone this wiki locally