Merge pull request #11788 from DefectDojo/master-into-dev/2.43.1-2.44.0-dev

Release: Merge back 2.43.1 into dev from: master-into-dev/2.43.1-2.44.0-dev

Author: rossops

docs/content/en/customize_dojo/user_management/configure_sso.md

@@ -17,7 +17,7 @@ Users can connect to DefectDojo with a Username and Password, but if you prefer,
 All of these methods can only be configured by a Superuser in DefectDojo.  DefectDojo Pro users can quickly set up SSO through their system settings, while Open Source users will need to configure these settings on the back-end via the local_settings.py file.  This article covers both methods of configuration.
 
 ## Disable username / password use
-You may wish to disable traditional username/password login on your instance.  
+You may wish to disable traditional username/password login on your instance.
 
 <span style="background-color:rgba(242, 86, 29, 0.3)">DefectDojo Pro</span> users can uncheck the "Allow Login via Username and Password" box on the Login Settings form: **Enterprise Settings > Login Settings**.
 
@@ -68,7 +68,7 @@ Both <span style="background-color:rgba(242, 86, 29, 0.3)">DefectDojo Pro</span>
 
 ### Open-Source
 
-Open-Source users will need to map these variables in the local_settings.py file. (see [Configuration](../../os_getting_started/configuration)).
+Open-Source users will need to map these variables in the local_settings.py file. (see [Configuration](../../open_source/installation/configuration/)).
 
 1. Fill out the variables as follows:
     {{< highlight python >}}
@@ -141,7 +141,7 @@ When a user is removed from a given group in Azure AD, they will also be removed
 
 ### Open-Source
 
-Open-Source users will need to map these variables in the local_settings.py file. (see [Configuration](../../os_getting_started/configuration)).
+Open-Source users will need to map these variables in the local_settings.py file. (see [Configuration](../../open_source/installation/configuration)).
 
 1.  Add the following information to the settings file:
 
@@ -155,7 +155,7 @@ Open-Source users will need to map these variables in the local_settings.py file
 2.  Restart DefectDojo, and you should now see a **Login with Azure AD** button on the login page.
 
 #### Open-Source Azure Group Mapping
-To import groups from Azure AD users, the following environment variable needs to be set:  
+To import groups from Azure AD users, the following environment variable needs to be set:
 
     {{< highlight python >}}
     DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_GET_GROUPS=True
@@ -170,7 +170,7 @@ If unsure of what type that is, select `All Groups`. Do not activate `Emit group
 Application API permissions need to be updated with the `Group.Read.All` permission so that groups can be read on behalf of the user that has successfully signed in.
 
 To limit the amount of groups imported from Azure AD, a regular expression can be used as the following:
-    
+
     {{< highlight python >}}
     DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_GROUPS_FILTER='^team-.*' # or 'teamA|teamB|groupC'
     {{< /highlight >}}
@@ -208,24 +208,24 @@ Both <span style="background-color:rgba(242, 86, 29, 0.3)">DefectDojo Pro</span>
     - **GitHub Enterprise OAuth Secret**: enter your GitHub Enterprise Client Secret
     - **GitHub Enterprise URL**: enter the GitHub URL for your organization, likely `https://github.<your_company>.com/`
     - **GitHub Enterprise API URL**: enter the URL for your organization's GitHub API (e.g. `https://github.<your_company>.com/api/v3/`)
-    
+
 2. Check off the box for 'Enable GitHub Enterprise OAuth'.  Submit the form, and 'Login With GitHub' should now be visible on the login page.
 
 ### Open-Source
 
-Open-Source users will need to map these variables in the local_settings.py file. (see [Configuration](../../os_getting_started/configuration)).
+Open-Source users will need to map these variables in the local_settings.py file. (see [Configuration](../../open_source/installation/configuration)).
 
 1. Add the following variables to your `local_settings.py` file:
-    {{< highlight python >}}  
-    DD_SOCIAL_AUTH_GITHUB_ENTERPRISE_KEY=(str, 'GitHub Enterprise OAuth App Client ID'),  
-    DD_SOCIAL_AUTH_GITHUB_ENTERPRISE_SECRET=(str, 'GitHub Enterprise OAuth App Client Secret'),  
-    DD_SOCIAL_AUTH_GITHUB_ENTERPRISE_URL=(str, 'https://github.<your_company>.com/'),  
-    DD_SOCIAL_AUTH_GITHUB_ENTERPRISE_API_URL=(str, 'https://github.<your_company>.com/api/v3/'),  
-    DD_SOCIAL_AUTH_GITHUB_ENTERPRISE_OAUTH2_ENABLED = True,  
+    {{< highlight python >}}
+    DD_SOCIAL_AUTH_GITHUB_ENTERPRISE_KEY=(str, 'GitHub Enterprise OAuth App Client ID'),
+    DD_SOCIAL_AUTH_GITHUB_ENTERPRISE_SECRET=(str, 'GitHub Enterprise OAuth App Client Secret'),
+    DD_SOCIAL_AUTH_GITHUB_ENTERPRISE_URL=(str, 'https://github.<your_company>.com/'),
+    DD_SOCIAL_AUTH_GITHUB_ENTERPRISE_API_URL=(str, 'https://github.<your_company>.com/api/v3/'),
+    DD_SOCIAL_AUTH_GITHUB_ENTERPRISE_OAUTH2_ENABLED = True,
     {{< /highlight >}}
 
 2. Restart DefectDojo, and you should now see a **Login with GitHub Enterprise**
