From: Dimitris Kavvathas Date: Tue, 30 Aug 2022 16:00:59 +0000 (+0200) Subject: SONAR-17229 Add Azure AD SAML documentation X-Git-Tag: 9.7.0.61563~293 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=965651c2e1f4d09a543e77941fae1368abbd5adb;p=sonarqube.git SONAR-17229 Add Azure AD SAML documentation --- diff --git a/server/sonar-docs/src/images/saml/saml-azure-attributes.jpg b/server/sonar-docs/src/images/saml/saml-azure-attributes.jpg new file mode 100644 index 00000000000..6f629a49acc Binary files /dev/null and b/server/sonar-docs/src/images/saml/saml-azure-attributes.jpg differ diff --git a/server/sonar-docs/src/images/saml/saml-azure-basic-saml.jpg b/server/sonar-docs/src/images/saml/saml-azure-basic-saml.jpg new file mode 100644 index 00000000000..ddf155190ae Binary files /dev/null and b/server/sonar-docs/src/images/saml/saml-azure-basic-saml.jpg differ diff --git a/server/sonar-docs/src/images/saml/saml-azure-certificate.jpg b/server/sonar-docs/src/images/saml/saml-azure-certificate.jpg new file mode 100644 index 00000000000..3cfdd9156f3 Binary files /dev/null and b/server/sonar-docs/src/images/saml/saml-azure-certificate.jpg differ diff --git a/server/sonar-docs/src/images/saml/saml-azure-create-application.jpg b/server/sonar-docs/src/images/saml/saml-azure-create-application.jpg new file mode 100644 index 00000000000..39fe2ef36df Binary files /dev/null and b/server/sonar-docs/src/images/saml/saml-azure-create-application.jpg differ diff --git a/server/sonar-docs/src/images/saml/saml-azure-links.jpg b/server/sonar-docs/src/images/saml/saml-azure-links.jpg new file mode 100644 index 00000000000..e31e6516011 Binary files /dev/null and b/server/sonar-docs/src/images/saml/saml-azure-links.jpg differ diff --git a/server/sonar-docs/src/images/saml/saml-azure-new.jpg b/server/sonar-docs/src/images/saml/saml-azure-new.jpg new file mode 100644 index 00000000000..9c66238205c Binary files /dev/null and b/server/sonar-docs/src/images/saml/saml-azure-new.jpg differ diff --git a/server/sonar-docs/src/images/saml/saml-azure-sq-appid.png b/server/sonar-docs/src/images/saml/saml-azure-sq-appid.png new file mode 100644 index 00000000000..1794ff2acf9 Binary files /dev/null and b/server/sonar-docs/src/images/saml/saml-azure-sq-appid.png differ diff --git a/server/sonar-docs/src/images/saml/saml-azure-sq-attributes.png b/server/sonar-docs/src/images/saml/saml-azure-sq-attributes.png new file mode 100644 index 00000000000..ba9481bf700 Binary files /dev/null and b/server/sonar-docs/src/images/saml/saml-azure-sq-attributes.png differ diff --git a/server/sonar-docs/src/images/saml/saml-azure-sq-certificate.png b/server/sonar-docs/src/images/saml/saml-azure-sq-certificate.png new file mode 100644 index 00000000000..29f4c190128 Binary files /dev/null and b/server/sonar-docs/src/images/saml/saml-azure-sq-certificate.png differ diff --git a/server/sonar-docs/src/images/saml/saml-azure-sq-links.png b/server/sonar-docs/src/images/saml/saml-azure-sq-links.png new file mode 100644 index 00000000000..f38a171b17d Binary files /dev/null and b/server/sonar-docs/src/images/saml/saml-azure-sq-links.png differ diff --git a/server/sonar-docs/src/images/saml/saml-azure-sq-login.png b/server/sonar-docs/src/images/saml/saml-azure-sq-login.png new file mode 100644 index 00000000000..2acc582d432 Binary files /dev/null and b/server/sonar-docs/src/images/saml/saml-azure-sq-login.png differ diff --git a/server/sonar-docs/src/images/saml/saml-azure-sq-saml.png b/server/sonar-docs/src/images/saml/saml-azure-sq-saml.png new file mode 100644 index 00000000000..dabad676d27 Binary files /dev/null and b/server/sonar-docs/src/images/saml/saml-azure-sq-saml.png differ diff --git a/server/sonar-docs/src/images/saml/saml-azure-sso.jpg b/server/sonar-docs/src/images/saml/saml-azure-sso.jpg new file mode 100644 index 00000000000..7d6374f1cf5 Binary files /dev/null and b/server/sonar-docs/src/images/saml/saml-azure-sso.jpg differ diff --git a/server/sonar-docs/src/images/saml/saml-azure-users.jpg b/server/sonar-docs/src/images/saml/saml-azure-users.jpg new file mode 100644 index 00000000000..ec2312742b1 Binary files /dev/null and b/server/sonar-docs/src/images/saml/saml-azure-users.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 37aaca8620e..5a1c3044a89 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 @@ -3,5 +3,56 @@ title: How to setup Azure AD url: /instance-administration/authentication/saml/azuread/ --- -### Using Azure AD as a SAML Identity Provider +## Using Azure AD as a SAML Identity Provider 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. + +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**. + ![SAML Azure AD New Application](/images/saml/saml-azure-new.jpg) +- Create your **own application** and fill in the **name**. + ![SAML Azure AD Create application](/images/saml/saml-azure-create-application.jpg) + +### Link SonarQube with Azure AD +- Navigate to **Single sign-on** and select **SAML**. + ![SAML Azure AD SSO](/images/saml/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`. + ![SAML Azure AD Basic SAML configuration](/images/saml/saml-azure-basic-saml.jpg) +- Fill in the corresponding SonarQube configuration. + ![SAML Azure AD SonarQube Application ID](/images/saml/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** + ![SAML Azure AD Links](/images/saml/saml-azure-links.jpg) +- Paste them into the corresponding fields in the SonarQube SAML configuration. + ![SAML Azure AD SonarQube Links](/images/saml/saml-azure-sq-links.png) + +### Attributes and Claims +- In the Azure AD SAML configuration, edit **Attributes & Claims** to view, edit or add attributes. + ![SAML Azure AD Attributes](/images/saml/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. + ![SAML Azure AD SonarQube Attributes](/images/saml/saml-azure-sq-attributes.png) + +### Certificates & Signatures +- Navigate to **SAML Certificates** and download **Certificate (Base64)**. + ![SAML Azure AD Certificate](/images/saml/saml-azure-certificate.jpg) +- The certificate should be copied into the **Identity provider certificate** field in the SonarQube SAML configuration. + ![SAML Azure AD SonarQube Certificate](/images/saml/saml-azure-sq-certificate.png) + +### Users and Groups +- 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/saml/saml-azure-users.jpg) + +### Enabling and testing SAML authentication +- In the SonarQube SAML settings, enable SAML. + ![SAML Azure AD SonarQube SAML](/images/saml/saml-azure-sq-saml.png) +- Logout and try to log in again. If all the mandatory fields are filled in, the Azure SAML integration should appear. + ![SAML Azure AD SonarQube Login](/images/saml/saml-azure-sq-login.png)