GitLab 토큰 문제 해결
GitLab v19.3Offering: GitLab Self-Managed, GitLab Dedicated
요약
GitLab 토큰 작업 중 다음과 같은 문제가 발생할 수 있습니다. 활성으로 표시된 토큰도 401 Unauthorized, 403 Forbidden 또는 404 Not Found 응답을 반환할 수 있습니다. 토큰의 권한은 스코프와 역할에 따라 달라집니다.
GitLab 토큰 작업 중 다음과 같은 문제가 발생할 수 있습니다.
토큰이 활성 상태로 보이지만 요청이 실패함#
활성으로 표시된 토큰도 401 Unauthorized, 403 Forbidden 또는 404 Not Found 응답을 반환할 수 있습니다.
활성 상태는 토큰이 존재하며 만료되거나 취소되지 않았다는 것만 나타냅니다.
이 상태가 토큰으로 특정 요청을 할 수 있다는 의미는 아닙니다.
토큰의 권한은 스코프와 역할에 따라 달라집니다. 요청은 토큰 외적인 이유로도 실패할 수 있습니다.
요청이 어디에서 오는지, 요청이 어떤 리소스를 대상으로 하는지, 관리자가 액세스 토큰을 껐는지 등입니다.
이러한 요소는 토큰 자체로는 알 수 없습니다. 개인, 프로젝트, 그룹 액세스 토큰은 모두 동일한 glpat- 접두사를 사용합니다.
따라서 동일해 보이는 두 토큰이 서로 다르게 동작할 수 있습니다.
활성 토큰은 다음과 같은 이유로 실패할 수 있습니다:
| 원인 | 해결 방법 |
|---|---|
| 요청에 필요한 스코프가 토큰에 없습니다. | 필요한 액세스 토큰 스코프를 가진 토큰을 만드세요. 교체는 원래 스코프를 유지하며 없는 스코프를 추가할 수 없습니다. |
| 그룹 또는 프로젝트 액세스 토큰에 필요한 역할이 없습니다. | 더 높은 역할의 토큰을 만드세요. 토큰의 권한은 역할과 스코프 모두에 의해 제한됩니다. |
| 토큰이 만료되었습니다. | 액세스 토큰은 만료 날짜의 UTC 자정에 만료됩니다. 토큰을 만든 다음 이전 토큰을 사용하던 모든 위치를 업데이트하세요. |
| 토큰이 취소되었거나, 교체되었지만 원래 값이 계속 사용되고 있습니다. | 교체하면 원래 토큰은 즉시 비활성화됩니다. 교체로 생성된 토큰을 사용하거나 토큰을 새로 만드세요. GitLab Self-Managed 및 GitLab Dedicated에서는 관리자가 실수로 취소된 개인 액세스 토큰을 복원할 수 있습니다. |
| 해당 토큰 유형으로는 리소스에 액세스할 수 없습니다. | 리소스에 액세스할 수 있는 토큰 유형을 사용하세요. 개인 액세스 토큰은 해당 사용자가 사용할 수 있는 그룹과 프로젝트에 액세스합니다. 그룹 액세스 토큰은 해당 그룹의 하위 그룹과 프로젝트에 액세스합니다. 프로젝트 액세스 토큰은 자신의 프로젝트에만 액세스합니다. |
| IP 주소 제한이 요청을 차단합니다. | 이 제한은 그룹 및 프로젝트 액세스 토큰에 적용되며, 차단된 요청은 404 Not Found를 반환합니다. 허용된 주소에서 요청을 보내거나, 최상위 그룹의 Owner 역할을 가진 사용자에게 해당 주소를 허용 범위에 추가하도록 요청하세요. |
| 외부 인가가 켜져 있습니다. | 개인 및 프로젝트 액세스 토큰은 컨테이너 레지스트리나 패키지 레지스트리에 액세스할 수 없습니다. 레지스트리에 대한 액세스를 복원하려면 외부 인가를 끄세요. |
| 관리자가 인스턴스의 액세스 토큰을 껐습니다. | 관리자 또는 Owner 역할을 가진 사용자에게 액세스 토큰을 다시 켜도록 요청하세요. |
어떤 원인이 적용되는지 확인하려면 실패한 토큰의 세부 정보를 정상 동작하는 토큰과 비교하세요:
세부 정보에는 각 토큰의 스코프, 만료 날짜 및 사용 정보가 포함됩니다. 그룹 및 프로젝트 액세스 토큰에는 할당된 역할도 표시됩니다.
요청을 보낸 후에도 토큰의 사용 정보가 업데이트되지 않으면 요청이 GitLab에 도달하지 않았을 수 있습니다. GitLab은 사용 시간을 10분마다, 사용 IP 주소를 1분마다 업데이트합니다. 해당 간격이 지난 후에도 GitLab이 사용을 기록하지 않는다면 요청이 GitLab에 도달하지 않은 것입니다.
편집기 확장 프로그램이나 명령줄 도구에서 토큰이 작동하지 않음#
GitLab UI나 API에서 인증되는 토큰도 편집기 확장 프로그램이나 명령줄 도구에서는 실패할 수 있습니다. 필요한 스코프는 도구마다 다릅니다.
유효한 토큰이 도구에서 실패하는 이유는 다음과 같습니다:
| 원인 | 해결 방법 |
|---|---|
| 토큰에 다른 스코프가 필요합니다. | 도구에 필요한 스코프와 토큰에 추가된 스코프를 비교하세요. 필요한 스코프를 가진 토큰을 만드세요. 교체는 원래 스코프를 유지하며 없는 스코프를 추가할 수 없습니다. |
| 도구가 올바른 토큰을 사용하고 있지 않습니다. | 도구가 어떤 토큰으로 인증하는지 확인한 다음, 잘못된 토큰을 업데이트하거나 제거하세요. VS Code용 GitLab 확장 프로그램은 해당 인스턴스에 대해 구성된 토큰이 없을 때만 GITLAB_WORKFLOW_TOKEN 환경 변수의 토큰을 사용합니다. 이 변수는 VS Code 스토리지를 삭제한 후에도 유지됩니다. 이를 재정의하려면 확장 프로그램에서 해당 인스턴스에 대한 토큰을 구성하세요. |
| 도구가 GitLab에 연결할 수 없습니다. | 토큰에 필요한 스코프가 있고 도구가 이를 사용하고 있다면, 네트워크에서 도구가 GitLab에 도달할 수 있는지 확인하세요. VS Code용 GitLab 확장 프로그램의 경우 인증 문제 해결을 참조하세요. |
만료된 액세스 토큰#
기존 액세스 토큰이 사용 중이고 expires_at 값에 도달하면, 토큰이 만료되고:
- 더 이상 인증에 사용할 수 없습니다.
- UI에서 표시되지 않습니다.
이 토큰을 사용하여 만든 요청은 401 Unauthorized 응답을 반환합니다. 동일한 IP 주소에서 짧은 시간 내에 너무 많은 승인되지 않은 요청이 발생하면 GitLab.com에서 403 Forbidden 응답이 반환됩니다.
인증 요청 제한에 대한 자세한 내용은 Git 및 컨테이너 레지스트리 인증 실패 금지를 참조하세요.
로그에서 만료된 액세스 토큰 식별#
히스토리
- GitLab 17.2에서 도입되었습니다.
사전 요구 사항:
다음이 필요합니다:
- 관리자여야 합니다.
api_json.log파일에 액세스할 수 있어야 합니다.
만료된 액세스 토큰으로 인해 어떤 401 Unauthorized 요청이 실패하는지 식별하려면 api_json.log 파일의 다음 필드를 사용합니다:
| 필드 이름 | 설명 |
|---|---|
meta.auth_fail_reason |
요청이 거부된 이유. 가능한 값: token_expired, token_revoked, insufficient_scope, impersonation_disabled. |
meta.auth_fail_token_id |
시도된 토큰의 유형 및 ID를 설명하는 문자열. |
meta.auth_fail_requested_scopes |
요청에 필요했던 OAuth 스코프. 공백으로 구분됩니다. |
meta.auth_fail_token_type |
사용된 토큰의 유형. 가능한 값: PersonalAccessToken, CiJobToken, unknown. |
meta.auth_fail_auth_header_type |
요청에서 토큰이 전달된 방식. 가능한 값: private_token_header, private_token_param, bearer, other. |
사용자가 만료된 토큰을 사용하려고 하면 meta.auth_fail_reason이 token_expired가 됩니다. 다음은 로그 항목의 발췌문입니다:
{
"status": 401,
"method": "GET",
"path": "/api/v4/user",
...
"meta.auth_fail_reason": "token_expired",
"meta.auth_fail_token_id": "PersonalAccessToken/12",
}
경우에 따라 meta.auth_fail_* 필드가 401이 아닌 응답에도 나타날 수 있습니다. 알려진 사례는 다음과 같습니다:
- 공개 프로젝트에 대한 Git HTTP 요청. 이 경우 Rack::Attack이 토큰 실패를 기록하지만 프로젝트의 공개 가시성 덕분에 요청은 성공합니다.
- Unleash 기능 플래그 엔드포인트. 토큰이 아닌
HTTP_UNLEASH_INSTANCEID로 인가합니다. - Workhorse 사전 인가(
/authorize) 엔드포인트. 토큰 확인 이후에 자체 인가를 수행합니다.
meta.auth_fail_token_id는 ID 12의 액세스 토큰이 사용되었음을 나타냅니다.
GitLab 18.9부터 meta.user에도 실패한 요청에 사용된 토큰과 관련된 사용자 이름이 채워집니다.
이 토큰에 대한 자세한 정보를 찾으려면 개인 액세스 토큰 API를 사용합니다. API를 사용하여 토큰을 교체할 수도 있습니다.
만료된 액세스 토큰 교체#
토큰을 교체하려면:
- 이전에 이 토큰이 사용된 위치를 확인하고 여전히 토큰을 사용하는 자동화에서 제거합니다.
- 개인 액세스 토큰의 경우, API를 사용하여 최근에 만료된 토큰을 나열합니다. 예를 들어,
https://gitlab.com/api/v4/personal_access_tokens로 이동하여 특정expires_at날짜가 있는 토큰을 찾습니다. - 프로젝트 액세스 토큰의 경우, 프로젝트 액세스 토큰 API를 사용하여 최근에 만료된 토큰을 나열합니다.
- 그룹 액세스 토큰의 경우, 그룹 액세스 토큰 API를 사용하여 최근에 만료된 토큰을 나열합니다.
- 개인 액세스 토큰의 경우, API를 사용하여 최근에 만료된 토큰을 나열합니다. 예를 들어,
- 새 액세스 토큰을 만듭니다:
- 개인 액세스 토큰의 경우, UI 사용 또는 사용자 토큰 API.
- 프로젝트 액세스 토큰의 경우, UI 사용 또는 프로젝트 액세스 토큰 API.
- 그룹 액세스 토큰의 경우, UI 사용 또는 그룹 액세스 토큰 API.
- 이전 액세스 토큰을 새 액세스 토큰으로 교체합니다. 이 프로세스는 예를 들어 시크릿으로 구성되거나 애플리케이션에 내장된 방식 등 토큰 사용 방법에 따라 달라집니다. 이 토큰에서 만들어진 요청은 더 이상
401응답을 반환하지 않아야 합니다.
개인 액세스 토큰 복원#
GitLab Self-Managed 또는 GitLab Dedicated 인스턴스에서 관리자는 실수로 취소된 개인 액세스 토큰을 복원할 수 있습니다. GitLab.com에서는 복원이 제공되지 않습니다.
다음 명령을 실행하면 데이터가 직접 변경됩니다. 올바르게 또는 올바른 조건에서 수행되지 않으면 손상될 수 있습니다. 먼저 테스트 환경에서 이러한 명령을 실행하고, 만일을 대비하여 인스턴스의 백업을 복원할 준비를 해야 합니다.
-
Rails 콘솔을 엽니다.
-
토큰을 복원합니다:
token = PersonalAccessToken.find_by_token('<token_string>') token.update!(revoked:false)예를 들어,
token-string-here123의 토큰을 복원하려면:token = PersonalAccessToken.find_by_token('token-string-here123') token.update!(revoked:false)
업그레이드 후 예기치 않게 만료되는 토큰#
만료 날짜가 없는 액세스 토큰은 무기한 유효하며, 토큰이 유출될 경우 보안 위험이 됩니다.
GitLab 버전 및 제품에 따라 업그레이드 시 기존 액세스 토큰에 만료 날짜가 자동으로 적용될 수 있습니다. 자세한 내용은 만료되지 않는 액세스 토큰을 참조하세요. 이러한 날짜가 변경된 것을 인지하지 못하면 경고 없이 인증이 실패할 수 있습니다.
GitLab 17.3 이상에서는 GitLab이 기존 토큰에 만료 날짜를 자동으로 설정하지 않습니다. 관리자는 새 액세스 토큰에 대한 만료 날짜 적용을 끌 수도 있습니다.
토큰 만료 날짜를 분석, 연장 또는 제거하려면 액세스 토큰 Rake 작업을 사용하세요.