-    button on the login page.  
+    button on the login page.
 
 ## GitLab
 
@@ -259,7 +259,7 @@ Follow along below.
 
 ### Open-Source
 
-Open-Source users will need to map these variables in the local_settings.py file. (see [Configuration](../../os_getting_started/configuration)).
+Open-Source users will need to map these variables in the local_settings.py file. (see [Configuration](../../open_source/installation/configuration)).
 
 1. Add the following variables to your `local_settings.py` file:
     {{< highlight python >}}
@@ -277,7 +277,7 @@ Open-Source users will need to map these variables in the local_settings.py file
     {{< /highlight >}}
 
     **Important:** if you enable this setting on already working instance with a GitLab integrations, it will require new grant "read_repository" by user
- 
+
 2. Restart DefectDojo, and you should now see a **Login with Gitlab** button on the login page.
 
 ## Google Auth
@@ -320,7 +320,7 @@ In order to use Google Authentication, a Google Authentication Server will need
 
 ### Open-Source
 
-Open-Source users will need to map these variables in the local_settings.py file. (see [Configuration](../../os_getting_started/configuration)).
+Open-Source users will need to map these variables in the local_settings.py file. (see [Configuration](../../open_source/installation/configuration)).
 
 1. Add the following variables to your `local_settings.py` file:
 
@@ -336,7 +336,7 @@ Open-Source users will need to map these variables in the local_settings.py file
     DD_SOCIAL_AUTH_GOOGLE_OAUTH2_WHITELISTED_DOMAINS = ['example.com', 'example.org']
     {{< /highlight >}}
 
-    As an environment variable: 
+    As an environment variable:
 
     {{< highlight python >}}
     DD_SOCIAL_AUTH_GOOGLE_OAUTH2_WHITELISTED_DOMAINS = example.com,example.org
@@ -348,7 +348,7 @@ Open-Source users will need to map these variables in the local_settings.py file
     DD_SOCIAL_AUTH_GOOGLE_OAUTH2_WHITELISTED_EMAILS = ['<email@example.com>']
     {{< /highlight >}}
 
-    As an environment variable: 
+    As an environment variable:
 
     {{< highlight python >}}
     DD_SOCIAL_AUTH_GOOGLE_OAUTH2_WHITELISTED_EMAILS = email@example.com,email2@example.com
@@ -374,7 +374,7 @@ This guide assumes you already have a KeyCloak Realm set up.  If not, you will n
 
 3. Under `Scope` -> `Full Scope Allowed` set to `off`.
 
-4. Under `mappers` -> add a custom mapper here: 
+4. Under `mappers` -> add a custom mapper here:
    * Name: `aud`
    * Mapper type: `audience`
    * Included audience: select your client/client-id here
@@ -403,21 +403,21 @@ This guide assumes you already have a KeyCloak Realm set up.  If not, you will n
 
 ### Open-Source
 
-Edit the local_settings.py file (see [Configuration](../../os_getting_started/configuration)) with the following information:
+Edit the local_settings.py file (see [Configuration](../../open_source/installation/configuration)) with the following information:
 
 1.    {{< highlight python >}}
    DD_SESSION_COOKIE_SECURE=True,
    DD_CSRF_COOKIE_SECURE=True,
    DD_SECURE_SSL_REDIRECT=True,
    DD_SOCIAL_AUTH_KEYCLOAK_OAUTH2_ENABLED=True,
    DD_SOCIAL_AUTH_KEYCLOAK_PUBLIC_KEY=(str, '<your realm public key>'),
-   DD_SOCIAL_AUTH_KEYCLOAK_KEY=(str, '<your client id>'), 
-   DD_SOCIAL_AUTH_KEYCLOAK_SECRET=(str, '<your keycloak client credentials secret>'), 
+   DD_SOCIAL_AUTH_KEYCLOAK_KEY=(str, '<your client id>'),
+   DD_SOCIAL_AUTH_KEYCLOAK_SECRET=(str, '<your keycloak client credentials secret>'),
    DD_SOCIAL_AUTH_KEYCLOAK_AUTHORIZATION_URL=(str, '<your authorization endpoint>'),
-   DD_SOCIAL_AUTH_KEYCLOAK_ACCESS_TOKEN_URL=(str, '<your token endpoint>')         
+   DD_SOCIAL_AUTH_KEYCLOAK_ACCESS_TOKEN_URL=(str, '<your token endpoint>')
    {{< /highlight >}}
