내부 API는 다양한 GitLab 컴포넌트에서 사용되며, 외부 소비자는 사용할 수 없습니다. 이 문서는 GitLab 코드베이스를 작업하는 사람들을 위한 것입니다.

이 문서에는 아직 GitLab Pages에서 사용하는 내부 API가 포함되어 있지 않습니다.

GitLab Subscriptions 내부 API에 대한 정보는 전용 페이지를 참조하세요.

Orbit 내부 API에 대한 정보는 전용 페이지를 참조하세요.

새 엔드포인트 추가#

API 엔드포인트는 기본적으로 적절한 인증 및 인가와 함께 외부에서 접근 가능해야 합니다. 새로운 내부 엔드포인트를 추가하기 전에, 해당 API가 더 넓은 GitLab 커뮤니티에 도움이 될 수 있으며 외부에서 접근 가능하게 만들 수 있는지 고려하세요.

내부 API 엔드포인트를 선호하는 한 가지 이유는, 그러한 엔드포인트를 사용하는 데 외부 행위자가 가질 수 없는 내부 데이터가 필요한 경우입니다. 예를 들어, 내부 Pages API에서는 요청을 내부 요청으로 식별하는 시크릿 토큰을 사용하거나, 더 넓은 커뮤니티에서는 사용할 수 없는 공개 키로 요청에 서명할 수 있습니다.

내부 API로 분리하는 또 다른 이유는, 그러한 API 엔드포인트에 대한 요청이 엣지(공개) 로드 밸런서를 통과해서는 안 되는 경우입니다. 이를 통해 내부 로드 밸런서를 통해서만 해당 엔드포인트에 내부 요청이 이루어질 수 있다는 것을 알기 때문에, 엔드포인트에 대한 접근 방식에 대해 서로 다른 속도 제한 규칙 및 정책을 구성할 수 있습니다.

인증#

이 메서드들은 모두 공유 시크릿을 사용하여 인증됩니다. 이 시크릿은 config/gitlab.yml에 구성된 경로의 파일에 저장되며, 기본적으로 Rails 앱의 루트에 .gitlab_shell_secret이라는 이름으로 있습니다.

해당 토큰을 사용하여 인증하려면, 클라이언트는:

• 해당 파일의 내용을 읽습니다.

• 파일 내용을 사용하여 JSON Web Token(JWT)을 생성합니다.

• Gitlab-Shell-Api-Request 헤더에 JWT를 전달합니다.

Git 인증#

리포지터리에 대한 접근을 확인하기 위해 Gitaly와 GitLab Shell에서 호출됩니다.

• GitLab Shell에서 호출되는 경우: 변경 사항이 전달되지 않으며, 내부 API는 요청을 Gitaly에 전달하는 데 필요한 정보를 응답합니다.

• pre-receive 훅의 Gitaly에서 호출되는 경우: 변경 사항이 전달되고 유효성 검사를 통해 푸시가 허용되는지 결정합니다.

호출은 각각 50초로 제한됩니다.

이 엔드포인트는 다루는 범위 때문에 자체 페이지에서 더 자세히 다룹니다.

POST /internal/allowed

요청 예시:

curl --request POST --header "Gitlab-Shell-Api-Request: " \
     --data "key_id=11&project=gnuwget/wget2&action=git-upload-pack&protocol=ssh" \
     "http://localhost:3001/api/v4/internal/allowed"

응답 예시:

{
  "status": true,
  "gl_repository": "project-3",
  "gl_project_path": "gnuwget/wget2",
  "gl_id": "user-1",
  "gl_username": "root",
  "git_config_options": [],
  "gitaly": {
    "repository": {
      "storage_name": "default",
      "relative_path": "@hashed/4e/07/4e07408562bedb8b60ce05c1decfe3ad16b72230967de01f640b7e4729b49fce.git",
      "git_object_directory": "",
      "git_alternate_object_directories": [],
      "gl_repository": "project-3",
      "gl_project_path": "gnuwget/wget2"
    },
    "address": "unix:/Users/bvl/repos/gitlab/gitaly.socket",
    "token": null
  },
  "gl_console_messages": []
}

알려진 소비자#

• Gitaly

• GitLab Shell

LFS 인증#

SSH를 통해 리포지터리에 접근할 때 LFS 클라이언트에 정보를 제공하기 위해 GitLab Shell에서 호출되는 엔드포인트입니다.

요청 예시:

curl --request POST --header "Gitlab-Shell-Api-Request: " \
     --data "key_id=11&project=gnuwget/wget2" "http://localhost:3001/api/v4/internal/lfs_authenticate"

