Add latest changes from gitlab-org/gitlab@13-0-stable-ee

2 files changed, 68 insertions, 24 deletions

diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md
index f49dd225146..a3d9a14df10 100644
--- a/doc/user/group/saml_sso/index.md
+++ b/doc/user/group/saml_sso/index.md
@@ -59,7 +59,7 @@ We recommend setting the NameID format to `Persistent` unless using a field (suc
 
 With this option enabled, users must use your group's GitLab single sign on URL to be added to the group or be added via SCIM. Users cannot be added manually, and may only access project/group resources via the UI by signing in through the SSO URL.
 
-However, users will not be prompted to log via SSO on each visit. GitLab will check whether a user has authenticated through the SSO link, and will only prompt the user to login via SSO if it has been longer than 7 days.
+However, users will not be prompted to log via SSO on each visit. GitLab will check whether a user has authenticated through the SSO link, and will only prompt the user to login via SSO if the session has expired.
 
 We intend to add a similar SSO requirement for [Git and API activity](https://gitlab.com/gitlab-org/gitlab/issues/9152) in the future.
 
@@ -189,6 +189,9 @@ Once you've set up your identity provider to work with GitLab, you'll need to co
 
 ![Group SAML Settings for GitLab.com](img/group_saml_settings.png)
 
+NOTE: **Note:**
+Please note that the certificate [fingerprint algorithm](#additional-setup-options) must be in SHA1. When configuring the identity provider, use a secure [signature algorithm](#additional-setup-options).
+
 ## User access and management
 
 Once Group SSO is configured and enabled, users can access the GitLab.com group through the identity provider's dashboard. If [SCIM](scim_setup.md) is configured, please see the [user access and linking setup section on the SCIM page](scim_setup.md#user-access-and-linking-setup).
@@ -254,6 +257,9 @@ Set other user attributes and claims according to the [assertions table](#assert
 
 ### Okta setup notes
 
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+For a demo of the Okta SAML setup including SCIM, see [Demo: Okta Group SAML & SCIM setup](https://youtu.be/0ES9HsZq0AQ).
+
 | GitLab Setting | Okta Field |
 |--------------|----------------|
 | Identifier | Audience URI |
@@ -297,7 +303,7 @@ GitLab [isn't limited to the SAML providers listed above](#my-identity-provider-
 | SAML Request Binding | HTTP Redirect | GitLab (the service provider) redirects users to your Identity Provider with a base64 encoded `SAMLRequest` HTTP parameter. |
 | SAML Response Binding | HTTP POST | Your Identity Provider responds to users with an HTTP form including the `SAMLResponse`, which a user's browser submits back to GitLab. |
 | Sign SAML Response | Yes | We require this to prevent tampering. |
-| X509 Certificate in response | Yes | This is used to sign the response and checked against the provided fingerprint. |
+| X.509 Certificate in response | Yes | This is used to sign the response and checked against the provided fingerprint. |
 | Fingerprint Algorithm | SHA-1  | We need a SHA-1 hash of the certificate used to sign the SAML Response. |
 | Signature Algorithm | SHA-1/SHA-256/SHA-384/SHA-512 | Also known as the Digest Method, this can be specified in the SAML response. It determines how a response is signed. |
 | Encrypt SAML Assertion | No | TLS is used between your Identity Provider, the user's browser, and GitLab. |
diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md
index e333fd19c1b..f66c8a788b6 100644
--- a/doc/user/group/saml_sso/scim_setup.md
+++ b/doc/user/group/saml_sso/scim_setup.md
@@ -12,25 +12,28 @@ that group is synchronized between GitLab and the identity provider.
 
 GitLab's [SCIM API](../../../api/scim.md) implements part of [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644).
 
+## Features
+
 Currently, the following actions are available:
 
-- CREATE
-- UPDATE
-- DELETE (deprovisioning)
+- Create users
+- Update users (Azure only)
+- Deactivate users
 
 The following identity providers are supported:
 
 - Azure
+- Okta
 
 ## Requirements
 
-- [Group SSO](index.md) must be configured.
+- [Group Single Sign-On](index.md) must be configured.
 
 ## GitLab configuration
 
-Once [Single sign-on](index.md) has been configured, we can:
+Once [Group Single Sign-On](index.md) has been configured, we can:
 
-1. Navigate to the group and click **Settings > SAML SSO**.
+1. Navigate to the group and click **Administration > SAML SSO**.
 1. Click on the **Generate a SCIM token** button.
 1. Save the token and URL so they can be used in the next step.
 
@@ -38,9 +41,12 @@ Once [Single sign-on](index.md) has been configured, we can:
 
 ## Identity Provider configuration
 
-### Azure
+- [Azure](#azure-configuration-steps)
+- [Okta](#okta-configuration-steps)
+
+### Azure configuration steps
 
-The SAML application that was created during [Single sign-on](index.md) setup now needs to be set up for SCIM.
+The SAML application that was created during [Single sign-on](index.md) setup for [Azure](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/configure-single-sign-on-non-gallery-applications) now needs to be set up for SCIM.
 
 1. Check the configuration for your GitLab SAML app and ensure that **Name identifier value** (NameID) points to `user.objectid` or another unique identifier. This will match the `extern_uid` used on GitLab.
 
@@ -109,6 +115,43 @@ bottom of the **Provisioning** screen, together with a link to the audit logs.
 CAUTION: **Warning:**
 Once synchronized, changing the field mapped to `id` and `externalId` will likely cause provisioning errors, duplicate users, and prevent existing users from accessing the GitLab group.
 
+### Okta configuration steps
+
+The SAML application that was created during [Single sign-on](index.md#okta-setup-notes) setup for [Okta](https://developer.okta.com/docs/guides/saml-application-setup/overview/) now needs to be set up for SCIM.
+Before proceeding, be sure to complete the [GitLab configuration](#gitlab-configuration) process.
+
+1. Sign in to Okta.
+1. If you see an **Admin** button in the top right, click the button. This will
+   ensure you are in the Admin area.
+
+   TIP: **Tip:** If you're using the Developer Console, click **Developer Console** in the top
+   bar and select **Classic UI**. Otherwise, you may not see the buttons described
+   in the following steps:
+
+1. In the **Application** tab, click **Add Application**.
+1. Search for **GitLab**, find and click on the 'GitLab' application.
+1. On the GitLab application overview page, click **Add**.
+1. Under **Application Visibility** select both check boxes. Currently the GitLab application does not support SAML authentication so the icon should not be shown to users.
+1. Click **Done** to finish adding the application.
+1. In the **Provisioning** tab, click **Configure API integration**.
+1. Select **Enable API integration**.
+    - For **Base URL** enter the URL obtained from the GitLab SCIM configuration page
+    - For **API Token** enter the SCIM token obtained from the GitLab SCIM configuration page
+1. Click 'Test API Credentials' to verify configuration.
+1. Click **Save** to apply the settings.
+1. After saving the API integration details, new settings tabs will appear on the left. Choose **To App**.
+1. Click **Edit**.
+1. Check the box to **Enable** for both **Create Users** and **Deactivate Users**.
+1. Click **Save**.
+1. Assign users in the **Assignments** tab. Assigned users will be created and
+   managed in your GitLab group.
+
+#### Okta Known Issues
+
+The Okta GitLab application currently only supports SCIM. Continue
+using the separate Okta [SAML SSO](index.md) configuration along with the new SCIM
+application described above.
+
 ## User access and linking setup
 
 As long as [Group SAML](index.md) has been configured, prior to turning on sync, existing GitLab.com users can link to their accounts in one of the following ways, before synchronization is active:
@@ -135,7 +178,9 @@ Upon the next sync, the user will be deprovisioned, which means that the user wi
 
 This section contains possible solutions for problems you might encounter.
 
-### How do I verify my SCIM configuration is correct?
+### Azure
+
+#### How do I verify my SCIM configuration is correct?
 
 Review the following:
 
@@ -148,11 +193,11 @@ Review the following SCIM parameters for sensible values:
 - `displayName`
 - `emails[type eq "work"].value`
 
-### Testing Azure connection: invalid credentials
+#### Testing Azure connection: invalid credentials
 
 When testing the connection, you may encounter an error: **You appear to have entered invalid credentials. Please confirm you are using the correct information for an administrative account**. If `Tenant URL` and `secret token` are correct, check whether your group path contains characters that may be considered invalid JSON primitives (such as `.`). Removing such characters from the group path typically resolves the error.
 
-### Azure: (Field) can't be blank sync error
+#### Azure: (Field) can't be blank sync error
 
 When checking the Audit Logs for the Provisioning, you can sometimes see the
 error `Namespace can't be blank, Name can't be blank, and User can't be blank.`
@@ -165,14 +210,7 @@ As a workaround, try an alternate mapping:
 1. Delete the `name.formatted` target attribute entry.
 1. Change the `displayName` source attribute to have `name.formatted` target attribute.
 
-### Message: "SAML authentication failed: Email has already been taken"
-
-This message may be caused by the following:
-
-- Existing users have not yet signed into the new app.
-- The identity provider attempts to create a new user account in GitLab with an email address that already exists in GitLab.com.
-
-### How do I diagnose why a user is unable to sign in
+#### How do I diagnose why a user is unable to sign in
 
 The **Identity** (`extern_uid`) value stored by GitLab is updated by SCIM whenever `id` or `externalId` changes. Users won't be able to sign in unless the GitLab Identity (`extern_uid`) value matches the `NameId` sent by SAML.
 
@@ -180,7 +218,7 @@ This value is also used by SCIM to match users on the `id`, and is updated by SC
 
 It is important that this SCIM `id` and SCIM `externalId` are configured to the same value as the SAML `NameId`. SAML responses can be traced using [debugging tools](./index.md#saml-debugging-tools), and any errors can be checked against our [SAML troubleshooting docs](./index.md#troubleshooting).
 
-### How do I verify user's SAML NameId matches the SCIM externalId
+#### How do I verify user's SAML NameId matches the SCIM externalId
 
 Group owners can see the list of users and the `externalId` stored for each user in the group SAML SSO Settings page.
 
@@ -194,7 +232,7 @@ curl 'https://example.gitlab.com/api/scim/v2/groups/GROUP_NAME/Users?startIndex=
 
 To see how this compares to the value returned as the SAML NameId, you can have the user use a [SAML Tracer](index.md#saml-debugging-tools).
 
-### Update or fix mismatched SCIM externalId and SAML NameId
+#### Update or fix mismatched SCIM externalId and SAML NameId
 
 Whether the value was changed or you need to map to a different field, ensure `id`, `externalId`, and `NameId` all map to the same field.
 
@@ -220,7 +258,7 @@ curl --verbose --request PATCH 'https://gitlab.com/api/scim/v2/groups/YOUR_GROUP
 
 It is important not to update these to incorrect values, since this will cause users to be unable to sign in. It is also important not to assign a value to the wrong user, as this would cause users to get signed into the wrong account.
 
-### I need to change my SCIM app
+#### I need to change my SCIM app
 
 Individual users can follow the instructions in the ["SAML authentication failed: User has already been taken"](./index.md#i-need-to-change-my-saml-app) section.