- 
-or, alternatively, for helm configuration, add this to the `extraConfig` section: 
+
+or, alternatively, for helm configuration, add this to the `extraConfig` section:
 
 ```yaml
 DD_SESSION_COOKIE_SECURE: 'True'
@@ -431,7 +431,7 @@ DD_SOCIAL_AUTH_KEYCLOAK_AUTHORIZATION_URL: '<your authorization endpoint>'
 DD_SOCIAL_AUTH_KEYCLOAK_ACCESS_TOKEN_URL: '<your token endpoint>'
 ```
 
-Optionally, you *can* set `DD_SOCIAL_AUTH_KEYCLOAK_LOGIN_BUTTON_TEXT` in order to customize the login button's text caption. 
+Optionally, you *can* set `DD_SOCIAL_AUTH_KEYCLOAK_LOGIN_BUTTON_TEXT` in order to customize the login button's text caption.
 
 2. Restart DefectDojo, and `Login With ____` (your login button text) will be added as an option to the Login menu.
 
@@ -445,7 +445,7 @@ Both <span style="background-color:rgba(242, 86, 29, 0.3)">DefectDojo Pro</span>
 1.  Navigate to the following address and either create a new account,
     or login with an existing one: [Okta Account
     Creation](https://www.okta.com/developer/signup/)
-    
+
 2.  Once logged in, enter the **Applications** and click **Add
     Application**:
 
@@ -489,7 +489,7 @@ Both <span style="background-color:rgba(242, 86, 29, 0.3)">DefectDojo Pro</span>
 
 ### Open-Source
 
-1. Edit the local_settings.py file (see [Configuration](../../os_getting_started/configuration)) with the following:
+1. Edit the local_settings.py file (see [Configuration](../../open_source/installation/configuration)) with the following:
 
     {{< highlight python >}}
     DD_SOCIAL_AUTH_OKTA_OAUTH2_ENABLED=True,
@@ -515,27 +515,27 @@ GET parameter starts with `http://` instead of
 
 ![image](images/sso_betaui_1.png)
 
-2. Complete the SAML form. Start by setting an **Entity ID** \- this is either a label or a URL which your SAML Identity Provider can point to, and use to identify DefectDojo. This is a required field.  
+2. Complete the SAML form. Start by setting an **Entity ID** \- this is either a label or a URL which your SAML Identity Provider can point to, and use to identify DefectDojo. This is a required field.
 ​
-3. If you wish, set **Login Button Text** in DefectDojo. This text will appear on the button or link users click to initiate the login process.  
+3. If you wish, set **Login Button Text** in DefectDojo. This text will appear on the button or link users click to initiate the login process.
 ​
-4. You can also set a **Logout URL** to redirect your users to once they have logged out of DefectDojo.  
+4. You can also set a **Logout URL** to redirect your users to once they have logged out of DefectDojo.
 ​
-5. The **Name ID Format** has four options: Persistent, Transient, Entity and Encrypted.  
-​   
-    - If you would prefer that users have a different SAML ID each time they access   
-    DefectDojo, choose **Transient**.   
-    - If you want your users to be consistently identified by SAML, use **Persistent.**   
-    - If you’re ok with all of your users sharing a SAML NameID, you can select **Entity.**   
+5. The **Name ID Format** has four options: Persistent, Transient, Entity and Encrypted.
+​
+    - If you would prefer that users have a different SAML ID each time they access
+    DefectDojo, choose **Transient**.
+    - If you want your users to be consistently identified by SAML, use **Persistent.**
+    - If you’re ok with all of your users sharing a SAML NameID, you can select **Entity.**
     - If you would like to encrypt each user’s NameID, you can use **Encrypted** as your NameID format.
 ​
-6. **Required Attributes** are the attributes that DefectDojo requires from the SAML response.  
+6. **Required Attributes** are the attributes that DefectDojo requires from the SAML response.
+​
+7. **Attribute Mapping** contains a formula for how you want these attributes to be matched to a user. For example, if your SAML response returns an email, you can associate it with a DefectDojo user with the formula **email=email**.
 ​
-7. **Attribute Mapping** contains a formula for how you want these attributes to be matched to a user. For example, if your SAML response returns an email, you can associate it with a DefectDojo user with the formula **email=email**.  
-​  
 The left side of the ‘=’ sign represents the attribute you want to map from the SAML response. The right side is a user’s field in DefectDojo, which you want this attribute to map to.
 ​
-8. **Remote SAML Metadata** is the URL where your SAML Identity Provider is located.  
+8. **Remote SAML Metadata** is the URL where your SAML Identity Provider is located.
 ​
 9. Finally, check the **Enable SAML** checkbox at the bottom of this form to confirm that you want to use SAML to log in. Once this is enabled, you will see the **Login With SAML** button on the DefectDojo Login Page.
 
@@ -558,7 +558,7 @@ The left side of the ‘=’ sign represents the attribute you want to map from
 ### Open-Source SAML
 
 1.  Navigate to your SAML IdP and find your metadata.
-2.  Edit the local_settings.py file (see [Configuration](../../os_getting_started/configuration)) with the following information:
+2.  Edit the local_settings.py file (see [Configuration](../../open_source/installation/configuration)) with the following information:
 
     {{< highlight python >}}
     DD_SAML2_ENABLED=(bool, **True**),