내부 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로 전달하기 위해 필요한 정보로 응답합니다.
  • pre-receive 후크에서 Gitaly에서 호출될 때: 변경 사항이 전달되고, 푸시가 허용되는지 확인됩니다.

각 호출은 최대 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 인증

이것은 저장소가 SSH로 접근될 때 LFS 클라이언트에게 정보를 제공하기 위해 GitLab Shell에서 호출되는 엔드포인트입니다.

속성 유형 필수 설명
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

인증된 키 확인

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

속성 유형 필수 설명
key 문자열 예 공개 키 인증에 사용된 승인된 키 
GET /internal/authorized_keys

예시 요청: 

curl --request GET --header "Gitlab-Shell-Api-Request: <JWT 토큰>" "http://localhost:3001/api/v4/internal/authorized_keys?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 토큰>" "http://localhost:3001/api/v4/internal/authorized_certs?key=<키>&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 토큰>" "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 정수 아니요 ssh 키 파일 또는 /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 문자열 예 통합된 오류 추적 기능에 의해 생성된 공개 키 
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 string yes 푸시를 받는 저장소의 식별자 
POST /internal/pre_receive

예시 요청: 

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

예시 응답: 

{
  "reference_counter_increased": true
}

PostReceive

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

속성 타입 필수 설명
identifier string yes 푸시 수행 사용자를 식별하는 user-[id] 또는 key-[id]
gl_repository string yes 푸시되는 저장소의 식별자
push_options string array no 푸시 옵션 배열
changes string no oldrev newrev refname\n 형식의 푸시에서 업데이트할 ref 
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": "포스트-리시브에서 안녕하세요",
      "type": "알림"
    }
  ],
  "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 integer/string yes 프로젝트의 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 해시 no 카운터의 해시
counters["k8s_api_proxy_request"] 정수 no k8s_api_proxy_request 카운터를 증가시킬 수
counters["gitops_sync"] 정수 no gitops_sync 카운터를 증가시킬 수
counters["flux_git_push_notifications_total"] 정수 no flux_git_push_notifications_total 카운터를 증가시킬 수
counters["k8s_api_proxy_requests_via_ci_access"] 정수 no k8s_api_proxy_requests_via_ci_access 카운터를 증가시킬 수
counters["k8s_api_proxy_requests_via_user_access"] 정수 no k8s_api_proxy_requests_via_user_access 카운터를 증가시킬 수
counters["k8s_api_proxy_requests_via_pat_access"] 정수 no k8s_api_proxy_requests_via_pat_access 카운터를 증가시킬 수
unique_counters 해시 no 고유 숫자 배열
unique_counters["k8s_api_proxy_requests_unique_users_via_ci_access"] 정수 배열 no ci_access를 통해 CI 터널을 상호 작용한 고유 사용자 ID 세트로, k8s_api_proxy_requests_unique_users_via_ci_access 메트릭 이벤트를 추적함
unique_counters["k8s_api_proxy_requests_unique_agents_via_ci_access"] 정수 배열 no ci_access를 통해 CI 터널을 상호 작용한 고유 에이전트 ID 세트로, k8s_api_proxy_requests_unique_agents_via_ci_access 메트릭 이벤트를 추적함
unique_counters["k8s_api_proxy_requests_unique_users_via_user_access"] 정수 배열 no user_access를 통해 CI 터널을 상호 작용한 고유 사용자 ID 세트로, k8s_api_proxy_requests_unique_users_via_user_access 메트릭 이벤트를 추적함
unique_counters["k8s_api_proxy_requests_unique_agents_via_user_access"] 정수 배열 no user_access를 통해 CI 터널을 상호 작용한 고유 에이전트 ID 세트로, k8s_api_proxy_requests_unique_agents_via_user_access 메트릭 이벤트를 추적함
unique_counters["k8s_api_proxy_requests_unique_users_via_pat_access"] 정수 배열 no 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"] 정수 배열 no PAT를 통해 KAS Kubernetes API 프록시를 사용한 고유 에이전트 ID 세트로, k8s_api_proxy_requests_unique_agents_via_pat_access 메트릭 이벤트를 추적함
unique_counters["flux_git_push_notified_unique_projects"] 정수 배열 no Flux 워크로드를 조정할 고유 프로젝트 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": {"gitops_sync":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 취약점 보고서로부터 보안 취약점을 생성하기 위해 호출됩니다. 이 요청은 멱등(idempotent)합니다. 동일한 데이터로 여러 요청을 한 경우 하나의 취약점을 생성합니다. 응답에는 생성된 취약점 탐지의 UUID가 포함됩니다.

