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 SAML configuration (Service Provider), both sides need to be configured.
+To integrate Azure AD (Identity Provider) with SonarQube (Service Provider), both sides need to be configured.
For SonarQube, navigate to **Administration > Authentication > SAML**.
For Azure AD, login to Azure and navigate to Azure AD.
## Set up the SonarQube application in Azure AD
-- In Azure AD, navigate to **Enterprise applications** and add a **New Application**.
+1. In Azure AD, navigate to **Enterprise applications** and add a **New Application**.
-- Create your **own application** and fill in the **name**.
+1. Create your **own application** and fill in the **name**.
## Link SonarQube with Azure AD
-- Navigate to **Single sign-on** and select **SAML**.
+1. Navigate to **Single sign-on** and select **SAML**.
-- Edit the **Basic SAML Configuration** and fill in the **Identifier** and the **Reply URL**. 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`.
+1. Edit the **Basic SAML Configuration** and fill in the **Identifier** and the **Reply URL**. 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`.
-- Fill in the corresponding SonarQube configuration.
+
+ [[info]]
+ |The **Reply URL** uses the **Server base URL** provided in SonarQube under **Administration > General**.
+1. Make sure that the **Application ID** in SonarQube has the same value as the **Identifier** in the Identity Provider.
-- In the Azure AD SAML configuration, navigate to **Set up "application name"** and copy the **Login URL** and **Azure AD Identifier**
+1. In the Azure AD SAML configuration, navigate to **Set up <application name>** and copy the **Login URL** and **Azure AD Identifier**
-- Paste them into the corresponding fields in the SonarQube SAML configuration.
+1. Paste the **Login URL** into the **SAML login url** and the **Azure AD Identifier** into the **Provider ID** field in the SonarQube SAML configuration.
## Attributes and Claims
-- In the Azure AD SAML configuration, edit **Attributes & Claims** to view, edit or add attributes.
+1. In the Azure AD SAML configuration, edit **Attributes & Claims** to view, edit or add attributes.
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.
- - **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. These have to be the same as the group name passed by Azure AD. Otherwise, the default **sonar-users** group is assigned.
- **Note:** The **NameID** attribute is *not* used in SonarQube.
-- Corresponding configuration in SonarQube. The full namespace of the attribute should be used.
+ - **Login** (required) A unique name to identify the user in SonarQube. The default Azure AD attribute `emailaddress` is used in the example.
+ - **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.
+ [[warning]]
+ |The **NameID** attribute is *not* used in SonarQube.
+1. Corresponding configuration in SonarQube. The namespace + name of the attribute should be used, as defined in Azure AD.
## Certificates & Signatures
-- Navigate to **SAML Certificates** and download **Certificate (Base64)**.
+1. Navigate to **SAML Certificates** and download **Certificate (Base64)**.
-- The certificate should be copied into the **Identity provider certificate** field in the SonarQube SAML configuration.
+1. The certificate should be copied into the **Identity provider certificate** field in the SonarQube SAML configuration.
-- (Optional) Encryption for SonarQube requests can be activated by generating an asymmetric key pair.
-
+1. (Optional) Encryption for SonarQube requests can be activated by generating an asymmetric key pair. (For more information, see [SAML token encryption in Azure](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/howto-saml-token-encryption?tabs=azure-portal))
Add the private key in SonarQube.
Import the public key certificate (.cer) file in Azure AD and activate token encryption
-- Azure AD, as an Identity Provider, does not verify signed requests from the Service Providers. SonarQube, however, offers the option for signing the SAML requests by adding a Service Provider private key and certificate.
+1. (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.
+ 
+ In SonarQube, fill in the corresponding private key and the same certificate and enable the **Sign requests** option.
## Users and Groups
-- In the Azure AD SonarQube application, navigate to **Users and groups** and assign users or groups to the application.
+1. In the Azure AD SonarQube application, navigate to **Users and groups** and assign users or groups to the application.
## Group mapping
Group mapping 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.
+For either case, the corresponding group name should exist in SonarQube under **Administration > Security > Groups**. (For more information, see [Authorization](/instance-administration/security/))
- For mapping with the Azure AD groups, a group claim must be added with `sAMAccountName` as a source attribute.
+ [[warning]]
+ |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
-- For mapping with the Azure AD 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.
+- 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.
## Enabling and testing SAML authentication
-- In the SonarQube SAML settings, enable SAML.
+1. In the SonarQube SAML settings, enable SAML.
-- In the login form, the new button **Log in with SAML** (or a custom name specified in the `sonar.auth.saml.providerName` setting) allows users to connect with their SAML account.
+1. In the login form, the new button **Log in with SAML** (or a custom name specified in the `sonar.auth.saml.providerName` setting) allows users to connect with their SAML account.
+
### Configure SAML settings
-Under *General Settings*, configure the following fields:
+1. Under *General Settings*, configure the following fields:
-- **Single sign on URL**: `<Your SonarQube URL>/oauth2/callback/saml` (e.g., `https://sonarqube.mycompany.com/oauth2/callback/saml`).
+ - **Single sign on URL**: `<Your SonarQube URL>/oauth2/callback/saml` (e.g., `https://sonarqube.mycompany.com/oauth2/callback/saml`).
-- **Audience URI (SP Entity ID)**: Something like `sonarqube` (SonarQube default value). It must not contain whitespace.
+ - **Audience URI (SP Entity ID)**: Something like `sonarqube` (SonarQube default value). It must not contain whitespace.
-
+ 
-Assertion signature is mandatory. You must keep the following default settings in *Show Advanced Settings*:
+2. Assertion signature is mandatory. You must keep the following default settings in *Show Advanced Settings*:
-- **Response**: Choose *Signed*.
+ - **Response**: Choose *Signed*.
-- **Assertion Signature**: Choose *Signed*.
+ - **Assertion Signature**: Choose *Signed*.
-- **Signature Algorithm**: Choose *RSA-SHA256*.
+ - **Signature Algorithm**: Choose *RSA-SHA256*.
-(Optional) If you want to enable assertion encryption, expand *Show Advanced Settings* and configure the following fields:
+3. (Optional) If you want to enable assertion encryption, expand *Show Advanced Settings* and configure the following fields:
-- **Assertion Encryption**: Choose *Encrypted*.
+ - **Assertion Encryption**: Choose *Encrypted*.
-- **Encryption Algorithm**: Choose *AES256-GCM* for high security.
+ - **Encryption Algorithm**: Choose *AES256-GCM* for high security.
-- **Key Transport Algorithm**: Choose *RSA-OAEP*.
+ - **Key Transport Algorithm**: Choose *RSA-OAEP*.
-- **Encryption Certificate**: Add the service provider certificate. It should be the same certificate as the one found in the SonarQube SAML settings under "Service provider certificate".
+ - **Encryption Certificate**: Add the service provider certificate. It should be the same certificate as the one found in the SonarQube SAML settings under "Service provider certificate".
-
+ 
-Under **Attribute Statements**, add the following attribute mappings:
+4. Under **Attribute Statements**, add the following attribute mappings:
-- Create a mapping for the *name*:
+ - Create a mapping for the *name*:
- 1. **Name**: `name`.
+ 1. **Name**: `name`.
- 2. **Name format**: *Unspecified*.
+ 2. **Name format**: *Unspecified*.
- 3. **Value**: Choose `user.firstName`.
+ 3. **Value**: Choose `user.firstName`.
-- Create a mapping for the *login*:
+ - Create a mapping for the *login*:
- 1. **Name**: `login`.
+ 1. **Name**: `login`.
- 2. **Name format**: *Unspecified*.
+ 2. **Name format**: *Unspecified*.
- 3. **Value**: Choose `user.login`.
+ 3. **Value**: Choose `user.login`.
-- (Optional) Create a mapping for the *email*:
+ - (Optional) Create a mapping for the *email*:
- 1. **Name**: `email`.
+ 1. **Name**: `email`.
- 2. **Name format**: *Unspecified*.
+ 2. **Name format**: *Unspecified*.
- 3. **Value**: Choose `user.email`.
+ 3. **Value**: Choose `user.email`.
- 
+ 
-- (Optional) Under *Group Attribute Statements* (See details in [Group Mapping](/instance-administration/authentication/overview/)):
+ - (Optional) Under *Group Attribute Statements* (See details in [Group Mapping](/instance-administration/authentication/overview/)):
- 1. **Name**: `groups`.
+ 1. **Name**: `groups`.
- 2. **Name format**: *Unspecified*.
+ 2. **Name format**: *Unspecified*.
- 3. **Filter**: Choose *Matches regex* and set the value to `.*`.
+ 3. **Filter**: Choose *Matches regex* and set the value to `.*`.
- 
+ 
-Click **Finish** in the **Feedback** dialog to confirm the creation of the application.
+5. Click **Finish** in the **Feedback** dialog to confirm the creation of the application.
-You can now add users and groups in the *Assignments* tab of the application.
+6. You can now add users and groups in the *Assignments* tab of the application.
-Navigate to the **Sign On** tab of the *SonarQube* application in Okta.
+7. Navigate to the **Sign On** tab of the *SonarQube* application in Okta.
-Next to the **SAML Signing Certificates** subsection, you will find the configurations needed for setting up SonarQube, under **View SAML setup instructions**.
+8. Next to the **SAML Signing Certificates** subsection, you will find the configurations needed for setting up SonarQube, under **View SAML setup instructions**.
projects / sonarqube.git / commitdiff
