OpenID Connect (OIDC) Authentication Using ID Tokens
- 소개된 GitLab 15.7에서 소개되었습니다.
GitLab CI/CD의 ID 토큰을 사용하여 써드파티 서비스와 인증할 수 있습니다. ID tokens을 사용하여 병합 요청을 생성하는 다양한 방법에 대해 알아보세요.
ID Tokens
ID tokens은 GitLab CI/CD 작업에 추가할 수 있는 JSON Web Tokens (JWTs)입니다. 이 토큰들은 써드파티 서비스와의 OIDC 인증에 사용되며, HashiCorp Vault와의 인증을 위해 secrets
키워드에 의해 사용됩니다.
ID 토큰은 .gitlab-ci.yml
에서 구성됩니다. 예를 들면:
job_with_id_tokens:
id_tokens:
FIRST_ID_TOKEN:
aud: https://first.service.com
SECOND_ID_TOKEN:
aud: https://second.service.com
script:
- first-service-authentication-script.sh $FIRST_ID_TOKEN
- second-service-authentication-script.sh $SECOND_ID_TOKEN
위 예제에서 두 토큰에는 서로 다른 aud
클레임이 있습니다. 써드파티 서비스는 자신의 바인딩 대상 청중과 일치하지 않는 토큰을 거부하도록 구성할 수 있습니다. 이 기능을 사용하여 토큰으로 인증할 수 있는 서비스 수를 줄이는 데 사용할 수 있습니다. 이렇게 하면 토큰이 노출될 경우 심각도가 감소합니다.
토큰 페이로드
각 ID 토큰에는 다음의 표준 클레임이 포함됩니다:
필드 | 설명 |
---|---|
iss
| 토큰의 발급자, 기본적으로 GitLab 인스턴스의 도메인입니다 (“issuer” 클레임). |
sub
|
project_path:{group}/{project}:ref_type:{type}:ref:{branch_name} (주제 클레임).
|
aud
| 토큰의 의도된 청중, 기본적으로 GitLab 인스턴스의 도메인입니다 (“audience” 클레임). ID tokens 구성에 지정됩니다. |
exp
| 만료 시간 (만료 시간 클레임). |
nbf
| 토큰이 유효해지는 시간 (“유효하지 않음” 클레임). |
iat
| JWT가 발급된 시간 (“발급 시간” 클레임). |
jti
| 토큰의 고유 식별자 (“JWT ID” 클레임). |
토큰에는 또한 GitLab에서 제공하는 사용자 정의 클레임이 포함됩니다:
필드 | 시기 | 설명 |
---|---|---|
namespace_id
| 항상 | ID별로 그룹 또는 사용자 수준의 네임스페이스에 적용합니다. |
namespace_path
| 항상 | 경로별로 그룹 또는 사용자 수준의 네임스페이스에 적용합니다. |
project_id
| 항상 | ID별로 프로젝트에 적용합니다. |
project_path
| 항상 | 경로별로 프로젝트에 적용합니다. |
user_id
| 항상 | 작업을 실행하는 사용자의 ID입니다. |
user_login
| 항상 | 작업을 실행하는 사용자의 사용자명입니다. |
user_email
| 항상 | 작업을 실행하는 사용자의 이메일 주소입니다. |
user_access_level
| 항상 | 작업을 실행하는 사용자의 액세스 수준입니다. GitLab 16.9에서 소개되었습니다. |
user_identities
| 사용자 설정 | 사용자의 외부 신원 목록입니다 (GitLab 16.0에서 소개). |
pipeline_id
| 항상 | 파이프라인의 ID입니다. |
pipeline_source
| 항상 | 파이프라인 소스입니다. |
job_id
| 항상 | 작업의 ID입니다. |
ref
| 항상 | 작업의 Git ref입니다. |
ref_type
| 항상 | Git ref 유형은 branch 또는 tag 중 하나입니다.
|
ref_path
| 항상 | 작업의 완전한 ref입니다. 예: refs/heads/main . GitLab 16.0에서 소개되었습니다.
|
ref_protected
| 항상 | Git ref가 보호되어 있는지 여부입니다. 보호되어 있다면 true 이고, 그렇지 않으면 false 입니다.
|
environment
| 작업이 환경을 지정하는 경우 | 해당 작업이 배포되는 환경입니다 (GitLab 13.9에서 소개). |
environment_protected
| 작업이 환경을 지정하는 경우 | 배포된 환경이 보호되어 있는지 여부입니다 (GitLab 13.9에서 소개). |
deployment_tier
| 작업이 환경을 지정하는 경우 | 작업이 지정하는 환경의 배포 계층입니다 (GitLab 15.2에서 소개). |
environment_action
| 작업이 환경을 지정하는 경우 | 작업에서 지정된 환경 작업 (environment:action )입니다 (GitLab 16.5에서 소개).
|
runner_id
| 항상 | 작업을 실행하는 러너의 ID입니다. GitLab 16.0에서 소개. |
runner_environment
| 항상 | 작업에 사용된 러너의 유형입니다. gitlab-hosted 또는 self-hosted 중 하나입니다. GitLab 16.0에서 소개.
|
sha
| 항상 | 작업의 커밋 SHA입니다. GitLab 16.0에서 소개. |
ci_config_ref_uri
| 항상 | 최상위 파이프라인 정의의 ref 경로입니다. 예: gitlab.example.com/my-group/my-project//.gitlab-ci.yml@refs/heads/main . GitLab 16.2에서 소개. 이 클레임은 파이프라인 정의가 동일 프로젝트에 있는 경우에만 null 입니다.
|
ci_config_sha
| 항상 |
ci_config_ref_uri 의 Git 커밋 SHA입니다. GitLab 16.2에서 소개. 이 클레임은 파이프라인 정의가 동일 프로젝트에 있는 경우에만 null 입니다.
|
project_visibility
| 항상 | 파이프라인이 실행되는 프로젝트의 가시성입니다. internal , private , 또는 public 중 하나입니다. GitLab 16.3에서 소개.
|
{
"namespace_id": "72",
"namespace_path": "my-group",
"project_id": "20",
"project_path": "my-group/my-project",
"user_id": "1",
"user_login": "sample-user",
"user_email": "sample-user@example.com",
"user_identities": [
{"provider": "github", "extern_uid": "2435223452345"},
{"provider": "bitbucket", "extern_uid": "john.smith"},
],
"pipeline_id": "574",
"pipeline_source": "push",
"job_id": "302",
"ref": "feature-branch-1",
"ref_type": "branch",
"ref_path": "refs/heads/feature-branch-1",
"ref_protected": "false",
"environment": "test-environment2",
"environment_protected": "false",
"deployment_tier": "testing",
"environment_action": "start",
"runner_id": 1,
"runner_environment": "self-hosted",
"sha": "714a629c0b401fdce83e847fc9589983fc6f46bc",
"project_visibility": "public",
"ci_config_ref_uri": "gitlab.example.com/my-group/my-project//.gitlab-ci.yml@refs/heads/main",
"ci_config_sha": "714a629c0b401fdce83e847fc9589983fc6f46bc",
"jti": "235b3a54-b797-45c7-ae9a-f72d7bc6ef5b",
"iss": "https://gitlab.example.com",
"iat": 1681395193,
"nbf": 1681395188,
"exp": 1681398793,
"sub": "project_path:my-group/my-project:ref_type:branch:ref:feature-branch-1",
"aud": "https://vault.example.com"
}
ID 토큰은 RS256을 사용하여 인코딩되며 전용 프라이빗 키로 서명됩니다. 토큰의 만료 시간은 작업의 타임아웃이 지정된 경우 해당 타임아웃으로 설정되며, 타임아웃이 지정되지 않은 경우 5분으로 설정됩니다.
수동 ID 토큰 인증
서드 파티 서비스와 OIDC 인증에 ID 토큰을 사용할 수 있습니다. 예를 들어:
manual_authentication:
variables:
VAULT_ADDR: http://vault.example.com:8200
image: vault:latest
id_tokens:
VAULT_ID_TOKEN:
aud: http://vault.example.com:8200
script:
- export VAULT_TOKEN="$(vault write -field=token auth/jwt/login role=myproject-example jwt=$VAULT_ID_TOKEN)"
- export PASSWORD="$(vault kv get -field=password secret/myproject/example/db)"
- my-authentication-script.sh $VAULT_TOKEN $PASSWORD
HashiCorp Vault를 사용한 자동 ID 토큰 인증
secrets
키워드를 사용하여 HashiCorp Vault에서 비밀을 자동으로 가져오려면 ID 토큰을 사용할 수 있습니다.
이전에 CI_JOB_JWT
를 사용하여 Vault에서 비밀을 가져오던 경우 ID 토큰 사용으로 Vault 구성 업데이트 튜토리얼을 통해 전환하는 방법을 알아보세요.
자동 ID 토큰 인증 구성
하나의 ID 토큰이 정의된 경우 secrets
키워드는 자동으로 해당 토큰을 사용하여 Vault와 인증합니다. 예를 들어:
job_with_secrets:
id_tokens:
VAULT_ID_TOKEN:
aud: https://example.vault.com
secrets:
PROD_DB_PASSWORD:
vault: example/db/password # $VAULT_ID_TOKEN을 사용하여 인증
script:
- access-prod-db.sh --token $PROD_DB_PASSWORD
여러 개의 ID 토큰이 정의된 경우 token
키워드를 사용하여 어떤 토큰을 사용할지 지정합니다. 예를 들어:
job_with_secrets:
id_tokens:
FIRST_ID_TOKEN:
aud: https://first.service.com
SECOND_ID_TOKEN:
aud: https://second.service.com
secrets:
FIRST_DB_PASSWORD:
vault: first/db/password
token: $FIRST_ID_TOKEN
SECOND_DB_PASSWORD:
vault: second/db/password
token: $SECOND_ID_TOKEN
script:
- access-first-db.sh --token $FIRST_DB_PASSWORD
- access-second-db.sh --token $SECOND_DB_PASSWORD
문제 해결
400: missing token
상태 코드
이 오류는 ID 토큰에 필요한 하나 이상의 기본 구성 요소가 없거나 예상대로 구성되지 않은 것을 나타냅니다.
문제를 찾으려면 관리자는 인스턴스의 exceptions_json.log
에서 실패한 특정 메서드에 대한 자세한 내용을 찾을 수 있습니다.
GitLab::Ci::Jwt::NoSigningKeyError
exceptions_json.log
파일의 이 오류는 서명 키가 데이터베이스에서 누락되어 토큰을 생성할 수 없기 때문입니다. 이 문제인지 확인하려면 인스턴스의 PostgreSQL 터미널에서 다음 쿼리를 실행합니다:
SELECT encrypted_ci_jwt_signing_key FROM application_settings;
반환된 값이 비어 있다면, 새 키를 생성하고 내부적으로 교체하기 위해 아래 Rails 스니펫을 사용하세요:
key = OpenSSL::PKey::RSA.new(2048).to_pem
ApplicationSetting.find_each do |application_setting|
application_setting.update(ci_jwt_signing_key: key)
end