내부 API

내부 API는 다양한 GitLab 컴포넌트에서 사용되며 기타 소비자에서는 사용할 수 없습니다. 이 설명서는 GitLab 코드베이스에서 작업하는 사람들을 위해 프로덕션되었습니다.

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

새 엔드포인트 추가

API 엔드포인트는 기본적으로 외부에서 접근 가능해야 하며 적절한 인증 및 권한이 필요합니다. 새로운 내부 엔드포인트를 추가하기 전에 해당 API가 보다 넓은 GitLab 커뮤니티에 유용할 수 있고 외부에서 접근 가능하게 할 수 있는지를 고려하세요.

가끔씩 우리가 내부 API 엔드포인트를 선호하는 이유는 해당 엔드포인트를 사용하는 데 내부 데이터가 필요한 경우입니다. 예를 들어, 내부 Pages API에서는 외부 액터가 가질 수 없는 비밀 토큰을 사용하거나 해당 엔드포인트로의 요청을 공개 키로 서명할 수 있습니다.

내부 API로 뭔가를 분리하는 또 다른 이유는 해당 API 엔드포인트로의 요청이 절대로 엣지(공용) 로드 밸런서를 통해 전달되어서는 안 되는 경우입니다. 이렇게 함으로써 해당 엔드포인트에 대한 액세스 규칙 및 정책을 구성할 수 있습니다. 왜냐하면 해당 엔드포인트로는 내부 요청만을 알고 있다는 것을 알기 때문에 내부 로드 밸런서를 통해만 요청이 이뤄질 것이기 때문입니다.

인증

이러한 방법들은 모두 공유 비밀을 사용하여 인증됩니다. 이 비밀은 기본적으로 config/gitlab.yml에 구성된 경로의 파일에 저장됩니다. 기본적으로 이는 레일 앱의 루트에 .gitlab_shell_secret라는 이름으로 저장됩니다.

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

  1. 그 파일의 내용을 읽습니다.
  2. 파일 내용을 사용하여 JSON Web Token(JWT)을 생성합니다.
  3. JWT를 Gitlab-Shell-Api-Request 헤더에 전달합니다.

Git 인증

이는 Gitaly 및 GitLab Shell에 의해 리포지터리 접근 권한을 확인하기 위해 호출됩니다.

  • GitLab Shell에서 호출되는 경우: 변경 사항이 전달되지 않으며 내부 API는 요청을 Gitaly에게 전달할 필요가 있는 정보를 반환합니다.
  • Gitaly에서 pre-receive 후크로 호출되는 경우: 변경 사항이 전달되고 푸시가 허용되는지 여부를 확인하여 유효성이 검사됩니다.

각 요청은 50초로 제한됩니다.

이 엔드포인트는 더 자세하게 다루어져 있으며 별도의 페이지에서 다루어집니다. 

POST /internal/allowed
속성 유형 필수 설명
key_id 문자열 아니요 GitLab Shell에 연결하는 데 사용되는 SSH 키의 ID
username 문자열 아니요 GitLab Shell에 연결하는 데 사용된 인증서의 사용자 이름
project 문자열 아니요 (gl_repository가 전달된 경우 아니요) 프로젝트 경로
gl_repository 문자열 아니요 (project가 전달된 경우 아니요) 프로젝트 식별자(project-7와 같은)
protocol 문자열 예 GitLab Shell에서 호출될 경우 SSH, Gitaly에서 호출될 경우 HTTP 또는 SSH
action 문자열 예 실행 중인 Git 명령 (git-upload-pack, git-receive-pack, git-upload-archive)
changes 문자열 예 Gitaly에서 호출된 경우 <oldrev> <newrev> <refname>, GitLab Shell에서 호출된 경우 마법의 문자열 _any
check_ip 문자열 아니요 GitLab Shell로의 호출 시 사용된 IP 주소

예시 요청: 

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT 토큰>" \
     --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 인증

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

속성 유형 필수 설명
key_id 문자열 아니요 GitLab Shell에 연결하는 데 사용되는 SSH 키의 ID
username 문자열 아니요 GitLab Shell에 연결하는 데 사용된 인증서의 사용자 이름
project 문자열 아니요 프로젝트 경로

예시 요청: 

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT 토큰>" \
     --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

허가된 키 확인

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

속성 유형 필수 설명
key 문자열 예 공개 키 인증에 사용되는 허가된 키입니다. 
GET /internal/authorized_keys

예시 요청: 

curl --request GET --header "Gitlab-Shell-Api-Request: <JWT 토큰>" "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

인증된 인증서

