Add latest changes from gitlab-org/gitlab@master

8 files changed, 142 insertions, 11 deletions

diff --git a/doc/integration/saml.md b/doc/integration/saml.md
index d0088eab957..b72be55aca3 100644
--- a/doc/integration/saml.md
+++ b/doc/integration/saml.md
@@ -429,6 +429,120 @@ args: {
 }
 ```
 
+## Response signature validation (required)
+
+We require Identity Providers to sign SAML responses to ensure that the assertions are
+not tampered with.
+
+This prevents user impersonation and prevents privilege escalation when specific group
+membership is required. Typically this:
+
+- Is configured using `idp_cert_fingerprint`.
+- Includes the full certificate in the response, although if your Identity Provider
+  doesn't support this, you can directly configure GitLab using the `idp_cert` option.
+
+Example configuration with `idp_cert_fingerprint`:
+
+```yaml
+args: {
+  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
+  idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
+  idp_sso_target_url: 'https://login.example.com/idp',
+  issuer: 'https://gitlab.example.com',
+  name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
+}
+```
+
+Example configuration with `idp_cert`:
+
+```yaml
+args: {
+  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
+  idp_cert: '-----BEGIN CERTIFICATE-----
+    <redacted>
+    -----END CERTIFICATE-----',
+  idp_sso_target_url: 'https://login.example.com/idp',
+  issuer: 'https://gitlab.example.com',
+  name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
+}
+```
+
+If the response signature validation is configured incorrectly, you can see error messages
+such as:
+
+- A key validation error.
+- Digest mismatch.
+- Fingerprint mismatch.
+
+Refer to the [troubleshooting section](#troubleshooting) for more information on
+debugging these errors.
+
+## Assertion Encryption (optional)
+
+GitLab requires the use of TLS encryption with SAML, but in some cases there can be a
+need for additional encryption of the assertions.
+
+This may be the case, for example, if you terminate TLS encryption early at a load
+balancer and include sensitive details in assertions that you do not want appearing
+in logs. Most organizations should not need additional encryption at this layer.
+
+The SAML integration supports EncryptedAssertion. You need to define the private key and the public certificate of your GitLab instance in the SAML settings:
+
+```yaml
+args: {
+  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
+  idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
+  idp_sso_target_url: 'https://login.example.com/idp',
+  issuer: 'https://gitlab.example.com',
+  name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
+  certificate: '-----BEGIN CERTIFICATE-----
+    <redacted>
+    -----END CERTIFICATE-----',
+  private_key: '-----BEGIN PRIVATE KEY-----
+    <redacted>
+    -----END PRIVATE KEY-----'
+}
+```
+
+Your Identity Provider will encrypt the assertion with the public certificate of GitLab. GitLab will decrypt the EncryptedAssertion with its private key.
+
+NOTE: **Note:**
+This integration uses the `certificate` and `private_key` settings for both assertion encryption and request signing.
+
+## Request signing (optional)
+
+Another optional configuration is to sign SAML authentication requests. GitLab SAML Requests uses the SAML redirect binding so this is not necessary, unlike the SAML POST binding where signing is required to prevent intermediaries tampering with the requests.
+
+In order to sign, you need to create a private key and public certificate pair for your GitLab instance to use for SAML. The settings related to signing can be set in the `security` section of the configuration.
+
+For example:
+
+```yaml
+args: {
+  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
+  idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
+  idp_sso_target_url: 'https://login.example.com/idp',
+  issuer: 'https://gitlab.example.com',
+  name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
+  certificate: '-----BEGIN CERTIFICATE-----
+    <redacted>
+    -----END CERTIFICATE-----',
+  private_key: '-----BEGIN PRIVATE KEY-----
+    <redacted>
+    -----END PRIVATE KEY-----',
+  security: {
+    authn_requests_signed: true, # enable signature on AuthNRequest
+    want_assertions_signed: true, # enable the requirement of signed assertion
+    embed_sign: true, # embedded signature or HTTP GET parameter signature
+    metadata_signed: false, # enable signature on Metadata
+    signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
+    digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256',
+  }
+}
+```
+
+GitLab will sign the request with the provided private key. GitLab will include the configured public x500 certificate in the metadata for your Identity Provider to validate the signature of the received request with. For more information on this option, see the [ruby-saml gem documentation](https://github.com/onelogin/ruby-saml/tree/v1.7.0). The `ruby-saml` gem is used by the [omniauth-saml gem](https://github.com/omniauth/omniauth-saml) to implement the client side of the SAML authentication.
+
 ## Troubleshooting
 
 ### 500 error after login
diff --git a/doc/security/asset_proxy.md b/doc/security/asset_proxy.md
index b480905339b..6e615028e8b 100644
--- a/doc/security/asset_proxy.md
+++ b/doc/security/asset_proxy.md
@@ -11,12 +11,12 @@ to log the IP address of the user.
 One way to mitigate this is by proxying any external images to a server you
 control.
 
-GitLab can be configured to use an asset proxy server when requesting external images/videos in
+GitLab can be configured to use an asset proxy server when requesting external images/videos/audio in
 issues, comments, etc. This helps ensure that malicious images do not expose the user's IP address
 when they are fetched.
 
 We currently recommend using [cactus/go-camo](https://github.com/cactus/go-camo#how-it-works)
-as it supports proxying video and is more configurable.
+as it supports proxying video, audio, and is more configurable.
 
 ## Installing Camo server
 
@@ -52,7 +52,7 @@ To install a Camo server as an asset proxy:
 
 ## Using the Camo server
 
-Once the Camo server is running and you've enabled the GitLab settings, any image or video that
+Once the Camo server is running and you've enabled the GitLab settings, any image, video, or audio that
 references an external source will get proxied to the Camo server.
 
 For example, the following is a link to an image in Markdown:
diff --git a/doc/user/img/markdown_audio.mp3 b/doc/user/img/markdown_audio.mp3
new file mode 100644
index 00000000000..8946c3b3b10
--- /dev/null
+++ b/doc/user/img/markdown_audio.mp3
diff --git a/doc/user/markdown.md b/doc/user/markdown.md
index 475bd7d17a0..65ff176df27 100644
--- a/doc/user/markdown.md
+++ b/doc/user/markdown.md
@@ -108,7 +108,7 @@ changing how standard markdown is used:
 | [code blocks](#code-spans-and-blocks) | [colored code and syntax highlighting](#colored-code-and-syntax-highlighting) |
 | [emphasis](#emphasis)                 | [multiple underscores in words](#multiple-underscores-in-words-and-mid-word-emphasis)
 | [headers](#headers)                   | [linkable Header IDs](#header-ids-and-links) |
-| [images](#images)                     | [embedded videos](#videos) |
+| [images](#images)                     | [embedded videos](#videos) and [audio](#audio) |
 | [linebreaks](#line-breaks)            | [more linebreak control](#newlines) |
 | [links](#links)                       | [automatically linking URLs](#url-auto-linking) |
 
@@ -899,6 +899,23 @@ Here's a sample video:
 
 ![Sample Video](img/markdown_video.mp4)
 
+#### Audio
+
+> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#audio).
+
+Similar to videos, link tags for files with an audio extension are automatically converted to
+an audio player. The valid audio extensions are `.mp3`, `.ogg`, and `.wav`:
+
+```md
+Here's a sample audio clip:
+
+![Sample Audio](img/markdown_audio.mp3)
+```
+
+Here's a sample audio clip:
+
+![Sample Audio](img/markdown_audio.mp3)
+
 ### Inline HTML
 
 > To see the markdown rendered within HTML in the second example, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#inline-html).
diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md
index 1d5a4a3d4c7..9fa92f19e4f 100644
--- a/doc/user/project/integrations/jira_cloud_configuration.md
+++ b/doc/user/project/integrations/jira_cloud_configuration.md
@@ -15,6 +15,6 @@ below to create one:
 
 ![Jira API token](img/jira_api_token.png)
 
-1. Click **Copy to clipboard**, or click **View** and write down the new API token. It is required when [configuring GitLab](jira.md#configuring-gitlab).
+1. Click **Copy**, or click **View** and write down the new API token. It is required when [configuring GitLab](jira.md#configuring-gitlab).
 
 The Jira configuration is complete. You need the newly created token, and the associated email address, when [configuring GitLab](jira.md#configuring-gitlab) in the next section.
diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md
index 5313975908b..01f4eb5b912 100644
--- a/doc/user/project/issues/issue_data_and_actions.md
+++ b/doc/user/project/issues/issue_data_and_actions.md
@@ -141,9 +141,9 @@ for the issue. This will automatically enable if you participate in the issue in
 
 #### 14. Reference
 
-- A quick "copy to clipboard" button for that issue's reference, which looks like `foo/bar#xxx`,
-  where `foo` is the `username` or `groupname`, `bar` is the `project-name`, and
-  `xxx` is the issue number.
+- A quick "copy" button for that issue's reference, which looks like
+  `foo/bar#xxx`, where `foo` is the `username` or `groupname`, `bar` is the
+  `project-name`, and `xxx` is the issue number.
 
 #### 15. Edit
 
diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md
index 3a389eb1e3a..083a117600b 100644
--- a/doc/user/project/merge_requests/allow_collaboration.md
+++ b/doc/user/project/merge_requests/allow_collaboration.md
@@ -52,7 +52,7 @@ Here's how the process would look like:
 
    ![Check out branch button](img/checkout_button.png)
 
-1. Use the copy to clipboard button to copy the first command and paste them
+1. Use the copy button to copy the first command and paste them
    in your terminal:
 
    ```sh
diff --git a/doc/user/snippets.md b/doc/user/snippets.md
index e55a407295e..77997c53210 100644
--- a/doc/user/snippets.md
+++ b/doc/user/snippets.md
@@ -70,8 +70,8 @@ To embed a snippet, first make sure that:
 - In **Project > Settings > Permissions**, the snippets permissions are
   set to **Everyone with access**
 
-Once the above conditions are met, the "Embed" section will appear in your snippet
-where you can simply click on the "Copy to clipboard" button. This copies a one-line
+Once the above conditions are met, the "Embed" section will appear in your
+snippet where you can simply click on the "Copy" button. This copies a one-line
 script that you can add to any website or blog post.
 
 Here's how an example code looks like: