%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
accTitle: Authorization workflow
accDescr: The flow of authorization requests between GitLab and a cloud provider.
participant GitLab
Note right of Cloud: Create OIDC identity provider
Note right of Cloud: Create role with conditionals
Note left of GitLab: CI/CD job with ID token
GitLab->>+Cloud: Call cloud API with ID token
Note right of Cloud: Decode & verify JWT with public key (https://gitlab.com/oauth/discovery/keys)
Note right of Cloud: Validate audience defined in OIDC
Note right of Cloud: Validate conditional (sub, aud) role
Note right of Cloud: Generate credential or fetch secret
Cloud->>GitLab: Return temporary credential
Note left of GitLab: Perform operation</code></pre></details></div>



클라우드에서 OIDC ID 공급자를 만듭니다(예: AWS, Azure, GCP, Vault).


그룹, 프로젝트, 브랜치 또는 태그로 필터링하는 클라우드 서비스에 조건부 역할을 만듭니다.


CI/CD job에는 JWT 토큰인 ID 토큰이 포함됩니다. 이 토큰을 클라우드 API와의 권한 부여에 사용할 수 있습니다.


클라우드는 토큰을 확인하고 페이로드에서 조건부 역할을 검증하여 임시 자격 증명을 반환합니다.


OIDC 클레임으로 조건부 역할 구성#
조건부 역할을 구성할 때 클라우드 공급자가 지원하는 경우 sub와 같은 경로 기반 클레임과 함께 namespace_id 또는 project_id와 같은 안정적이고 고유한 식별자를 포함하세요. 이러한 식별자는 경로와 독립적이므로 이를 참조하는 신뢰 정책은 그룹이나 프로젝트 이름 변경과 같은 경로 변경에 영향을 받지 않습니다.
이러한 조건 키에 대한 지원은 클라우드 공급자와 GitLab 오퍼링에 따라 다릅니다. 예를 들어 AWS는 gitlab.com OIDC ID 공급자에 대해서만 namespace_id 및 project_id를 지원합니다. 공급자 예시는 AWS에서 OpenID Connect 구성을 참조하세요.
GitLab과 OIDC 간의 신뢰를 구성하려면 JWT에 대해 확인하는 클라우드 공급자에 조건부 역할을 만들어야 합니다.
조건은 JWT에 대해 검증되어 대상(audience)과 주체(subject)의 두 클레임에 대한 신뢰를 구체적으로 만듭니다.

대상(audience) 또는 aud: ID 토큰의 일부로 구성됩니다:

job_needing_oidc_auth:
  id_tokens:
    OIDC_TOKEN:
      aud: https://oidc.provider.com
  script:
    - echo $OIDC_TOKEN


주체(subject) 또는 sub: 그룹, 프로젝트, 브랜치 및 태그를 포함하는 GitLab CI/CD 워크플로를 설명하는 메타데이터의 연결입니다. sub 필드는 기본적으로 다음 형식입니다:

project_path:{group}/{project}:ref_type:{type}:ref:{branch_name}



필터 유형
예시




모든 브랜치로 필터링
와일드카드 지원. project_path:mygroup/myproject:ref_type:branch:ref:*


특정 프로젝트, main 브랜치로 필터링
project_path:mygroup/myproject:ref_type:branch:ref:main


그룹 아래의 모든 프로젝트로 필터링
와일드카드 지원. project_path:mygroup/*:ref_type:branch:ref:main


Git 태그로 필터링
와일드카드 지원. project_path:mygroup/*:ref_type:tag:ref:1.0



주체로 프로젝트 ID 사용#
클라우드 신뢰 정책을 변경 불가능한 식별자에 바인딩하려면 sub 클레임의 첫 번째 구성 요소로 project_id를 사용하세요.
프로젝트 이름을 변경하거나 이동하더라도 클라우드 액세스가 안정적으로 유지되도록 이 옵션을 사용하세요.
이를 활성화하려면 프로젝트 API 엔드포인트 API를 사용하여 ci_id_token_sub_claim_components를
["project_id", "ref_type", "ref"]와 유사한 값으로 설정하세요.
그러면 sub 필드의 형식이 다음과 같아집니다:

project_id:{id}:ref_type:{type}:ref:{branch_name}

클라우드 공급자로 OIDC 권한 부여#
클라우드 공급자와 연결하려면 다음 튜토리얼을 참조하세요:


AWS에서 OpenID Connect 구성


Azure에서 OpenID Connect 구성


Google Cloud에서 OpenID Connect 구성