diff options
| author | Dimitris Kavvathas <dimitris.kavvathas@sonarsource.com> | 2022-09-19 11:04:23 +0200 |
|---|---|---|
| committer | sonartech <sonartech@sonarsource.com> | 2022-09-22 20:03:33 +0000 |
| commit | 4403555a430bfa814e261a0e680b953bab9d9594 (patch) | |
| tree | e8adcf7047fd5cde719f61a75bae375adbfdd907 | |
| parent | 3eeb15ab739dc67d135128142a37b8c75635a8d1 (diff) | |
| download | sonarqube-4403555a430bfa814e261a0e680b953bab9d9594.tar.gz sonarqube-4403555a430bfa814e261a0e680b953bab9d9594.zip | |
SONAR-17229 Improve Azure AD integration documentation
3 files changed, 71 insertions, 62 deletions
diff --git a/server/sonar-docs/src/images/azure/saml-azure-signature.jpg b/server/sonar-docs/src/images/azure/saml-azure-signature.jpg Binary files differnew file mode 100644 index 00000000000..8fa055c2771 --- /dev/null +++ b/server/sonar-docs/src/images/azure/saml-azure-signature.jpg 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**.  -- 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. +  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**: `<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**.  |