{
  "username": "root",
  "lfs_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7ImFjdG9yIjoicm9vdCJ9LCJqdGkiOiIyYWJhZDcxZC0xNDFlLTQ2NGUtOTZlMi1mODllYWRiMGVmZTYiLCJpYXQiOjE1NzAxMTc2NzYsIm5iZiI6MTU3MDExNzY3MSwiZXhwIjoxNTcwMTE5NDc2fQ.g7atlBw1QMY7QEBVPE0LZ8ZlKtaRzaMRmNn41r2YITM",
  "repository_http_path": "http://localhost:3001/gnuwget/wget2.git",
  "expires_in": 1800
}

알려진 소비자#

• GitLab Shell

인가된 키 확인#

이 엔드포인트는 GitLab Shell 인가된 키 확인에 의해 호출됩니다. 빠른 SSH 키 조회를 위해 OpenSSH 또는 GitLab SSHD에서 호출됩니다.

GET /internal/authorized_keys

요청 예시:

curl --request GET --header "Gitlab-Shell-Api-Request: " "http://localhost:3001/api/v4/internal/authorized_keys?key=<key>"

응답 예시:

{
  "id": 11,
  "title": "admin@example.com",
  "key": "ssh-rsa ...",
  "created_at": "2019-06-27T15:29:02.219Z"
}

알려진 소비자#

• GitLab Shell

인가된 인증서#

이 엔드포인트는 특정 CA SSH 인증서가 구성된 네임스페이스를 가져오기 위해 GitLab Shell에서 호출됩니다. 또한 user_identifier를 받아 지정된 식별자에 대한 GitLab 사용자를 반환합니다.

GET /internal/authorized_certs

요청 예시:

curl --request GET --header "Gitlab-Shell-Api-Request: " "http://localhost:3001/api/v4/internal/authorized_certs?key=<key>&user_identifier=<user_identifier>"

응답 예시:

{
  "success": true,
  "namespace": "gitlab-org",
  "username": "root"
}

알려진 소비자#

• GitLab Shell

사용자 ID 또는 키로 사용자 가져오기#

이 엔드포인트는 사용자가 ssh git@gitlab.com을 수행할 때 사용됩니다. SSH 키와 연결된 사용자를 찾습니다.

GET /internal/discover

요청 예시:

curl --request GET --header "Gitlab-Shell-Api-Request: " "http://localhost:3001/api/v4/internal/discover?key_id=7"

응답 예시:

{
  "id": 7,
  "name": "Dede Eichmann",
  "username": "rubi"
}

알려진 소비자#

• GitLab Shell

인스턴스 정보#

인스턴스에 대한 일반적인 정보를 가져옵니다. Geo 노드에서 서로의 정보를 가져오는 데 사용됩니다.

GET /internal/check

요청 예시:

curl --request GET --header "Gitlab-Shell-Api-Request: " "http://localhost:3001/api/v4/internal/check"

응답 예시:

{
  "api_version": "v4",
  "gitlab_version": "12.3.0-pre",
  "gitlab_rev": "d69c988e6a6",
  "redis": true
}

알려진 소비자#

• GitLab Geo

• GitLab Shell의 bin/check

• Gitaly

SSH 키를 사용하여 새 2FA 복구 코드 가져오기#

GitLab Shell에서 호출되며 사용자가 SSH 키를 기반으로 새 2FA 복구 코드를 가져올 수 있게 합니다.

GET /internal/two_factor_recovery_codes

요청 예시:

curl --request POST --header "Gitlab-Shell-Api-Request: " \
     --data "key_id=7" "http://localhost:3001/api/v4/internal/two_factor_recovery_codes"

응답 예시:

{
  "success": true,
  "recovery_codes": [
    "d93ee7037944afd5",
    "19d7b84862de93dd",
    "1e8c52169195bf71",
    "be50444dddb7ca84",
    "26048c77d161d5b7",
    "482d5c03d1628c47",
    "d2c695e309ce7679",
    "dfb4748afc4f12a7",
    "0e5f53d1399d7979",
    "af04d5622153b020"
  ]
}

알려진 소비자#

• GitLab Shell

새 개인 액세스 토큰 가져오기#

GitLab Shell에서 호출되며 사용자가 새 개인 액세스 토큰을 생성할 수 있게 합니다.

POST /internal/personal_access_token

요청 예시:

curl --request POST --header "Gitlab-Shell-Api-Request: " \
     --data "user_id=29&name=mytokenname&scopes[]=read_user&scopes[]=read_repository&expires_at=2020-07-24" \
     "http://localhost:3001/api/v4/internal/personal_access_token"

응답 예시:

{
  "success": true,
  "token": "Hf_79B288hRv_3-TSD1R",
  "scopes": ["read_user","read_repository"],
  "expires_at": "2020-07-24"
}

알려진 소비자#

• GitLab Shell

오류 추적 요청 인증#

이 엔드포인트는 오류 추적 Go REST API 애플리케이션에서 프로젝트를 인증하기 위해 호출됩니다.

POST /internal/error_tracking/allowed

요청 예시:

curl --request POST --header "Gitlab-Shell-Api-Request: " \
     --data "project_id=111&public_key=generated-error-tracking-key" \
          "http://localhost:3001/api/v4/internal/error_tracking/allowed"

응답 예시:

{ "enabled": true }

알려진 소비자#

• OpsTrace

pre-receive에서 카운터 증가#

푸시가 수락될 수 있는 경우 참조 카운터를 증가시키는 Gitaly 훅에서 호출됩니다.

POST /internal/pre_receive

요청 예시:

curl --request POST --header "Gitlab-Shell-Api-Request: " \
     --data "gl_repository=project-7" "http://localhost:3001/api/v4/internal/pre_receive"

응답 예시:

{
  "reference_counter_increased": true
}

PostReceive#

푸시를 수신한 후 Gitaly에서 호출됩니다. Sidekiq에서 PostReceive-worker를 트리거하고, 전달된 푸시 옵션을 처리하며 사용자에게 표시해야 하는 메시지를 포함한 응답을 빌드합니다.

POST /internal/post_receive

요청 예시:

curl --request POST --header "Gitlab-Shell-Api-Request: " \
     --data "gl_repository=project-7" --data "identifier=user-1" \
     --data "changes=0000000000000000000000000000000000000000 fd9e76b9136bdd9fe217061b497745792fe5a5ee gh-pages\n" \
     "http://localhost:3001/api/v4/internal/post_receive"

응답 예시:

{
  "messages": [
    {
      "message": "Hello from post-receive",
      "type": "alert"
    }
  ],
  "reference_counter_decreased": true
}

쿠버네티스용 GitLab 에이전트 엔드포인트#

히스토리

• GitLab 16.7에서 기능 플래그 제거됨.

다음 엔드포인트들은 쿠버네티스용 GitLab 에이전트 서버(kas)에서 다양한 목적으로 사용됩니다.

이 엔드포인트들은 모두 JWT를 사용하여 인증됩니다. JWT 시크릿은 config/gitlab.yml에 지정된 파일에 저장됩니다. 기본적으로 위치는 GitLab Rails 앱의 루트에 있는 .gitlab_kas_secret이라는 파일입니다.

쿠버네티스용 GitLab 에이전트 정보#

주어진 에이전트 토큰에 대한 에이전트 정보를 가져오기 위해 쿠버네티스용 GitLab 에이전트 서버(kas)에서 호출됩니다. kas가 에이전트 구성을 가져오고 업데이트하기 위해 에이전트 프로젝트의 Gitaly 연결 정보를 반환합니다.

GET /internal/kubernetes/agent_info

요청 예시:

curl --request GET --header "Gitlab-Kas-Api-Request: " \
     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/agent_info"

쿠버네티스용 GitLab 에이전트 프로젝트 정보#

주어진 에이전트 토큰에 대한 프로젝트 정보를 가져오기 위해 쿠버네티스용 GitLab 에이전트 서버(kas)에서 호출됩니다. 요청된 프로젝트에 대한 Gitaly 연결을 반환합니다. GitLab kas는 이를 사용하여 프로젝트 리포지터리에서 쿠버네티스 리소스를 가져와 동기화하도록 에이전트를 구성합니다.

공개 프로젝트만 지원됩니다. 비공개 프로젝트의 경우, 에이전트에 대한 인가 기능은 아직 구현되지 않았습니다.

GET /internal/kubernetes/project_info

요청 예시:

curl --request GET --header "Gitlab-Kas-Api-Request: " \
     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/project_info?id=7"

쿠버네티스용 GitLab 에이전트 사용량 메트릭#

사용량 메트릭 카운터를 증가시키기 위해 쿠버네티스용 GitLab 에이전트 서버(kas)에서 호출됩니다.

POST /internal/kubernetes/usage_metrics

요청 예시:

curl --request POST --header "Gitlab-Kas-Api-Request: " --header "Content-Type: application/json" \
     --data '{"counters": {"k8s_api_proxy_request":1}}' "http://localhost:3000/api/v4/internal/kubernetes/usage_metrics"

쿠버네티스용 GitLab 에이전트 이벤트#

이벤트를 추적하기 위해 쿠버네티스용 GitLab 에이전트 서버(kas)에서 호출됩니다.

POST /internal/kubernetes/agent_events

요청 예시:

