/sonar-auth-aad

Azure Active Directory Authentication for SonarQube

Primary LanguageJavaOtherNOASSERTION

Azure Active Directory (AAD) Authentication Plug-in for SonarQube

Build Status

Description

This plug-in enables Azure Active Directory (AAD) users to automatically be sign up (a login is created if they don’t have one already) and authenticated on a SonarQube server.

Prerequisites

Enable HTTPS on SonarQube

The Azure Active Directory Authentication Plug-in for SonarQube is an OAuth 2.0 provider for SonarQube. For security reasons, HTTP is not supported. HTTPS must be used, by configuring it on the SonarQube server if this is not done already.

Server base URL property must be set to this HTTPS URL either by setting the property from SonarQube administration page (General -> Server base URL) or through setting sonar.core.serverBaseURL key value in the sonar.properties file.

For more details, on how to setup HTTPS on SonarQube, please see Securing the Server behind a Proxy

Create Active Directory application under your Azure Active Directory tenant

  1. Sign in to the Azure management portal.

  2. Click Azure Active Directory in the left navigation bar.

  3. Click App registrations, and then select New application registration

  4. Follow the prompts to create a Web Application and/or WebAPI.

    1. Name describes the app to users, for example SonarQube Azure Authentication
    2. Application type should be "Web app / API"
    3. Sign-On URL is the base URL for your SonarQube Server, example https://localhost:9000. You can change this later as needed.
    4. Click on the Create button

  5. After you've completed the registration, Azure AD assigns the app a unique application ID. Copy the value from the app page, you will need later to to set the Client ID.

  6. Go into the Settings page of your application

    1. In Reply URL, remove the existing URL. Add SonarQube Server URL and append https://<SonarQube_ServerURL>/oauth2/callback/aad, example https://localhost:9000/oauth2/callback/aad

    2. In Keys, create a key for your application with 1 year expiry duration. Copy the value of the key, you will need later to set the Client Secret.

    3. In Required permissions, make sure the application has access to Windows Azure Active Directory API. The following delegated permissions need to be enabled.

      • Sign in and read user profile
      • Read all users' basic profiles

      Sign-in permission

  7. If you enabled group synchronization, make sure the application has access to the Windows Azure Active Directory API. The following delegated permissions needs to be enabled.

    • Read directory data

    • Read all user's basic profiles

    • Sign in and read user profile

      groups permission

    It's best security practice to grant your registered applications the least amount of privileges possible. If you don't plan on using the group synchronization feature, avoid enabling the "Read directory data" permission.

    Once this is enabled, you will need to create new Azure groups of the type "Security". The names of these groups need to correspond to the names of the groups in SonarQube. Once you've created the groups, add your Azure users to it.

    Lastly, you still need to grant users access to your registered application. You can add them by going to Enterprise applications, your application's name (whatever you named your application when registering it), Users and groups, then finally click "Add user" at the top.

  8. If your application is a single tenant application, you need to provide the tenant id in the provider settings. You can retrieve the tenant id by leaving the App Registration and navigating to the Properties section of the tenant and retrieving the Directory ID as shown below.

  9. Make a note of the Application ID, Key value, and tenant Id. You will need this later when you configure your application. 

For a more detailed walkthrough, Create Active Directory application and service principal using portal.

Installation and configurations

Install Azure AD Authentication plug-in

  1. Download and Copy sonar-auth-aad-plugin-1.0 to SonarQube server plugin folder under extensions folder. You can download the plugin from SonarQube Update Center or from GitHub https://github.com/SonarQubeCommunity/sonar-auth-aad/releases

  2. Restart SonarQube Server

Configure Azure AD Authentication plugin

  1. Login to SonarQube with an administration account.

  2. On the main menu, go to Administration .

  3. Click Azure Active Directory under Category menu, and provide the following values:

    1. Set the Enabled property to true

    2. Set the Client ID from the value provided by the Azure AD application (Application ID).

    3. Set the Client Secret from the value provided by the Azure AD application.

    4. Set the Multi-tenant Azure Application value based on the configuration of the Azure application.

    5. For a single tenant application, set the Tenant ID to the Azure AD tenant Id.

    6. Set Login generation strategy value:

      1. 'Unique', the user's login will be auto-generated the first time so that it is unique.

      2. 'Same as Azure AD login', the user's login will be the Azure AD login.

    7. Click Save Authentication Settings.

    8. Sign out and go to the log in form. A new button named "Log in with Microsoft" allows users to sign in with their Azure AD account. For login with username and password, clicking "More options" reveals the login form.

    Login with Microsoft