속성 유형 필수 설명
vulnerability 해시 네 보안 보고서 스키마와 일치하는 취약점 데이터 vulnerability 필드과 일치합니다.
scanner 해시 yes 보안 보고서 스키마와 일치하는 스캐너 데이터 scanner 필드와 일치합니다. 
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": "libc의 CVE-123-4567",
    "severity": "높음",
    "confidence": "알 수 없음",
    "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 문자열 배열 예 Create Starboard vulnerability 응답에서 수집된 검색 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": "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"
    }
  ]
}

정책 구성

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 날짜 예 구독 시작 날짜
end_date 날짜 아니요 구독 만료 날짜
plan_code 문자열 아니요 구독 티어 코드
seats 정수 아니요 구독에서의 좌석 수
max_seats_used 정수 아니요 지난 달 동안의 활성 사용자 수
auto_renew 부울 아니요 구독 만료 시 자동 갱신 여부
trial 부울 아니요 구독이 체험인지 여부
trial_starts_on 날짜 아니요 체험 시작 날짜
trial_ends_on 날짜 아니요 체험 종료 날짜

예시 요청: 

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 date no 구독 시작일
end_date date no 구독 종료일
plan_code string no 구독 티어 코드
seats integer no 구독에 포함된 좌석 수
max_seats_used integer no 지난 달의 활성 사용자 중 가장 많은 수
auto_renew boolean no 구독이 자동 갱신되는지 여부
trial boolean no 구독이 시험판인지 여부
trial_starts_on date no 시험판 시작일. 시험판이 true인 경우 필수입니다.
trial_ends_on date no 시험판 종료일

예시 요청: 

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의 최상위 그룹과 같은 곳에 코드 제안과 같은 구독 애드온을 적용하기 위해 사용됩니다. 이는 저장소 및 컴퓨팅 팩 구매에는 사용되지 않습니다.

구독 애드온 구매 생성

구독 애드온 구매를 생성하려면 POST 명령을 사용하세요. 

POST /namespaces/:id/subscription_add_on_purchase/:add_on_name
속성 유형 필수 설명
quantity integer yes 구독 애드온 구매의 단위 수 (예: 코드 제안 애드온의 좌석 수)
expires_on date yes 구독 애드온 구매의 만료일
purchase_xid string yes 구독 애드온 구매를 위한 식별자 (예: 코드 제안 애드온의 구독 이름)

예시 요청: 

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""

예시 응답: 

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

구독 애드온 구매 업데이트

기존 구독 애드온 구매를 업데이트하려면 PUT 명령을 사용하세요. 

PUT /namespaces/:id/subscription_add_on_purchase/:add_on_name
속성 유형 필수 설명
quantity integer no 구독 애드온 구매의 단위 수 (예: 코드 제안 애드온의 좌석 수)
expires_on date yes 구독 애드온 구매의 만료일
purchase_xid string no 구독 애드온 구매를 위한 식별자 (예: 코드 제안 애드온의 구독 이름)

예시 요청: 

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""

예시 응답: 

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

구독 애드온 구매내역 조회

기존 구독 애드온 구매내역을 보려면 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"
}

알려진 소비자

  • 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": "a reason to exclude the Namespace"
    },
    {
      "id": 2,
      "namespace_id": 4321,
      "namespace_name": "Another Namespace Name",
      "reason": "another reason to exclude the Namespace"
    },
]

저장소 용량 제외 생성

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

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

예시 요청: 

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"
}

저장소 용량 제외 삭제

네임스페이스의 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”가 “컴퓨팅 할당량” 및 “컴퓨팅 분”으로 이름이 변경되었습니다.