curl --request POST \
  --url "http://localhost:3000/api/v4/internal/kubernetes/agent_events" \
  --header "Gitlab-Kas-Api-Request: " \
  --header "Content-Type: application/json" \
  --data '{
    "events": {
      "k8s_api_proxy_requests_unique_users_via_ci_access": [
        {
          "user_id": 1,
          "project_id": 1
        }
      ]
    }
  }'

Starboard 취약점 생성#

Starboard 취약점 보고서에서 보안 취약점을 생성하기 위해 쿠버네티스용 GitLab 에이전트 서버(kas)에서 호출됩니다. 이 요청은 멱등성을 가집니다. 동일한 데이터로 여러 번 요청해도 단일 취약점만 생성됩니다. 응답에는 생성된 취약점 찾기의 UUID가 포함됩니다.

PUT internal/kubernetes/modules/starboard_vulnerability

요청 예시:

curl --request PUT --header "Gitlab-Kas-Api-Request: " \
     --header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" \
     --url "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability" \
     --data '{
  "vulnerability": {
    "name": "CVE-123-4567 in libc",
    "severity": "high",
    "confidence": "unknown",
    "location": {
      "kubernetes_resource": {
        "namespace": "production",
        "kind": "deployment",
        "name": "nginx",
        "container": "nginx"
      }
    },
    "identifiers": [
      {
        "type": "cve",
        "name": "CVE-123-4567",
        "value": "CVE-123-4567"
      }
    ]
  },
  "scanner": {
    "id": "starboard_trivy",
    "name": "Trivy (via Starboard Operator)",
    "vendor": "GitLab"
  }
}'

응답 예시:

{
  "uuid": "4773b2ee-5ba5-5e9f-b48c-5f7a17f0faac"
}

Starboard 취약점 해결#

Starboard 보안 취약점을 해결하기 위해 쿠버네티스용 GitLab 에이전트 서버(kas)에서 호출됩니다. 찾기 UUID 목록을 받아 해당 목록에서 식별되지 않은 모든 Starboard 취약점을 해결된 것으로 표시합니다.

POST internal/kubernetes/modules/starboard_vulnerability/scan_result

요청 예시:

curl --request POST --header "Gitlab-Kas-Api-Request: " \
     --header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" \
     --url "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability/scan_result" \
     --data '{ "uuids": ["102e8a0a-fe29-59bd-b46c-57c3e9bc6411", "5eb12985-0ed5-51f4-b545-fd8871dc2870"] }'

스캔 실행 정책#

에이전트 토큰이 속한 프로젝트에 구성된 scan_execution_policies를 가져오기 위해 쿠버네티스용 GitLab 에이전트 서버(kas)에서 호출됩니다. GitLab kas는 이를 사용하여 정책에 따라 쿠버네티스 클러스터의 이미지를 스캔하도록 에이전트를 구성합니다.

GET /internal/kubernetes/modules/starboard_vulnerability/scan_execution_policies

요청 예시:

curl --request GET --header "Gitlab-Kas-Api-Request: " \
     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability/scan_execution_policies"

응답 예시:

{
  "policies": [
    {
      "name": "Policy",
      "description": "Policy description",
      "enabled": true,
      "yaml": "---\nname: Policy\ndescription: 'Policy description'\nenabled: true\nactions:\n- scan: container_scanning\nrules:\n- type: pipeline\n  branches:\n  - main\n",
      "updated_at": "2022-06-02T05:36:26+00:00"
    }
  ]
}

정책 구성#

에이전트 토큰이 속한 프로젝트에 구성된 policies_configuration을 가져오기 위해 쿠버네티스용 GitLab 에이전트 서버(kas)에서 호출됩니다. GitLab kas는 이를 사용하여 구성에 따라 쿠버네티스 클러스터의 이미지를 스캔하도록 에이전트를 구성합니다.

GET /internal/kubernetes/modules/starboard_vulnerability/policies_configuration

요청 예시:

curl --request GET --header "Gitlab-Kas-Api-Request: " \
     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability/policies_configuration"

응답 예시:

{
  "configurations": [
    {
      "cadence": "30 2 * * *",
      "namespaces": [
        "namespace-a",
        "namespace-b"
      ],
      "updated_at": "2022-06-02T05:36:26+00:00"
    }
  ]
}

검색#

다음 엔드포인트들은 Zoekt와 같은 GitLab 검색 서비스에서 사용됩니다.

Zoekt#

다음 엔드포인트들은 Zoekt에서 하트비트와 인덱싱 콜백 응답을 전송하기 위해 호출됩니다.

하트비트 전송 및 인덱싱 태스크 가져오기#

