Add SCIM API docs

Adds the SCIM API documentation and the setup
for SAML GitLab groups.

doc/api/README.md

@@ -143,6 +143,11 @@ Endpoints are available for:
 - [GitLab CI YAML templates](templates/gitlab_ci_ymls.md).
 - [Open source license templates](templates/licenses.md).
 
+## SCIM
+
+[GitLab.com Silver and above](https://about.gitlab.com/pricing/) provides an [SCIM API](scim.md) that implements [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644) and provides
+the `/Users` endpoint. The base URL is: `/api/scim/v2/groups/:group_path/Users/`.
+
 ## Road to GraphQL
 
 Going forward, we will start on moving to

doc/api/scim.md

+# SCIM API
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9388) in [GitLab Silver](https://about.gitlab.com/pricing/) 11.10.
+
+The SCIM API implements the [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644).
+
+NOTE: **Note:**
+[Group SSO](../user/group/saml_sso/index.md) and the feature
+flag `:group_scim` must be enabled for the group. For more information, see [SCIM setup documentation](../user/group/saml_sso/scim_setup.md#requirements). 
+
+## Get a list of SAML users
+
+NOTE: **Note:**
+This endpoint is used as part of the SCIM syncing mechanism and it only returns
+a single user based on a unique ID which should match the `extern_uid` of the user.
+
+```text
+GET /api/scim/v2/groups/:group_path/Users
+```
+
+Parameters:
+
+| Attribute | Type    | Required | Description                                                                                                                             |
+|:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------|
+| `filter`   | string  | yes     | A [filter](#available-filters) expression. |
+| `group_path` | string | yes    | Full path to the group. |
+
+Example request:
+
+```sh
+curl 'https://example.gitlab.com/api/scim/v2/groups/test_group/Users?filter=id%20eq%20"0b1d561c-21ff-4092-beab-8154b17f82f2"' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"
+```
+
+Example response:
+
+```json
+{
+  "schemas": [
+    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
+  ],
+  "totalResults": 1,
+  "itemsPerPage": 20,
+  "startIndex": 1,
+  "Resources": [
+    {
+      "schemas": [
+        "urn:ietf:params:scim:schemas:core:2.0:User"
+      ],
+      "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
+      "active": true,
+      "name.formatted": "Test User",
+      "emails": [
+        {
+          "type": "work",
+          "value": "name@example.com",
+          "primary": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Get a single SAML user
+
+```text
+GET /api/scim/v2/groups/:group_path/Users/:id
+```
+
+Parameters:
+
+| Attribute | Type    | Required | Description                                                                                                                             |
+|:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------|
+| `id`   | string  | yes     | External UID of the user. |
+| `group_path` | string | yes    | Full path to the group. |
+
+Example request:
+
+```sh
+curl 'https://example.gitlab.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"
+```
+
+Example response:
+
+```json
+{
+  "schemas": [
+    "urn:ietf:params:scim:schemas:core:2.0:User"
+  ],
+  "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
+  "active": true,
+  "name.formatted": "Test User",
+  "emails": [
+    {
+      "type": "work",
+      "value": "name@example.com",
+      "primary": true
+    }
+  ]
+}
+```
+
+## Update a single SAML user
+
+Fields that can be updated are:
+
+| SCIM/IdP field | GitLab field |
+|:----------|:--------|
+| id  | extern_uid |
+| name.formatted  | name |
+| emails\[type eq "work"\].value  | email |
+| active | Identity removal if `active = false` |
+
+```text
+PATCH /api/scim/v2/groups/:group_path/Users/:id
+```
+
+Parameters:
+
+| Attribute | Type    | Required | Description                                                                                                                             |
+|:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------|
+| `id`   | string  | yes     | External UID of the user. |
+| `group_path` | string | yes    | Full path to the group. |
+| `Operations`   | JSON string  | yes     | An [operations](#available-operations) expression. |
+
+Example request:
+
+```sh
+curl --verbose --request PATCH 'https://example.gitlab.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2' --data '{ "Operations": [{"op":"Add","path":"name.formatted","value":"New Name"}] }' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"
+```
+
+Returns an empty response with a `204` status code if successful.
+
+## Remove a single SAML user
+
+Removes the user's SSO identity and group membership.
+
+```text
+DELETE /api/scim/v2/groups/:group_path/Users/:id
+```
+
+Parameters:
+
+| Attribute | Type    | Required | Description                                                                                                                             |
+|:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------|
+| `id`   | string  | yes     | External UID of the user. |
+| `group_path` | string | yes    | Full path to the group. |
+
+Example request:
+
+```sh
+curl --verbose --request DELETE 'https://example.gitlab.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"
+```
+
+Returns an empty response with a `204` status code if successful.
+
+## Available filters
+
+They match an expression as specified in [the RFC7644 filtering section](https://tools.ietf.org/html/rfc7644#section-3.4.2.2).
+
+| Filter | Description |
+| ----- | ----------- |
+| `eq` | The attribute matches exactly the specified value. |
+
+Example:
+
+```
+id eq a-b-c-d
+```
+
+## Available operations
+
+They perform an operation as specified in [the RFC7644 update section](https://tools.ietf.org/html/rfc7644#section-3.5.2).
+
+| Operator | Description |
+| ----- | ----------- |
+| `Replace` | The attribute's value is updated. |
+| `Add` | The attribute has a new value. |
+
+Example:
+
+```json
+{ "op": "Add", "path": "name.formatted", "value": "New Name" }
+```

doc/topics/authentication/index.md

@@ -31,6 +31,7 @@ This page gathers all the resources for the topic **Authentication** within GitL
   - [CAS OmniAuth Provider](../../integration/cas.md)
   - [SAML OmniAuth Provider](../../integration/saml.md)
   - [SAML for GitLab.com Groups](../../user/group/saml_sso/index.md)
+  - [SCIM user provisioning for GitLab.com Groups](../../user/group/saml_sso/scim_setup.md)
   - [Okta SSO provider](../../administration/auth/okta.md)
   - [Kerberos integration (GitLab EE)](https://docs.gitlab.com/ee/integration/kerberos.html)
 

doc/user/group/saml_sso/index.md

@@ -7,6 +7,8 @@ This topic is for SAML on GitLab.com Silver tier and above. For SAML on self-man
 
 Currently SAML on GitLab.com can be used to automatically add users to a group, and does not yet sign users into GitLab.com. Users should already have an account on the GitLab instance, or can create one when logging in for the first time.
 
+User synchronization for GitLab.com is partially supported using [SCIM](scim_setup.md).
+
 NOTE: **Note:**
 SAML SSO for groups is used only as a convenient way to add users and does not sync users between providers. Group owners will still need to manage user accounts, such as removing users when necessary.
 

doc/user/group/saml_sso/scim_setup.md

+# SCIM provisioning using SAML SSO for Groups
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9388) in [GitLab Silver](https://about.gitlab.com/pricing/) 11.10.
+
+GitLab's [SCIM API](../../../api/scim.md) implements part of [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644).
+
+Currently, the following actions are available:
+
+- UPDATE
+- DELETE (deprovisioning)
+
+The following identity providers are supported:
+
+- Azure
+
+## Requirements
+
+- [Group SSO](index.md) needs to be configured. 
+- The `scim_group` feature flag must be enabled:
+
+    Run the following commands in a Rails console:
+    
+    ```sh
+    # Omnibus GitLab
+    gitlab-rails console
+    
+    # Installation from source
+    cd /home/git/gitlab
+    sudo -u git -H bin/rails console RAILS_ENV=production
+    ```
+    
+    To enable SCIM for a group named `group_name`:
+    
+    ```ruby
+    group = Group.find_by_full_path('group_name')
+    Feature.enable(:group_scim, group)
+    ```
+    
+### GitLab configuration
+
+Once [Single sign-on](index.md) has been configured, we can:
+
+1. Navigate to the group and click **Settings > 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.
+
+![SCIM token configuration](img/scim_token.png)    
+
+## SCIM IdP configuration
+
+### Configuration on Azure
+
+In the [Single sign-on](index.md) configuration for the group, make sure
+that the **Name identifier value** (NameID) points to a unique identifier, such
+as the `user.objectid`. This will match the `extern_uid`  used on GitLab.
+
+The GitLab app in Azure needs to be configured following 
+[Azure's SCIM setup](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/use-scim-to-provision-users-and-groups#getting-started).
+
+Note the following:
+
+- The `Tenant URL` and `secret token` are the ones retrieved in the
+[previous step](#gitlab-configuration).
+- Should there be any problems with the availability of GitLab or similar
+errors, the notification email set will get those.
+- For mappings, we will only leave `Synchronize Azure Active Directory Users to AppName` enabled.
+
+You can then test the connection clicking on `Test Connection`.
+
+### Synchronize Azure Active Directory users
+
+1. Click on `Synchronize Azure Active Directory Users to AppName`, to configure
+the attribute mapping.
+1. Select the unique identifier (in the example `objectId`) as the `id` and enable
+the`Update` and `Create` actions.
+
+    Example configuration:
+    
+    ![Azure's attribute mapping configuration](img/scim_attribute_mapping.png)
+
+1. Click on **Show advanced options > Edit attribute list for AppName**.
+1. Leave the `id` as the primary and only required field.
+
+    NOTE: **Note:**
+    `username` should neither be primary nor required as we don't support
+    that field on GitLab SCIM yet.
+    
+    ![Azure's attribute advanced configuration](img/scim_advanced.png)
+
+1. Save all the screens and, in the **Provisioning** step, set
+the `Provisioning Status` to `ON`.
+
+    NOTE: **Note:**
+    You can control what is actually synced by selecting the `Scope`. For example,
+    `Sync only assigned users and groups` will only sync the users assigned to
+    the application (`Users and groups`), otherwise it will sync the whole Active Directory.
+
+Once enabled, the synchronization details and any errors will appear on the
+bottom of the **Provisioning** screen, together with a link to the audit logs.