이 엔드포인트는 GitLab Shell에 의해 호출되어, 특정 CA SSH 인증서가 구성된 네임스페이스를 가져오고, user_identifier를 허용하여 지정된 식별자에 대한 GitLab 사용자를 반환합니다.

속성 유형 필수 설명
key 문자열 예 SSH 인증서의 지문.
user_identifier 문자열 예 해당 식별자에 대한 SSH 인증서가 발급된 사용자의 식별자(사용자 이름 또는 주요 이메일). 
GET /internal/authorized_certs

예시 요청: 

curl --request GET --header "Gitlab-Shell-Api-Request: <JWT token>" "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 키에 연결된 사용자를 찾습니다.

속성 유형 필수 설명
key_id 정수 아니요 승인된 키 파일이나 /authorized_keys 확인을 통해 찾은 SSH 키의 ID
username 문자열 아니요 인증서를 사용하여 인증할 때 GitLab Shell에서 사용되는 사용자 이름 
GET /internal/discover

예시 요청: 

curl --request GET --header "Gitlab-Shell-Api-Request: <JWT token>" "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: <JWT token>" "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 복구 코드를 가져올 수 있습니다.

속성 유형 필수 설명
key_id 정수 아니요 승인된 키 파일이나 /authorized_keys 확인을 통해 찾은 SSH 키의 ID
user_id 정수 아니요 새로운 복구 코드를 생성할 사용자 ID [사용 중단됨] 
GET /internal/two_factor_recovery_codes

예시 요청: 

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --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에서 호출되어, 사용자가 새로운 개인 접근 토큰을 생성할 수 있습니다.

속성 유형 필수 설명
name 문자열 예 새 토큰의 이름
scopes 문자열 배열 예 새 토큰의 권한 범위, 유효한 토큰 권한이어야 함
expires_at 문자열 아니요 새 토큰의 만료 날짜
key_id 정수 아니요 승인된 키 파일이나 /authorized_keys 확인을 통해 찾은 SSH 키의 ID
user_id 정수 아니요 새 토큰을 생성할 사용자 ID 
POST /internal/personal_access_token

예시 요청: 

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --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 응용 프로그램에 의해 호출되어 프로젝트를 인증합니다. > GitLab 15.1에 도입되었습니다.

속성 유형 필수 설명
project_id 정수 예 관련 키를 가지고 있는 프로젝트의 ID
public_key 문자열 예 통합된 Error Tracking 기능에서 생성된 공개 키 
POST /internal/error_tracking/allowed

예시 요청: 

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --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 후크에서 호출되어, 수락될 수 있는 푸시에 대해 참조 카운터를 증가시킵니다.

속성 유형 필수 설명
gl_repository 문자열 예 푸시를 받는 리포지터리의 리포지터리 식별자 
POST /internal/pre_receive

예시 요청: 

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

예시 응답: 

{
  "reference_counter_increased": true
}

PostReceive

Gitaly에서 push를 받은 후에 호출됩니다. 이는 PostReceive-worker를 Sidekiq에서 트리거하며, 전달된 푸시 옵션을 처리하고 사용자에게 표시해야 하는 메시지를 포함하여 응답을 작성합니다.

속성 유형 필수 설명
identifier 문자열 예 push를 수행하는 사용자 식별(예: user-[id] 또는 key-[id])
gl_repository 문자열 예 푸시되는 리포지터리의 식별자
push_options 문자열 배열 아니요 푸시 옵션의 배열
changes 문자열 아니요 푸시에서 업데이트할 참조(refs)를 나타내는 형식 (oldrev newrev refname\n) 
POST /internal/post_receive

예시 요청: 

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT 토큰>" \
     --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 에이전트 서버(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: <JWT 토큰>" \
     --header "Authorization: Bearer <에이전트 토큰>" "http://localhost:3000/api/v4/internal/kubernetes/agent_info"

GitLab 에이전트 프로젝트 정보

GitLab 에이전트 서버(kas)에서 호출되어 주어진 에이전트 토큰에 대한 프로젝트 정보를 검색합니다. 이는 요청된 프로젝트의 Gitaly 연결을 반환합니다. GitLab kas는 이를 사용하여 에이전트를 구성하여 프로젝트 리포지터리에서 Kubernetes 리소스를 동기화합니다.

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

속성 유형 필수 설명
id 정수/문자열 예 프로젝트의 ID 또는 URL 인코딩된 경로 
GET /internal/kubernetes/project_info

예시 요청: 