이 엔드포인트를 사용하여 노드의 마지막 확인 시각 타임스탬프를 계속 업데이트하고 Zoekt의 미처리 태스크를 가져옵니다.

POST /internal/search/zoekt/:uuid/heartbeat

요청 예시:

curl --location "https://example.com/api/v4/internal/search/3869fe21-36d1-4612-9676-0b783ef2dcd7/heartbeat" \
--header "Gitlab-Shell-Api-Request: " \
--header "Content-Type: application/json" \
--data '{
    "node.url": "http://localhost:6090",
    "node.name": "foo.local",
    "disk.all": "994662584320",
    "disk.used": "532673712128"
}'

응답 예시:

{
  "id": 1,
  "truncate": true,
  "tasks": [
    {
      "name": "index",
      "payload": {
        "GitalyConnectionInfo": {
          "Address": "unix:/praefect.socket",
          "Token": null,
          "Storage": "default",
          "Path": "@hashed/79/02/7902699be42c8a8e46fbbb4501726517e86b22c56a189f7625a6da49081d9043.git",
          "Callback": {
            "name": "index",
            "Payload": {
              "task_id": 1,
              "schema_version": 2531
            }
          },
          "RepoId": 1,
          "FileSizeLimit": 1048576,
          "Parallelism": 1,
          "Timeout": "1800s",
          "FileCountLimit": 500000,
          "TrigramMax": 20000,
          "MissingRepo": false,
          "Metadata": {
            "project_id": "1",
            "traversal_ids": "3-",
            "visibility_level": "10",
            "repository_access_level": "20",
            "forked": "f",
            "archived": "f"
          },
          "Force": true
        }
      }
    }
  ],
  "pull_frequency": "5s",
  "stop_indexing": false
}

인덱싱 태스크 처리 후 콜백 전송#

인덱싱 태스크를 처리한 후 페이로드 데이터와 함께 콜백을 전송하는 데 이 엔드포인트를 사용합니다.

POST /internal/search/zoekt/:uuid/callback

요청 예시:

curl --location "https://example.com/api/v4/internal/search/3869fe21-36d1-4612-9676-0b783ef2dcd7/callback" \
--header "Gitlab-Shell-Api-Request: " \
--header "Content-Type: application/json" \
--data '{
    "name": "index",
    "success": true,
    "payload": { "schema_version": 2531, "task_id": 48 },
    "additional_payload": { "repo_stats": { "index_file_count": 1, "size_in_bytes": 41800 } }
}'

응답 예시:

{ "message": "202 Accepted" }

스토리지 한도 예외#

네임스페이스 스토리지 한도 예외 엔드포인트는 GitLab.com의 최상위 네임스페이스에서 스토리지 한도 예외를 관리합니다. 이 엔드포인트들은 GitLab.com의 관리자 영역에서만 사용할 수 있습니다.

스토리지 한도 예외 조회#

GET 요청을 사용하여 모든 Namespaces::Storage::LimitExclusion 레코드를 가져옵니다.

GET /namespaces/storage/limit_exclusions

요청 예시:

curl --request GET \
  --url "https://gitlab.com/v4/namespaces/storage/limit_exclusions" \
  --header 'PRIVATE-TOKEN: <admin access token>'

응답 예시:

[
    {
      "id": 1,
      "namespace_id": 1234,
      "namespace_name": "A Namespace Name",
      "reason": "a reason to exclude the Namespace"
    },
    {
      "id": 2,
      "namespace_id": 4321,
      "namespace_name": "Another Namespace Name",
      "reason": "another reason to exclude the Namespace"
    },
]

스토리지 한도 예외 생성#

POST 요청을 사용하여 Namespaces::Storage::LimitExclusion을 생성합니다.

POST /namespaces/:id/storage/limit_exclusion

요청 예시:

curl --request POST \
  --url "https://gitlab.com/v4/namespaces/123/storage/limit_exclusion" \
  --header 'Content-Type: application/json' \
  --header 'PRIVATE-TOKEN: <admin access token>' \
  --data '{
    "reason": "a reason to exclude the Namespace"
  }'

응답 예시:

{
  "id": 1,
  "namespace_id": 1234,
  "namespace_name": "A Namespace Name",
  "reason": "a reason to exclude the Namespace"
}

스토리지 한도 예외 삭제#

DELETE 요청을 사용하여 네임스페이스의 Namespaces::Storage::LimitExclusion을 삭제합니다.

DELETE /namespaces/:id/storage/limit_exclusion

요청 예시:

curl --request DELETE \
  --url "https://gitlab.com/v4/namespaces/123/storage/limit_exclusion" \
  --header 'PRIVATE-TOKEN: <admin access token>'

응답 예시:

204

알려진 소비자#

