Add latest changes from gitlab-org/gitlab@master

2 files changed, 134 insertions, 4 deletions

diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md
index dcbaff70633..af8c6a3feb0 100644
--- a/doc/user/application_security/dast/index.md
+++ b/doc/user/application_security/dast/index.md
@@ -253,6 +253,85 @@ LoadModule proxy_http_module modules/mod_proxy_http.so
 [This snippet](https://gitlab.com/gitlab-org/security-products/dast/snippets/1894732) contains a complete `httpd.conf` file
 configured to act as a remote proxy and add the `Gitlab-DAST-Permission` header.
 
+### API scan
+
+Using an API specification as a scan's target is a useful way to seed URLs for scanning an API.
+Vulnerability rules in an API scan are different than those in a normal website scan.
+
+#### Specification format
+
+API scans support OpenAPI V2 and OpenAPI V3 specifications. You can define these specifications using `JSON` or `YAML`.
+
+#### Import API specification from a URL
+
+If your API specification is accessible at a URL, you can pass that URL in directly as the target.
+The specification doesn't have to be hosted on the same host as the API being tested.
+
+```yml
+include:
+  - template: DAST.gitlab-ci.yml
+
+variables:
+  DAST_API_SPECIFICATION: http://my.api/api-specification.yml
+```
+
+#### Import API specification from a file
+
+If your API specification is in your repository, you can provide the specification's filename directly as the target. The specification file is expected to be in the `/zap/wrk` directory.
+
+```yml
+dast:
+  script:
+    - mkdir -p /zap/wrk
+    - cp api-specification.yml /zap/wrk/api-specification.yml
+    - /analyze -t $DAST_WEBSITE
+  variables:
+    GIT_STRATEGY: fetch
+    DAST_API_SPECIFICATION: api-specification.yml
+```
+
+#### Full scan
+
+API scans support full scanning, which can be enabled by using the `DAST_FULL_SCAN_ENABLED` environment variable. Domain validation isn't supported for full API scans.
+
+#### Host override
+
+Specifications often define a host, which contains a domain name and a port. The host referenced may be different than the host of the API's review instance.
+This can cause incorrect URLs to be imported, or a scan on an incorrect host. Use the `DAST_API_HOST_OVERRIDE` environment variable to override these values.
+
+For example, with a OpenAPI V3 specification containing:
+
+```yml
+servers:
+  - url: https://api.host.com
+```
+
+If the test version of the API is running at `https://api-test.host.com`, then the following DAST configuration can be used:
+
+```yml
+include:
+  - template: DAST.gitlab-ci.yml
+
+variables:
+  DAST_API_SPECIFICATION: http://api-test.host.com/api-specification.yml
+  DAST_API_HOST_OVERRIDE: api-test.host.com
+```
+
+Note that `DAST_API_HOST_OVERRIDE` is only applied to specifications imported by URL.
+
+#### Authentication using headers
+
+Tokens in request headers are often used as a way to authenticate API requests. You can achieve this by using the `DAST_REQUEST_HEADERS` environment variable. Headers are applied to every request DAST makes.
+
+```yml
+include:
+  - template: DAST.gitlab-ci.yml
+
+variables:
+  DAST_API_SPECIFICATION: http://api-test.api.com/api-specification.yml
+  DAST_REQUEST_HEADERS: "Authorization: Bearer my.token"
+```
+
 ### Customizing the DAST settings
 
 The DAST settings can be changed through environment variables by using the
@@ -300,17 +379,21 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia
 
 | Environment variable        | Required   | Description                                                                    |
 |-----------------------------| ----------|--------------------------------------------------------------------------------|
-| `DAST_WEBSITE`  | yes | The URL of the website to scan. |
-| `DAST_AUTH_URL` | no | The authentication URL of the website to scan. |
+| `DAST_WEBSITE`  | no| The URL of the website to scan. `DAST_API_SPECIFICATION` must be specified if this is omitted. |
+| `DAST_API_SPECIFICATION`  | no | The API specification to import. `DAST_WEBSITE` must be specified if this is omitted. |
+| `DAST_AUTH_URL` | no | The authentication URL of the website to scan. Not supported for API scans. |
 | `DAST_USERNAME` | no | The username to authenticate to in the website. |
 | `DAST_PASSWORD` | no | The password to authenticate to in the website. |
 | `DAST_USERNAME_FIELD` | no | The name of username field at the sign-in HTML form. |
 | `DAST_PASSWORD_FIELD` | no | The name of password field at the sign-in HTML form. |
-| `DAST_AUTH_EXCLUDE_URLS` | no | The URLs to skip during the authenticated scan; comma-separated, no spaces in between. |
+| `DAST_AUTH_EXCLUDE_URLS` | no | The URLs to skip during the authenticated scan; comma-separated, no spaces in between. Not supported for API scans. |
 | `DAST_TARGET_AVAILABILITY_TIMEOUT` | no | Time limit in seconds to wait for target availability. Scan is attempted nevertheless if it runs out. Integer. Defaults to `60`. |
 | `DAST_FULL_SCAN_ENABLED` | no | Switches the tool to execute [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. |
-| `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | no | Requires [domain validation](#domain-validation) when running DAST full scans. Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. |
+| `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | no | Requires [domain validation](#domain-validation) when running DAST full scans. Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. Not supported for API scans. |
 | `DAST_AUTO_UPDATE_ADDONS` | no | Set to `false` to pin the versions of ZAProxy add-ons to those provided with the DAST image. Defaults to `true`. |
+| `DAST_API_HOST_OVERRIDE` | no | Used to override domains defined in API specification files. |
+| `DAST_EXCLUDE_RULES` | no | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from scans. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/master/docs/scanners.md). For example, `HTTP Parameter Override` has a rule ID of `10026`. |
+| `DAST_REQUEST_HEADERS` | no | Set to a comma-separated list of request header names and values. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` |
 
 ### DAST command-line options
 
diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md
index 359d548e236..cf8d63e1512 100644
--- a/doc/user/group/saml_sso/index.md
+++ b/doc/user/group/saml_sso/index.md
@@ -316,6 +316,53 @@ For example, to unlink the `MyOrg` account, the following **Disconnect** button
 | Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". |
 | Certificate fingerprint | Used to confirm that communications over SAML are secure by checking that the server is signing communications with the correct certificate. Also known as a certificate thumbprint. |
 
+## Configuring on a self-managed GitLab instance
+
+For self-managed GitLab instances we strongly recommend using the
+[instance-wide SAML OmniAuth Provider](../../../integration/saml.md) instead.
+
+Group SAML SSO helps if you need to allow access via multiple SAML identity providers, but as a multi-tenant solution is less suited to cases where you administer your own GitLab instance.
+
+To proceed with configuring Group SAML SSO instead, you'll need to enable the `group_saml` OmniAuth provider. This can be done from:
+
+- `gitlab.rb` for GitLab [Omnibus installations](#omnibus-installations).
+- `gitlab/config/gitlab.yml` for [source installations](#source-installations).
+
+### Limitations
+
+Group SAML on a self-managed instance is limited when compared to the recommended
+[instance-wide SAML](../../../integration/saml.md). The recommended solution allows you to take advantage of:
+
+- [LDAP compatibility](../../../administration/auth/ldap.md).
+- [LDAP group Sync](../../../administration/auth/how_to_configure_ldap_gitlab_ee/index.md#group-sync).
+- [Required groups](../../../integration/saml.md#required-groups-starter-only).
+- [Admin groups](../../../integration/saml.md#admin-groups-starter-only).
+- [Auditor groups](../../../integration/saml.md#auditor-groups-starter-only).
+
+### Omnibus installations
+
+1. Make sure GitLab is
+   [configured with HTTPS](../../../install/installation.md#using-https).
+1. Enable OmniAuth and the `group_saml` provider in `gitlab.rb`:
+
+   ```ruby
+   gitlab_rails['omniauth_enabled'] = true
+   gitlab_rails['omniauth_providers'] = [{ name: 'group_saml' }]
+   ```
+
+### Source installations
+
+1. Make sure GitLab is
+   [configured with HTTPS](../../../install/installation.md#using-https).
+1. Enable OmniAuth and the `group_saml` provider in `gitlab/config/gitlab.yml`:
+
+    ```yaml
+    omniauth:
+        enabled: true
+        providers:
+          - { name: 'group_saml' }
+    ```
+
 ## Troubleshooting
 
 This section contains possible solutions for problems you might encounter.