SCIM API

GitLab Silver11.10 で導入されました。

SCIM API はRFC7644 プロトコルを実装しています。

注意：このAPIはSCIMプロバイダーと接続するための内部システム用です。 直接使用することもできますが、予告なく変更されることがあります。
注意:グループ SSOはグループに対して有効にする必要があります。 詳細については、SCIM セットアップドキュメントを参照してください。

SAML ユーザのリストの取得

注意:このエンドポイントは SCIM 同期メカニズムの一部として使用され、ユーザのextern_uid と一致する一意の ID に基づいて単一のユーザのみを返します。
GET /api/scim/v2/groups/:group_path/Users

パラメーター

属性 タイプ 必須 説明
filter 列 いいえ フィルター式。
group_path 列 はい グループへのフルパス。
startIndex 整数 いいえ どこから結果を返すかを示す 1 ベースのインデックス。 1 未満の値は 1 と解釈されます。
count 整数 いいえ 希望するクエリ結果の最大数。
注意:ページ分割は、他の場所で使われている GitLab のページ分割ではなくSCIM の仕様に従います。 リクエスト間でレコードが変更されると、別のページに移動したレコードがなかったり前のリクエストのレコードを繰り返したりする可能性があります。

リクエスト例 

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"

回答例 

{
  "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",
      "userName": "username",
      "meta": { "resourceType":"User" },
      "emails": [
        {
          "type": "work",
          "value": "name@example.com",
          "primary": true
        }
      ]
    }
  ]
}

単一の SAML ユーザの取得 

GET /api/scim/v2/groups/:group_path/Users/:id

パラメーター

属性 タイプ 必須 説明
id 列 はい ユーザーの外部UID。
group_path 列 はい グループへのフルパス。

リクエスト例 

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"

回答例 

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
  "active": true,
  "name.formatted": "Test User",
  "userName": "username",
  "meta": { "resourceType":"User" },
  "emails": [
    {
      "type": "work",
      "value": "name@example.com",
      "primary": true
    }
  ]
}

SAML ユーザの作成 

POST /api/scim/v2/groups/:group_path/Users/

パラメーター

属性 タイプ 必須 説明
externalId 列 はい ユーザーの外部UID。
userName 列 はい ユーザーのユーザー名。
emails JSON文字列 はい 仕事のメール
name JSON文字列 はい ユーザー名
meta 列 いいえ リソースタイプ (User).

リクエスト例 

curl --verbose --request POST "https://example.gitlab.com/api/scim/v2/groups/test_group/Users" --data '{"externalId":"test_uid","active":null,"userName":"username","emails":[{"primary":true,"type":"work","value":"name@example.com"}],"name":{"formatted":"Test User","familyName":"User","givenName":"Test"},"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"meta":{"resourceType":"User"}}' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

回答例 

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
  "active": true,
  "name.formatted": "Test User",
  "userName": "username",
  "meta": { "resourceType":"User" },
  "emails": [
    {
      "type": "work",
      "value": "name@example.com",
      "primary": true
    }
  ]
}

成功した場合は201 のステータスコードを返します。

単一の SAML ユーザーの更新

更新可能なフィールドは以下の通りです：

SCIM/IDPフィールド GitLabフィールド
id/externalId extern_uid
name.formatted name
emails\[type eq "work"\].value email
active active = の場合、アイデンティティを削除。false
userName username 
PATCH /api/scim/v2/groups/:group_path/Users/:id

パラメーター

属性 タイプ 必須 説明
id 列 はい ユーザーの外部UID。
group_path 列 はい グループへのフルパス。
Operations JSON文字列 はい オペレーション表現。

リクエスト例 

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"

成功した場合は、204 ステータスコードとともに空のレスポンスを返します。

単一の SAML ユーザーの削除

ユーザーのSSO IDとグループメンバーシップを削除します。 

DELETE /api/scim/v2/groups/:group_path/Users/:id

パラメーター

属性 タイプ 必須 説明
id 列 はい ユーザーの外部UID。
group_path 列 はい グループへのフルパス。

リクエスト例 

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"

成功した場合は、204 ステータスコードとともに空のレスポンスを返します。

利用可能なフィルター

これらは、RFC7644のフィルタリングセクションで指定されている式にマッチします。

Filter 説明
eq 属性は指定された値と正確に一致します。

使用例： 

id eq a-b-c-d

可能なオペレーション

RFC7644の更新セクションで指定されているオペレーションを実行します。

オペレーション 説明
Replace 属性の値が更新されます。
Add 属性は新しい値を持ちます。

使用例： 

{ "op": "Add", "path": "name.formatted", "value": "New Name" }