• GitLab.com 관리자 영역

그룹 SCIM API#

히스토리

• GitLab 19.0에서 사용자 프로비저닝 해제가 동기식에서 비동기식으로 변경됨.

그룹 SCIM API는 RFC7644 프로토콜을 부분적으로 구현합니다. 이 API는 /groups/:group_path/Users 및 /groups/:group_path/Users/:id 엔드포인트를 제공합니다. 기본 URL은 <http|https>:///api/scim/v2입니다. 이 API는 SCIM 공급자 통합을 위한 시스템 용도이므로 예고 없이 변경될 수 있습니다.

이 API를 사용하려면 그룹에 대해 Group SSO를 활성화하세요. 이 API는 그룹 SSO용 SCIM이 활성화된 경우에만 사용됩니다. SCIM ID 생성의 전제 조건입니다.

이 그룹 SCIM API는:

• SCIM 공급자 통합을 위한 시스템 용도입니다.

• RFC7644 프로토콜을 구현합니다.

• 그룹에 대해 SCIM으로 프로비저닝된 사용자 목록을 가져옵니다.

• 그룹에 대해 SCIM으로 프로비저닝된 사용자를 생성, 삭제 및 업데이트합니다.

인스턴스 SCIM API는 인스턴스에 대해 동일한 작업을 수행합니다.

사용자 프로비저닝 해제는 비동기적으로 처리됩니다. GitLab에서 성공 응답을 받은 후 사용자가 모든 그룹 및 프로젝트에서 완전히 제거되기까지 몇 분이 걸릴 수 있습니다.

이 그룹 SCIM API는 SCIM API와 다릅니다. SCIM API는:

• 내부 API가 아닙니다.

• RFC7644 프로토콜을 구현하지 않습니다.

• 그룹의 SCIM ID를 가져오고, 확인하고, 업데이트하고, 삭제합니다.

이 API는 Gitlab-Shell-Api-Request 헤더가 필요하지 않습니다.

SCIM 프로비저닝된 사용자 목록 가져오기#

이 엔드포인트는 SCIM 동기화 메커니즘의 일부로 사용됩니다. 사용된 필터에 따라 사용자 목록을 반환합니다.

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

파라미터:

페이지네이션은 다른 곳에서 사용하는 GitLab 페이지네이션이 아닌 SCIM 사양을 따릅니다. 요청 사이에 레코드가 변경되면 페이지에서 다른 페이지로 이동한 레코드가 누락되거나 이전 요청의 레코드가 반복될 수 있습니다.

특정 식별자로 필터링하는 요청 예시:

curl "https://gitlab.example.com/api/scim/v2/groups/test_group/Users?filter=id%20eq%20%220b1d561c-21ff-4092-beab-8154b17f82f2%22" \
     --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
        }
      ]
    }
  ]
}

단일 SCIM 프로비저닝된 사용자 가져오기#

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

파라미터:

요청 예시:

curl "https://gitlab.example.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
    }
  ]
}

SCIM 프로비저닝된 사용자 생성#

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

파라미터:

요청 예시:

curl --verbose --request POST "https://gitlab.example.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 상태 코드를 반환합니다.

사용자에 대한 그룹 SCIM ID를 생성한 후, 관리자 영역에서 해당 SCIM ID를 볼 수 있습니다.

단일 SCIM 프로비저닝된 사용자 업데이트#

업데이트할 수 있는 필드:

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

파라미터:

사용자의 id 업데이트 요청 예시:

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --data '{ "Operations": [{"op":"replace","path":"id","value":"1234abcd"}] }' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

성공하면 204 상태 코드와 함께 빈 응답을 반환합니다.

사용자의 active 상태 설정 요청 예시:

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --data '{ "Operations": [{"op":"replace","path":"active","value":"true"}] }' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

성공하면 204 상태 코드와 함께 빈 응답을 반환합니다.

단일 SCIM 프로비저닝된 사용자 제거#

사용자의 SSO ID 및 그룹 멤버십을 제거합니다.

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

파라미터:

요청 예시:

curl --verbose --request DELETE "https://gitlab.example.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 상태 코드와 함께 빈 응답을 반환합니다.

인스턴스 SCIM API#

히스토리

• GitLab 18.0에서 그룹 동기화 지원이 추가됨.

인스턴스 SCIM API는 RFC7644 프로토콜을 부분적으로 구현합니다. 이 API는 사용자 및 그룹을 관리하는 엔드포인트를 제공합니다. 기본 URL은 <http|https>:///api/scim/v2입니다. 이 API는 SCIM 공급자 통합을 위한 시스템 용도이므로 예고 없이 변경될 수 있습니다.