curl --request GET --header "Gitlab-Kas-Api-Request: <JWT 토큰>" \
     --header "Authorization: Bearer <에이전트 토큰>" "http://localhost:3000/api/v4/internal/kubernetes/project_info?id=7"

GitLab 에이전트 사용량 지표

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

속성 유형 필수 설명
counters 해시 아니요 카운터 해시
counters["k8s_api_proxy_request"] 정수 아니요 k8s_api_proxy_request 카운터를 증가시킬 수 있는 숫자
counters["flux_git_push_notifications_total"] 정수 아니요 flux_git_push_notifications_total 카운터를 증가시킬 수 있는 숫자
counters["k8s_api_proxy_requests_via_ci_access"] 정수 아니요 k8s_api_proxy_requests_via_ci_access 카운터를 증가시킬 수 있는 숫자
counters["k8s_api_proxy_requests_via_user_access"] 정수 아니요 k8s_api_proxy_requests_via_user_access 카운터를 증가시킬 수 있는 숫자
counters["k8s_api_proxy_requests_via_pat_access"] 정수 아니요 k8s_api_proxy_requests_via_pat_access 카운터를 증가시킬 수 있는 숫자
unique_counters 해시 아니요 고유 숫자 배열
unique_counters["k8s_api_proxy_requests_unique_users_via_ci_access"] 정수 배열 아니요 ci_access를 통해 CI 터널과 상호 작용한 고유 사용자 ID 집합을 추적하는 k8s_api_proxy_requests_unique_users_via_ci_access 메트릭 이벤트
unique_counters["k8s_api_proxy_requests_unique_agents_via_ci_access"] 정수 배열 아니요 ci_access를 통해 CI 터널과 상호 작용한 고유 에이전트 ID 집합을 추적하는 k8s_api_proxy_requests_unique_agents_via_ci_access 메트릭 이벤트
unique_counters["k8s_api_proxy_requests_unique_users_via_user_access"] 정수 배열 아니요 user_access를 통해 CI 터널과 상호 작용한 고유 사용자 ID 집합을 추적하는 k8s_api_proxy_requests_unique_users_via_user_access 메트릭 이벤트
unique_counters["k8s_api_proxy_requests_unique_agents_via_user_access"] 정수 배열 아니요 user_access를 통해 CI 터널과 상호 작용한 고유 에이전트 ID 집합을 추적하는 k8s_api_proxy_requests_unique_agents_via_user_access 메트릭 이벤트
unique_counters["k8s_api_proxy_requests_unique_users_via_pat_access"] 정수 배열 아니요 PAT를 통해 KAS Kubernetes API 프록시를 사용한 고유 사용자 ID 집합을 추적하는 k8s_api_proxy_requests_unique_users_via_pat_access 메트릭 이벤트
unique_counters["k8s_api_proxy_requests_unique_agents_via_pat_access"] 정수 배열 아니요 PAT를 통해 KAS Kubernetes API 프록시를 사용한 고유 에이전트 ID 집합을 추적하는 k8s_api_proxy_requests_unique_agents_via_pat_access 메트릭 이벤트
unique_counters["flux_git_push_notified_unique_projects"] 정수 배열 아니요 플럭스 워크로드를 조정하기 위해 통지된 고유 프로젝트 ID 집합을 추적하는 flux_git_push_notified_unique_projects 메트릭 이벤트 
POST /internal/kubernetes/usage_metrics

예시 요청: 

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

GitLab 에이전트 이벤트

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

| 속성 | 유형 | 필수 | 설명 | |:—————————————————————————|:—————-|:———|:——————————| | events | 해시 | 아니요 | 이벤트 해시 | | events["k8s_api_proxy_requests_unique_users_via_ci_access"] | 해시 배열 | 아니요 | k8s_api_proxy_requests_unique_users_via_ci_access를 위한 이벤트 배열 | | events["k8s_api_proxy_requests_unique_users_via_ci_access"]["user_id"] | 정수 | 아니요 | 이벤트에 대한 사용자 ID | | events["k8s_api_proxy_requests_unique_users_via_ci_access"]["project_id"]| 정수 | 아니요 | 이벤트에 대한 프로젝트 ID | | events["k8s_api_proxy_requests_unique_users_via_user_access"] | 해시 배열 | 아니요 | k8s_api_proxy_requests_unique_users_via_user_access를 위한 이벤트 배열 | | events["k8s_api_proxy_requests_unique_users_via_user_access"]["user_id"] | 정수 | 아니요 | 이벤트에 대한 사용자 ID | | events["k8s_api_proxy_requests_unique_users_via_user_access"]["project_id"]| 정수 | 아니요 | 이벤트에 대한 프로젝트 ID | | events[“k8s_api_proxy_requests_unique_users_via_pat_access”] | 해시 배열 | 아니요 | k8s_api_proxy_requests_unique_users_via_pat_access를 위한 이벤트 배열 | | events[“k8s_api_proxy_requests_unique_users_via_pat_access”][“user_id”] | 정수 | 아니요 | 이벤트에 대한 사용자 ID | | events[“k8s_api_proxy_requests_unique_users_via_pat_access”][“project_id”]| 정수 | 아니요 | 이벤트에 대한 프로젝트 ID | 