컴퓨팅 할당량 엔드포인트는 CustomersDot (customers.gitlab.com)에서 GitLab.com의 개인 네임스페이스 또는 최상위 그룹에 추가 컴퓨팅 분 팩을 적용하기 위해 사용됩니다.

추가 팩 생성

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

POST /namespaces/:id/minutes
속성 유형 필수 설명
packs array yes 구매한 컴퓨트 팩 배열
packs[expires_at] date yes 구매한 팩의 만료일
packs[number_of_minutes] integer yes 추가 컴퓨팅 분 수
packs[purchase_xid] string yes 구매의 고유 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 string yes 팩을 이동할 네임스페이스의 ID
target_id string yes 팩을 이동할 대상 네임스페이스의 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 array yes 예정된 조정사항의 배열

각 배열 요소는 다음을 포함합니다:

속성 유형 필수 설명
namespace_id integer yes 조정될 네임스페이스의 ID
next_reconciliation_date date yes 다음 조정사항의 날짜
display_alert_from date yes 예정된 조정사항 경고의 표시 시작 날짜

예시 요청: 

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 integer yes 예정된 조정사항이 더 이상 존재하지 않는 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 식별자를 가져오거나 확인, 업데이트, 삭제하지 않습니다.

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

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

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

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

매개변수:

속성 유형 필수 설명
filter 문자열 아니오 filter 표현식
group_path 문자열 예 그룹의 전체 경로
startIndex 정수 아니오 결과를 반환할 시작 위치를 나타내는 1 기반 인덱스. 1보다 작은 값은 1로 해석됩니다.
count 정수 아니오 원하는 쿼리 결과의 최대 수

참고: 페이지네이션은 다른 곳에서 사용되는 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 문자열 예 사용자의 외부 UID
group_path 문자열 예 그룹의 전체 경로

예시 요청: 

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 문자열 예 사용자의 외부 UID
userName 문자열 예 사용자의 사용자 이름
emails JSON 문자열 예 작업 이메일
name JSON 문자열 예 사용자의 이름
meta 문자열 아니오 리소스 유형 (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 상태 코드가 반환됩니다.

참고: 사용자의 그룹 SCIM 식별 정보를 만든 후에는 관리자 영역에서 해당 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 yes 사용자의 외부 UID.
group_path string yes 그룹의 전체 경로.
Operations JSON 문자열 yes 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 string yes 사용자의 외부 UID.
group_path string yes 그룹의 전체 경로.

예시 요청: 

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 ID를 가져오고 확인하며 업데이트하고 삭제합니다.

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

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

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

GET /api/scim/v2/application/Users

매개변수:

속성 유형 필수 설명
filter string no 사용 가능한 필터 표현.
startIndex integer no 결과를 반환할 시작 위치를 나타내는 1부터 시작하는 인덱스입니다. 1보다 작은 값은 1로 해석됩니다.
count integer no 원하는 쿼리 결과의 최대 개수입니다.

참고: 페이지네이션은 다른 곳에서 사용되는 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

매개변수:

속성 유형 필수 설명
id string yes 사용자의 외부 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": "Test User",
  "userName": "username",
  "meta": { "resourceType":"User" },
  "emails": [
    {
      "type":"work",
      "value":"name@example.com",
      "primary":true
    }
  ]
}

SCIM 프로비저닝된 사용자 만들기 

POST /api/scim/v2/application/Users

매개변수:

속성 유형 필수 설명
externalId string yes 사용자의 외부 UID입니다.
userName string yes 사용자의 사용자 이름입니다.
emails JSON string yes 작업 이메일입니다.
name JSON string yes 사용자의 이름입니다.
meta string no 리소스 유형 (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":"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 프로비저닝된 사용자 업데이트

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

SCIM/IdP 필드 GitLab 필드
id/externalId extern_uid
active false인 경우 사용자가 차단되지만, SCIM 신원은 여전히 연결됨. 
PATCH /api/scim/v2/application/Users/:id

매개변수:

속성 유형 필요 여부 설명
id 문자열 yes 사용자의 외부 UID.
Operations JSON 문자열 yes 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 문자열 yes 사용자의 외부 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" }