이 API를 사용하려면 인스턴스에 대해 SAML SSO를 활성화하세요.

이 인스턴스 SCIM API는:

• SCIM 공급자 통합을 위한 시스템 용도입니다.

• RFC7644 프로토콜을 구현합니다.

• SCIM으로 프로비저닝된 사용자 목록을 가져옵니다.

• SCIM으로 프로비저닝된 사용자를 생성, 삭제 및 업데이트합니다.

• SAML 그룹 링크를 통해 그룹 멤버십을 관리합니다.

그룹 SCIM API는 그룹에 대해 동일한 작업을 수행합니다.

이 인스턴스 SCIM API는 SCIM API와 다릅니다. SCIM API는:

• 내부 API가 아닙니다.

• RFC7644 프로토콜을 구현하지 않습니다.

• 그룹 내 SCIM ID를 가져오고, 확인하고, 업데이트하고, 삭제합니다.

이 API는 Gitlab-Shell-Api-Request 헤더가 필요하지 않습니다.

사용자 엔드포인트#

사용자 엔드포인트를 사용하여 SCIM으로 프로비저닝된 사용자를 관리합니다.

SCIM 프로비저닝된 사용자 목록 가져오기#

이 엔드포인트는 SCIM 동기화 메커니즘의 일부로 사용됩니다. 사용된 필터에 따라 사용자 목록을 반환합니다.

GET /api/scim/v2/application/Users

파라미터:

페이지네이션은 다른 곳에서 사용하는 GitLab 페이지네이션이 아닌 SCIM 사양을 따릅니다. 요청 사이에 레코드가 변경되면 페이지에서 다른 페이지로 이동한 레코드가 누락되거나 이전 요청의 레코드가 반복될 수 있습니다.

요청 예시:

curl "https://gitlab.example.com/api/scim/v2/application/Users?filter=id%20eq%20%220b1d561c-21ff-4092-beab-8154b17f82f2%22" \
     --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
        }
      ]
    }
  ]
}

단일 SCIM 프로비저닝된 사용자 가져오기#

GET /api/scim/v2/application/Users/:id

파라미터:

요청 예시:

curl "https://gitlab.example.com/api/scim/v2/application/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
    }
  ]
}

SCIM 프로비저닝된 사용자 생성#

POST /api/scim/v2/application/Users

파라미터:

요청 예시:

curl --verbose --request POST "https://gitlab.example.com/api/scim/v2/application/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 상태 코드를 반환합니다.

단일 SCIM 프로비저닝된 사용자 업데이트#

업데이트할 수 있는 필드:

PATCH /api/scim/v2/application/Users/:id

파라미터:

요청 예시:

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/application/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --data '{ "Operations": [{"op":"Update","path":"active","value":"false"},{"op":"Update","path":"id","value":"foo"}] }' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

성공하면 204 상태 코드와 함께 빈 응답을 반환합니다.

단일 SCIM 프로비저닝된 사용자 차단#

사용자는 차단됨 상태로 전환되고 로그아웃됩니다. 즉, 사용자는 로그인하거나 코드를 푸시하거나 풀할 수 없습니다.

DELETE /api/scim/v2/application/Users/:id

파라미터:

요청 예시:

curl --verbose --request DELETE "https://gitlab.example.com/api/scim/v2/application/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

성공하면 204 상태 코드와 함께 빈 응답을 반환합니다.

그룹 엔드포인트#

그룹 엔드포인트를 사용하여 SCIM ID 공급자와 GitLab을 자동으로 동기화합니다.

이 API는 SAML 그룹 링크를 사용하여 IdP(ID 공급자) 그룹과 GitLab 그룹을 연결합니다. 이 엔드포인트를 사용하기 전에 동기화하려는 그룹에 필요한 SAML 그룹 링크를 생성해야 합니다.

SCIM 그룹 목록 가져오기#

이 엔드포인트는 SCIM ID가 할당된 그룹 목록을 반환합니다.

GET /api/scim/v2/application/Groups

파라미터:

페이지네이션은 GitLab 페이지네이션이 아닌 SCIM 사양을 따릅니다.

요청 예시:

curl "https://gitlab.example.com/api/scim/v2/application/Groups?filter=displayName%20eq%20%22Developers%22" \
     --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:Group"
      ],
      "id": "86e7d437-1a55-4731-b3a3-2867fb4d2a94",
      "displayName": "Developers",
      "members": [
        {
          "value": "2435223452",
          "display": "Sidney Jones",
          "type": "User"
        }
      ],
      "meta": {
        "resourceType": "Group"
      }
    }
  ]
}

단일 SCIM 그룹 가져오기#

GET /api/scim/v2/application/Groups/:id

파라미터:

요청 예시:

curl "https://gitlab.example.com/api/scim/v2/application/Groups/86e7d437-1a55-4731-b3a3-2867fb4d2a94" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

응답 예시:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "86e7d437-1a55-4731-b3a3-2867fb4d2a94",
  "displayName": "Developers",
  "members": [
    {
      "value": "2435223452",
      "display": "Sidney Jones",
      "type": "User"
    }
  ],
  "meta": {
    "resourceType": "Group"
  }
}

members의 각 항목은 SCIM 그룹에 속한 사용자를 설명합니다:

SCIM 그룹 생성#

이 엔드포인트는 SCIM 그룹 ID를 동일한 이름의 기존 SAML 그룹 링크와 연결합니다.

POST /api/scim/v2/application/Groups

파라미터:

요청 예시:

curl --verbose --request POST "https://gitlab.example.com/api/scim/v2/application/Groups" \
     --data '{"displayName":"Developers","schemas":["urn:ietf:params:scim:schemas:core:2.0:Group"]}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

응답 예시:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "86e7d437-1a55-4731-b3a3-2867fb4d2a94",
  "displayName": "Developers",
  "members": [],
  "meta": {
    "resourceType": "Group"
  }
}

성공하면 201 상태 코드를 반환합니다.

이 엔드포인트는 GitLab 그룹을 생성하지 않습니다. 지정된 표시 이름을 가진 기존 SAML 그룹 링크에만 SCIM ID를 연결합니다.

SCIM 그룹 업데이트#

SCIM 그룹의 멤버를 업데이트합니다. SCIM 그룹과 연결된 GitLab 그룹에서 사용자를 추가하거나 제거하는 데 사용됩니다.

PATCH /api/scim/v2/application/Groups/:id

파라미터:

지원되는 작업:

• path가 members인 add로 그룹에 멤버 추가

• path가 members인 remove로 그룹에서 멤버 제거

멤버 추가 요청 예시:

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/application/Groups/86e7d437-1a55-4731-b3a3-2867fb4d2a94" \
     --data '{"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],"Operations":[{"op":"add","path":"members","value":[{"value":"f0b1d561c-21ff-4092-beab-8154b17f82f2"}]}]}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

멤버 제거 요청 예시:

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/application/Groups/86e7d437-1a55-4731-b3a3-2867fb4d2a94" \
     --data '{"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],"Operations":[{"op":"remove","path":"members","value":[{"value":"f0b1d561c-21ff-4092-beab-8154b17f82f2"}]}]}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

성공하면 204 상태 코드와 함께 빈 응답을 반환합니다.

SCIM 그룹 교체#

SCIM 그룹의 모든 멤버를 새 멤버 집합으로 교체합니다.

PUT /api/scim/v2/application/Groups/:id

파라미터:

요청 예시:

curl --verbose --request PUT "https://gitlab.example.com/api/scim/v2/application/Groups/86e7d437-1a55-4731-b3a3-2867fb4d2a94" \
     --data '{"schemas":["urn:ietf:params:scim:schemas:core:2.0:Group"],"displayName":"Developers","members":[{"value":"f0b1d561c-21ff-4092-beab-8154b17f82f2"}]}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

응답에는 업데이트된 그룹 정보가 포함됩니다.

PUT 작업은 모든 그룹 멤버를 교체합니다. 요청에 포함되지 않은 기존 멤버는 이 SCIM 그룹과 연결된 모든 GitLab 그룹에서 제거됩니다.

SCIM 그룹 삭제#

SCIM 그룹 ID를 지워 기존 SAML 그룹 링크에서 SCIM 관리를 제거합니다. 이 엔드포인트는 또한 SCIM 그룹 멤버십 추적 레코드의 백그라운드 정리를 예약합니다.

DELETE /api/scim/v2/application/Groups/:id

파라미터:

요청 예시:

curl --verbose --request DELETE "https://gitlab.example.com/api/scim/v2/application/Groups/86e7d437-1a55-4731-b3a3-2867fb4d2a94" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

성공하면 204 상태 코드와 함께 빈 응답을 반환합니다.

이 엔드포인트는 GitLab 그룹을 삭제하지 않습니다. 지정된 SCIM 그룹 ID를 가진 SAML 그룹 링크에서 SCIM 관리만 제거하여 ID 공급자가 불필요한 SCIM 그룹을 프로비저닝 해제할 수 있도록 합니다.

사용 가능한 필터#

RFC7644 필터링 섹션에 지정된 대로 표현식을 매칭합니다.

예시:

id eq a-b-c-d

사용 가능한 작업#

RFC7644 업데이트 섹션에 지정된 대로 작업을 수행합니다.

예시:

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