General Configurations

AAD Final Settings

Property Key Property Name Description Default value
sonar.auth.aad.enabled Enabled Enable Azure AD users to log in. Value is ignored if client ID and secret are not defined. false
sonar.auth.aad.clientId.secured Client ID Client ID provided by Azure AD when registering the application. None
sonar.auth.aad.clientSecret.secured Client Secret Client password provided by Azure AD when registering the application. None
sonar.auth.aad.multiTenant Multi-tenant Azure Application Set the value to True if users from other Azure Active Directories can consent to the application and sign in to it. false
sonar.auth.aad.tenantId Tenant ID Azure Active Directory Tenant Id. This value is optional if sonar.auth.aad.multiTenant set to True None
sonar.auth.aad.allowUsersToSignUp Allow users to sign-up Allow new users to authenticate. When set to 'false', only existing users will be able to authenticate to the server. true
sonar.auth.aad.loginStrategy Login generation strategy When the login strategy is set to 'Unique', the user's login will be auto-generated the first time so that it is unique. When the login strategy is set to 'Same as Azure AD login', the user's login will be the Azure AD login. This last strategy allows, when changing the authentication provider, to keep existing users if logins from a new provider are the same as Azure AD). Unique
sonar.auth.aad.directoryLocation Directory Location The location of the Azure installation. You normally won't need to change this. Azure AD (Global)

Groups Synchronization

This feature was introduced in the 1.1-RC1 version of the plugin.

Groups sync Settings

Property Key Property Name Description Default value
sonar.auth.aad.enableGroupsSync Enable Groups Synchronization Enable groups syncronization from Azure AD to SonarQube, For each Azure AD group user belongs to, the user will be associated to a group with the same name(if it exists) in SonarQube. false

Additional Configurations

  1. Customize Profile Picture This can be simply done by linking your email to an existing Gravitar account or by creating a new one. In SonarQube Gravitar support is enabled by default, using gravitar.com. You can configure a different server or disable the feature altogether. Refer to Look and Feel

  2. Managing AAD users access to SonarQube To restrict access to SonarQube to a given group of AAD users, there are currently two ways to do so:

    1. From SonarQube Server, set "Allow Users to SignUp" property to False in AAD settings. When set to 'false', only existing local/AAD users will be able to authenticate to the server. SonarQube Administrator can add local users manually to the server. refer to Authentication

    2. From Azure Active Directory Application settings, restricting the access to the Azure application you created in "Create Active Directory application under your Azure Active Directory tenant" section. Refer to Managing access to apps

Troubleshooting

  • Some users havving IIS as a reverse proxy reported getting an HTTP 404 error while submitting a new project analysis when the size of the SonarQube analysis report was too big. This was due to IIS max request length (set to 1000000 bytes (9.5MB) by default). To increase the max request length on IIS:

    1. Connect to the server
    2. Highlight the server in the "Connections" pane, and double-click on "request filtering"
    3. In the "Actions" pane, click "Edit Feature Settings..."
    4. Modify the "Maximum allowed content length" field to the desired maximum size in bytes

  • Some users having IIS as a reverse proxy with SSL certificate following the tutorial Configure SSL for SonarQube on Windows when try to login with Azure Active Directory the URL has as hostname the same as default domain. To perform login without this issue:

    1. Go to the windows server.
    2. Open IIS Manager (Internet Information Services Manager).
    3. Highlight the server in the "Connections" pane, and double-click on "Application Request Routing Cache"
    4. In the "Actions" pane, click "Server Proxy Settings..."
    5. Uncheck "Reverse rewrite host in response headers" Then, when you click on Log in with Microsoft in Login page, the redirection to login.microsoftonline.com correctly.