POST /internal/kubernetes/agent_events

예시 요청: 

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

Starboard 취약점 생성

GitLab 에이전트 서버(kas)에서 Starboard 취약점 보고서로부터 보안 취약점을 생성하기 위해 호출됩니다. 이 요청은 멱등성을 가지고 있습니다. 동일한 데이터로 여러 요청을 보내더라도 단일 취약점이 생성됩니다. 응답에는 생성된 취약점 파인딩의 UUID가 포함됩니다.

속성 유형 필수 설명
vulnerability Hash yes 보안 보고서 스키마와 일치하는 취약점 데이터 vulnerability field.
scanner Hash yes 보안 보고서 스키마와 일치하는 스캐너 데이터 scanner field. 
PUT internal/kubernetes/modules/starboard_vulnerability

예시 요청: 

curl --request PUT --header "Gitlab-Kas-Api-Request: <JWT 토큰>" \
     --header "Authorization: Bearer <에이전트 토큰>" --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 취약점 해결

GitLab 에이전트 서버(kas)에서 Starboard 보안 취약점을 해결하기 위해 호출됩니다. 발견된 UUID 디렉터리을 수락하고, 디렉터리에 포함되지 않은 모든 Starboard 취약점을 해결되지 않은 것으로 표시합니다.

속성 유형 필수 설명
uuids string array yes Starboard 취약점 생성 응답에서 수집된 발견 UUID 디렉터리. 
POST internal/kubernetes/modules/starboard_vulnerability/scan_result

예시 요청: 

curl --request POST --header "Gitlab-Kas-Api-Request: <JWT 토큰>" \
     --header "Authorization: Bearer <에이전트 토큰>" --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"] }'

스캔 실행 정책

GitLab 에이전트 서버(kas)에서 에이전트 토큰에 속한 프로젝트를 위해 구성된 scan_execution_policies를 검색하는 데에 사용됩니다. GitLab kas는 이를 사용하여 Kubernetes 클러스터 내의 이미지를 정책에 따라 스캔하도록 에이전트를 구성합니다. 

GET /internal/kubernetes/modules/starboard_vulnerability/scan_execution_policies

예시 요청: 

curl --request GET --header "Gitlab-Kas-Api-Request: <JWT 토큰>" \
     --header "Authorization: Bearer <에이전트 토큰>" "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability/scan_execution_policies"

예시 응답: 

{
  "policies": [
    {
      "name": "Policy",
      "description": "정책 설명",
      "enabled": true,
      "yaml": "---\nname: Policy\ndescription: '정책 설명'\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"
    }
  ]
}

정책 구성

GitLab 에이전트 서버(kas)에서 에이전트 토큰에 속한 프로젝트를 위해 구성된 policies_configuration을 검색하는 데에 사용됩니다. GitLab kas는 이를 사용하여 Kubernetes 클러스터 내의 이미지를 구성에 따라 스캔하도록 에이전트를 구성합니다. 

GET /internal/kubernetes/modules/starboard_vulnerability/policies_configuration

예시 요청: 

curl --request GET --header "Gitlab-Kas-Api-Request: <JWT 토큰>" \
     --header "Authorization: Bearer <에이전트 토큰>" "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"
    }
  ]
}

구독

구독 엔드포인트는 CustomersDot (customers.gitlab.com)에서 GitLab.com 내의 개인 네임스페이스 또는 최상위 그룹에 대한 평가판 및 애드온 구매를 포함하여 구독을 적용하는 데에 사용됩니다.

구독 생성

POST 명령을 사용하여 구독을 생성합니다. 

POST /namespaces/:id/gitlab_subscription
속성 유형 필수 설명
start_date 날짜 yes 구독 시작 날짜
end_date 날짜 no 구독 종료 날짜
plan_code 문자열 no 구독 티어 코드
seats 정수 no 구독에 포함된 좌석 수
max_seats_used 정수 no 지난 달에 활성 사용자의 최대 수
auto_renew 부울 no 구독이 자동 갱신되는지 여부
trial 부울 no 구독이 평가판인지 여부
trial_starts_on 날짜 no 평가판 시작 날짜
trial_ends_on 날짜 no 평가판 종료 날짜

