Коммит ea039154 создал по автору James Lopez's avatar James Lopez Зафиксировано автором Evan Read
Просмотр файлов

Add SCIM API docs 

Adds the SCIM API documentation and the setup
for SAML GitLab groups.
владелец 29e936e7
Скрыть пробелы
Построчно Рядом
doc/api/README.md
Просмотр файла @ ea039154
......@@ -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 0 → 100644
Просмотр файла @ ea039154
# 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
Просмотр файла @ ea039154
......@@ -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
Просмотр файла @ ea039154
......@@ -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 0 → 100644
Просмотр файла @ ea039154
# 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.
Поддерживает Markdown
0% или .
You are about to add 0 people to the discussion. Proceed with caution.
Сначала завершите редактирование этого сообщения!
Пожалуйста, зарегистрируйтесь или чтобы прокомментировать