From: Dimitris Kavvathas Date: Mon, 19 Sep 2022 09:04:23 +0000 (+0200) Subject: SONAR-17229 Improve Azure AD integration documentation X-Git-Tag: 9.7.0.61563~183 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=4403555a430bfa814e261a0e680b953bab9d9594;p=sonarqube.git SONAR-17229 Improve Azure AD integration documentation --- diff --git a/server/sonar-docs/src/images/azure/saml-azure-signature.jpg b/server/sonar-docs/src/images/azure/saml-azure-signature.jpg new file mode 100644 index 00000000000..8fa055c2771 Binary files /dev/null and b/server/sonar-docs/src/images/azure/saml-azure-signature.jpg differ diff --git a/server/sonar-docs/src/pages/instance-administration/authentication/saml/azuread.md b/server/sonar-docs/src/pages/instance-administration/authentication/saml/azuread.md index fb757426f1c..9f9cab97cbe 100644 --- a/server/sonar-docs/src/pages/instance-administration/authentication/saml/azuread.md +++ b/server/sonar-docs/src/pages/instance-administration/authentication/saml/azuread.md @@ -5,71 +5,80 @@ url: /instance-administration/authentication/saml/azuread/ 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**. ![SAML Azure AD New Application](/images/azure/saml-azure-new.jpg) -- Create your **own application** and fill in the **name**. +1. Create your **own application** and fill in the **name**. ![SAML Azure AD Create application](/images/azure/saml-azure-create-application.jpg) ## Link SonarQube with Azure AD -- Navigate to **Single sign-on** and select **SAML**. +1. Navigate to **Single sign-on** and select **SAML**. ![SAML Azure AD SSO](/images/azure/saml-azure-sso.jpg) -- 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 `/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 `/oauth2/callback/saml`. ![SAML Azure AD Basic SAML configuration](/images/azure/saml-azure-basic-saml.jpg) -- 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. ![SAML Azure AD SonarQube Application ID](/images/azure/saml-azure-sq-appid.png) -- 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 ** and copy the **Login URL** and **Azure AD Identifier** ![SAML Azure AD Links](/images/azure/saml-azure-links.jpg) -- 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. ![SAML Azure AD SonarQube Links](/images/azure/saml-azure-sq-links.png) ## 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. ![SAML Azure AD Attributes](/images/azure/saml-azure-attributes.jpg) 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. ![SAML Azure AD SonarQube Attributes](/images/azure/saml-azure-sq-attributes.png) ## Certificates & Signatures -- Navigate to **SAML Certificates** and download **Certificate (Base64)**. +1. Navigate to **SAML Certificates** and download **Certificate (Base64)**. ![SAML Azure AD Certificate](/images/azure/saml-azure-certificate.jpg) -- 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. ![SAML Azure AD SonarQube Certificate](/images/azure/saml-azure-sq-certificate.png) -- (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. ![SAML Azure AD SonarQube Encryption](/images/azure/saml-azure-sq-encryption.png) Import the public key certificate (.cer) file in Azure AD and activate token encryption ![SAML Azure AD Encryption](/images/azure/saml-azure-encryption.jpg) -- 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. + ![SAML Azure AD Encryption](/images/azure/saml-azure-signature.jpg) + In SonarQube, fill in the corresponding private key and the same certificate and enable the **Sign requests** option. ![SAML Azure AD SonarQube certs](/images/azure/saml-azure-sq-certs.png) ## 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. ![SAML Azure AD SonarQube Links](/images/azure/saml-azure-users.jpg) ## 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 ![SAML Azure AD SonarQube Links](/images/azure/saml-azure-group-claim.jpg) ![SAML Azure AD SonarQube Links](/images/azure/saml-azure-sq-groups.png) -- 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. ![SAML Azure AD SonarQube Links](/images/azure/saml-azure-sq-group-role.png) ## Enabling and testing SAML authentication -- In the SonarQube SAML settings, enable SAML. +1. In the SonarQube SAML settings, enable SAML. ![SAML Azure AD SonarQube SAML](/images/azure/saml-azure-sq-saml.png) -- 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. + ![SAML Azure AD SonarQube Login](/images/azure/saml-azure-sq-login.png) diff --git a/server/sonar-docs/src/pages/instance-administration/authentication/saml/okta.md b/server/sonar-docs/src/pages/instance-administration/authentication/saml/okta.md index 4e61ab7a19c..58497ecc7f0 100644 --- a/server/sonar-docs/src/pages/instance-administration/authentication/saml/okta.md +++ b/server/sonar-docs/src/pages/instance-administration/authentication/saml/okta.md @@ -23,83 +23,83 @@ To integrate Okta (Identity Provider) with SonarQube (Service Provider), both si ### Configure SAML settings -Under *General Settings*, configure the following fields: +1. Under *General Settings*, configure the following fields: -- **Single sign on URL**: `/oauth2/callback/saml` (e.g., `https://sonarqube.mycompany.com/oauth2/callback/saml`). + - **Single sign on 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. -![SAML settings](/images/okta/okta-saml-settings.png) + ![SAML settings](/images/okta/okta-saml-settings.png) -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". -![Encryption attributes](/images/okta/okta-encryption-attributes.png) + ![Encryption attributes](/images/okta/okta-encryption-attributes.png) -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`. - ![Attributes](/images/okta/okta-attributes.png) + ![Attributes](/images/okta/okta-attributes.png) -- (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 `.*`. - ![Group attribute](/images/okta/okta-group-attribute.png) + ![Group attribute](/images/okta/okta-group-attribute.png) -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. ![Assign users](/images/okta/okta-assign-users.png) -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. ![Signon tab](/images/okta/okta-signon.png) -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**. ![Setup instructions](/images/okta/okta-setup-instructions.png)