예시 요청: 

curl --request POST --header "TOKEN: <관리자 액세스 토큰>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?start_date="2020-07-15"&plan="premium"&seats=10"

예시 응답: 

{
  "plan": {
    "code":"premium",
    "name":"premium",
    "trial":false,
    "auto_renew":null,
    "upgradable":false,
  },
  "usage": {
    "seats_in_subscription":10,
    "seats_in_use":1,
    "max_seats_used":0,
    "seats_owed":0
  },
  "billing": {
    "subscription_start_date":"2020-07-15",
    "subscription_end_date":null,
    "trial_ends_on":null
  }
}

구독 업데이트

기존 구독을 업데이트하려면 PUT 명령을 사용합니다. 

PUT /namespaces/:id/gitlab_subscription
속성 유형 필수 설명
start_date 날짜 아니오 구독 시작 날짜
end_date 날짜 아니오 구독 종료 날짜
plan_code 문자열 아니오 구독 티어 코드
seats 정수 아니오 구독의 좌석 수
max_seats_used 정수 아니오 지난 달에 활성 사용자 수가 가장 많았을 때
auto_renew 부울 아니오 구독 종료 시 자동 갱신 여부
trial 부울 아니오 구독이 체험판인지 여부
trial_starts_on 날짜 아니오 체험판 시작 날짜. 체험판인 경우 필수입니다.
trial_ends_on 날짜 아니오 체험판 종료 날짜

예시 요청: 

curl --request PUT --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?max_seats_used=0"

예시 응답: 

{
  "plan": {
    "code":"premium",
    "name":"premium",
    "trial":false,
    "auto_renew":null,
    "upgradable":false,
  },
  "usage": {
    "seats_in_subscription":80,
    "seats_in_use":82,
    "max_seats_used":0,
    "seats_owed":2
  },
  "billing": {
    "subscription_start_date":"2020-07-15",
    "subscription_end_date":"2021-07-15",
    "trial_ends_on":null
  }
}

구독 조회

기존 구독을 보려면 GET 명령을 사용합니다. 

GET /namespaces/:id/gitlab_subscription

예시 요청: 

curl --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription"

예시 응답: 

{
  "plan": {
    "code":"premium",
    "name":"premium",
    "trial":false,
    "auto_renew":null,
    "upgradable":false,
    "exclude_guests":false,
  },
  "usage": {
    "seats_in_subscription":80,
    "seats_in_use":82,
    "max_seats_used":82,
    "seats_owed":2
  },
  "billing": {
    "subscription_start_date":"2020-07-15",
    "subscription_end_date":"2021-07-15",
    "trial_ends_on":null
  }
}

알려진 소비자

  • CustomersDot

구독 추가 온 구매(스토리지 및 컴퓨팅 팩 제외)

구독 추가 온 구매 엔드포인트는 CustomersDot (customers.gitlab.com)에서 사용됩니다. 이를 통해 개인 네임스페이스나 GitLab.com 내에서 최상위 그룹과 같은 구독 추가 온 구매(예: 개인 네임스페이스를 위한 Code Suggestions)를 적용합니다. 이는 스토리지 및 컴퓨팅 팩 구매에는 사용되지 않습니다.

구독 추가 온 구매 생성

구독 추가 온 구매를 생성하려면 POST 명령을 사용합니다. 

POST /namespaces/:id/subscription_add_on_purchase/:add_on_name
속성 유형 필수 설명
quantity 정수 예 구독 추가 온 구매의 단위 수 (예: Code Suggestions 추가 온 구매의 좌석 수)
expires_on 날짜 예 구독 추가 온 구매의 만료 날짜
purchase_xid 문자열 예 구독 추가 온 구매의 식별자 (예: Code Suggestions 추가 온 구매의 구독 이름)
trial 부울 아니오 추가 온이 체험판인지 여부

예시 요청: 

curl --request POST --header "PRIVATE-TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/subscription_add_on_purchase/code_suggestions?&quantity=10&expires_on="2024-07-15"&purchase_xid="A-S12345678"&trial=true"

예시 응답: 

{
  "namespace_id":1234,
  "namespace_name":"A Namespace Name",
  "add_on":"Code Suggestions",
  "quantity":10,
  "expires_on":"2024-07-15",
  "purchase_xid":"A-S12345678",
  "trial":true
}

구독 추가 온 구매 업데이트

기존 구독 추가 온 구매를 업데이트하려면 PUT 명령을 사용합니다. 

PUT /namespaces/:id/subscription_add_on_purchase/:add_on_name
속성 유형 필수 설명
quantity 정수 아니오 구독 추가 온 구매의 단위 수 (예: Code Suggestions 추가 온 구매의 좌석 수)
expires_on 날짜 예 구독 추가 온 구매의 만료 날짜
purchase_xid 문자열 아니오 구독 추가 온 구매의 식별자 (예: Code Suggestions 추가 온 구매의 구독 이름)
trial 부울 아니오 추가 온이 체험판인지 여부

예시 요청: 

curl --request PUT --header "PRIVATE-TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/subscription_add_on_purchase/code_suggestions?&quantity=15&expires_on="2024-07-15"&purchase_xid="A-S12345678"&trial=true"

예시 응답: 

{
  "namespace_id":1234,
  "namespace_name":"A Namespace Name",
  "add_on":"Code Suggestions",
  "quantity":15,
  "expires_on":"2024-07-15",
  "purchase_xid":"A-S12345678",
  "trial":true
}

구독 추가 온 구매 조회

기존 구독 추가 온 구매를 보려면 GET 명령을 사용합니다. 

GET /namespaces/:id/subscription_add_on_purchase/:add_on_name

예시 요청: 

curl --header "PRIVATE-TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/subscription_add_on_purchase/code_suggestions"

예시 응답: 

{
  "namespace_id":1234,
  "namespace_name":"A Namespace Name",
  "add_on":"Code Suggestions",
  "quantity":15,
  "expires_on":"2024-07-15",
  "purchase_xid":"A-S12345678",
  "trial":true
}

알려진 소비자

  • CustomersDot

스토리지 한도 제외

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

스토리지 한도 제외 조회

모든 Namespaces::Storage::LimitExclusion 레코드를 검색하려면 GET 요청을 사용합니다. 

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": "네임스페이스를 제외하는 이유"
    },
    {
      "id": 2,
      "namespace_id": 4321,
      "namespace_name": "Another Namespace Name",
      "reason": "다른 네임스페이스를 제외하는 이유"
    },
]

스토리지 제한 제외 생성

Namespaces::Storage::LimitExclusion를 생성하려면 POST 요청을 사용하십시오. 

POST /namespaces/:id/storage/limit_exclusion
속성 유형 필수 설명
reason 문자열 예 네임스페이스를 제외하는 이유

예시 요청: 

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": "네임스페이스를 제외하는 이유"
  }'

예시 응답: 

{
  "id": 1,
  "namespace_id": 1234,
  "namespace_name": "네임스페이스 이름",
  "reason": "네임스페이스를 제외하는 이유"
}

스토리지 제한 제외 삭제

네임스페이스의 Namespaces::Storage::LimitExclusion를 삭제하려면 DELETE 요청을 사용하십시오. 

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 관리 영역

할당량 프로비저닝 계산

  • GitLab 16.1에서 “CI/CD minutes”가 “compute quota” 및 “compute minutes”로 이름이 변경되었습니다.

할당량 프로비저닝 엔드포인트는 개인 네임스페이스나 GitLab.com의 최상위 그룹을 대상으로 하는 추가 컴퓨트 분에 대한 적용을 위해 CustomersDot (customers.gitlab.com)에서 사용됩니다.

추가 팩 생성

추가 팩을 만들려면 POST 명령을 사용하십시오. 

POST /namespaces/:id/minutes
속성 유형 필수 설명
packs 배열 예 구매한 컴퓨트 팩들의 배열
packs[expires_at] 날짜 예 구매한 팩의 만료 날짜
packs[number_of_minutes] 정수 예 추가 컴퓨트 분의 수
packs[purchase_xid] 문자열 예 구매의 고유 ID

예시 요청: 

curl --request POST \
  --url "http://localhost:3000/api/v4/namespaces/123/minutes" \
  --header 'Content-Type: application/json' \
  --header 'PRIVATE-TOKEN: <admin access token>' \
  --data '{
    "packs": [
      {
        "number_of_minutes": 10000,
        "expires_at": "2022-01-01",
        "purchase_xid": "46952fe69bebc1a4de10b2b4ff439d0c"
      }
    ]
  }'

예시 응답: 

[
  {
    "namespace_id": 123,
    "expires_at": "2022-01-01",
    "number_of_minutes": 10000,
    "purchase_xid": "46952fe69bebc1a4de10b2b4ff439d0c"
  }
]

추가 팩 이동

추가 팩을 다른 네임스페이스로 이동하려면 PATCH 명령을 사용하십시오. 

PATCH /namespaces/:id/minutes/move/:target_id
속성 유형 필수 설명
id 문자열 예 팩을 이동할 네임스페이스 ID
target_id 문자열 예 팩을 이동할 대상 네임스페이스 ID

예시 요청: 

curl --request PATCH \
  --url "http://localhost:3000/api/v4/namespaces/123/minutes/move/321" \
  --header 'PRIVATE-TOKEN: <admin access token>'

예시 응답: 

{
  "message": "202 Accepted"
}

알려진 사용자

  • CustomersDot

예정 중인 조정

upcoming_reconciliations 엔드포인트는 CustomersDot (customers.gitlab.com)에서 네임스페이스의 예정 중인 조정을 업데이트하는 데 사용됩니다.

upcoming_reconciliations 업데이트

upcoming_reconciliations을 업데이트하려면 PUT 명령을 사용하십시오. 

PUT /internal/upcoming_reconciliations
속성 유형 필수 설명
upcoming_reconciliations 배열 예 예정 중인 조정 배열

각 배열 요소는:

속성 유형 필수 설명
namespace_id 정수 예 조정할 네임스페이스 ID
next_reconciliation_date 날짜 예 다음 조정일
display_alert_from 날짜 예 예정 중인 조정 경고 시작일

예시 요청: 

curl --request PUT --header "PRIVATE-TOKEN: <admin_access_token>" --header "Content-Type: application/json" \
     --data '{"upcoming_reconciliations": [{"namespace_id": 127, "next_reconciliation_date": "13 Jun 2021", "display_alert_from": "06 Jun 2021"}, {"namespace_id": 129, "next_reconciliation_date": "12 Jun 2021", "display_alert_from": "05 Jun 2021"}]}' \
     "https://gitlab.com/api/v4/internal/upcoming_reconciliations"

예시 응답: 

200

upcoming_reconciliation 삭제

upcoming_reconciliation을 삭제하려면 DELETE 명령을 사용하십시오. 

DELETE /internal/upcoming_reconciliations
속성 유형 필수 설명
namespace_id 정수 예 예정 중인 조정이 더 이상 없는 GitLab.com 네임스페이스 ID

예시 요청: 

curl --request DELETE \
  --url "http://localhost:3000/api/v4/internal/upcoming_reconciliations?namespace_id=22" \
  --header 'PRIVATE-TOKEN: <admin_access_token>'

예시 응답: 

204

알려진 사용자

  • CustomersDot

그룹 SCIM API

Tier: Premium, Ultimate Offering: GitLab.com

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

이 API를 사용하려면 그룹에 그룹 SSO를 활성화하십시오. 이 API는 SCIM for Group SSO가 활성화된 경우에만 사용됩니다. 이는 SCIM 식별자 생성의 선행 조건입니다.

이 그룹 SCIM API:

  • SCIM 제공자 통합을 위한 시스템 사용을 위한 것입니다.
  • RFC7644 프로토콜을 구현합니다.
  • 그룹에 대해 SCIM으로 제공된 사용자 디렉터리을 가져옵니다.
  • 그룹의 SCIM으로 제공된 사용자를 생성, 삭제 및 업데이트합니다.

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

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

  • 내부 API가 아닙니다.
  • RFC7644 프로토콜을 구현하지 않습니다.
  • 그룹 내에서 SCIM 식별자를 가져오고 확인하며, 업데이트하고 삭제합니다.
note
이 API는 Gitlab-Shell-Api-Request 헤더가 필요하지 않습니다.

SCIM 프로비저닝된 사용자 디렉터리 가져오기

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

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

파라미터:

속성 타입 필수 여부 설명
filter string 아니오 filter 표현식.
group_path string 예 그룹의 전체 경로.
startIndex 정수 아니오 결과를 반환할 시작 위치를 나타내는 1부터 시작하는 인덱스. 1보다 작은 값은 1로 해석됩니다.
count 정수 아니오 원하는 최대 쿼리 결과 수.
note
페이지네이션은 다른 곳에서 사용되는 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

파라미터:

속성 타입 필수 여부 설명
id string 예 사용자의 외부 UID.
group_path string 예 그룹의 전체 경로.

예시 요청: 

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/

파라미터:

속성 타입 필수 여부 설명
externalId string 예 사용자의 외부 UID.
userName string 예 사용자의 사용자명.
emails JSON 문자열 예 업무 이메일.
name JSON 문자열 예 사용자의 이름.
meta string 아니오 리소스 유형 (User).

예시 요청: 

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 상태 코드를 반환합니다.

note
사용자의 그룹 SCIM 식별을 생성한 후, Admin 영역에서 해당 SCIM 식별을 볼 수 있습니다.

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

업데이트할 수 있는 필드는 다음과 같습니다:

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 string 예 사용자의 외부 UID.
group_path string 예 그룹의 전체 경로.
Operations JSON 문자열 예 operations 표현식.

사용자의 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 식별 및 그룹 멤버십을 제거합니다. 

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

매개변수:

속성 유형 필수 설명
id 문자열 예 사용자의 외부 UID.
group_path 문자열 예 그룹의 전체 경로.

예시 요청: 

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

Tier: Premium, Ultimate Offering: Self-Managed

인스턴스 SCIM API는 RFC7644 프로토콜을 부분적으로 구현합니다. 이 API는 /application/Users 및 /application/Users/:id 엔드포인트를 제공합니다. 기본 URL은 <http|https>://<GitLab 호스트>/api/scim/v2입니다. 이 API는 SCIM 프로바이더 통합을 위한 시스템 사용을 위해 제공되므로 사전 통지없이 변경될 수 있습니다.

이 API를 사용하려면 인스턴스에 대해 SAML SSO를 활성화해야 합니다.

이 인스턴스 SCIM API는 다음을 수행합니다:

  • SCIM 프로비저닝된 사용자 디렉터리을 가져옵니다.
  • 그룹에 대해 SCIM 프로비저닝된 사용자를 생성, 삭제 및 업데이트합니다.

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

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

  • 내부 API가 아닙니다.
  • RFC7644 프로토콜을 구현하지 않습니다.
  • 그룹 내 SCIM 식별자를 가져오고 확인하며 업데이트 및 삭제합니다.
note
이 API는 Gitlab-Shell-Api-Request 헤더가 필요하지 않습니다.

SCIM 프로비저닝된 사용자 디렉터리 가져오기

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

GET /api/scim/v2/application/Users

매개변수:

속성 유형 필수 설명
filter 문자열 아니오 필터 표현식.
startIndex 정수 아니오 결과 반환을 시작할 1을 기준으로 한 색인. 1보다 작은 값은 1로 해석됩니다.
count 정수 아니오 원하는 최대 쿼리 결과 수.
note
페이지네이션은 문자마다 SCIM 사양을 따르며 다른 곳에서 사용된 GitLab 페이징과는 다릅니다. 요청 사이에 레코드가 변경되면 페이지에서 이전 요청에있는 레코드가 다른 페이지로 이동한 레코드를 누락하거나 반복해서 표시할 수 있습니다.

예시 요청: 

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

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

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

매개변수:

속성 유형 필수 설명
id 문자열 예 사용자의 외부 UID.

예시 요청: 

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

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

POST /api/scim/v2/application/Users

매개변수:

속성 유형 필수 설명
externalId 문자열 예 사용자의 외부 UID.
userName 문자열 예 사용자의 사용자 이름.
emails JSON 문자열 예 업무 이메일.
name JSON 문자열 예 사용자의 이름.
meta 문자열 아니오 리소스 유형 (User).

예시 요청: 

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

성공할 경우 201 상태 코드를 반환합니다.

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

업데이트할 수 있는 필드는 다음과 같습니다:

SCIM/IdP 필드 GitLab 필드
id/externalId extern_uid
active false인 경우 사용자가 차단되지만, SCIM 식별 정보는 연결된 상태입니다. 
PATCH /api/scim/v2/application/Users/:id

매개변수:

속성 유형 필수 여부 설명
id 문자열 예 사용자의 외부 UID.
Operations JSON 문자열 예 operations 표현식.

예시 요청: 

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"}] }' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

성공한 경우 204 상태 코드와 빈 응답을 반환합니다.

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

사용자가 차단 상태로 설정되고 로그아웃됩니다. 즉, 사용자는 로그인하거나 코드를 푸시하거나 끌 수 없습니다. 

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

매개변수:

속성 유형 필수 여부 설명
id 문자열 예 사용자의 외부 UID.

예시 요청: 

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 상태 코드와 빈 응답을 반환합니다.

사용 가능한 필터

RFC7644 필터링 섹션에 명시된 대로 표현식을 일치시킵니다.

필터 설명
eq 속성이 지정된 값과 정확히 일치합니다.

예시: 

id eq a-b-c-d

사용 가능한 작업

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

오퍼레이터 설명
Replace 속성 값이 업데이트됩니다.
Add 속성에 새로운 값이 있습니다.

예시: 

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