GitLab 토큰을 사용할 때 다음과 같은 문제가 발생할 수 있습니다.

토큰이 활성 상태로 보이지만 요청이 실패하는 경우#

활성 상태로 표시된 토큰도 401 Unauthorized, 403 Forbidden, 또는 404 Not Found 응답을 반환할 수 있습니다. 활성 상태는 토큰이 존재하며 만료되거나 취소되지 않았음을 나타낼 뿐입니다. 이 상태가 토큰이 특정 요청을 수행할 수 있음을 의미하지는 않습니다. 토큰이 만료되었거나 취소된 경우에는 토큰이 만료된 후 요청이 실패하는 경우를 대신 참고합니다.

토큰의 권한은 스코프와 역할에 따라 달라집니다. 요청은 토큰 자체와 무관한 이유로도 실패할 수 있습니다. 요청이 어디에서 왔는지, 요청이 대상으로 하는 리소스, 관리자가 액세스 토큰을 비활성화했는지 여부 등이 그 예입니다. 이러한 요인 중 어느 것도 토큰 자체에서는 드러나지 않습니다. 개인, 프로젝트, 그룹 액세스 토큰은 모두 동일한 glpat- 접두사를 사용합니다. 따라서 동일해 보이는 두 토큰이 서로 다르게 동작할 수 있습니다.

활성 토큰은 다음과 같은 이유로 실패할 수 있습니다.

어떤 원인에 해당하는지 확인하려면 실패한 토큰의 세부 정보를 정상 동작하는 토큰과 비교합니다.

• 개인 액세스 토큰
• 그룹 액세스 토큰
• 프로젝트 액세스 토큰

세부 정보에는 각 토큰의 스코프, 만료일, 사용 정보가 포함됩니다. 그룹 및 프로젝트 액세스 토큰은 할당된 역할도 표시합니다.

요청을 보낸 후에도 토큰의 사용 정보가 업데이트되지 않는다면 요청이 GitLab에 도달하지 못했을 수 있습니다. GitLab은 사용 시각을 10분마다, 사용 IP 주소를 1분마다 업데이트합니다. 해당 간격이 지난 후에도 GitLab 이 사용 내역을 기록하지 않는다면 요청이 GitLab에 도달하지 않은 것입니다.

에디터 확장 프로그램이나 명령줄 도구에서 토큰이 동작하지 않는 경우#

GitLab UI 나 API에서 인증되는 토큰도 에디터 확장 프로그램이나 명령줄 도구에서는 실패할 수 있습니다. 스코프 요구 사항은 도구마다 다릅니다.

유효한 토큰도 다음과 같은 이유로 도구에서 실패할 수 있습니다.

토큰이 만료된 후 요청이 실패하는 경우#

사용 중인 기존 액세스 토큰이 expires_at 값에 도달하면 토큰이 만료되며 다음과 같이 됩니다.

• 더 이상 인증에 사용할 수 없습니다.
• UI에 표시되지 않습니다.

이 토큰을 사용한 요청은 401 Unauthorized 응답을 반환합니다. 동일한 IP 주소에서 짧은 시간 내에 너무 많은 인증되지 않은 요청이 발생하면 GitLab.com에서 403 Forbidden 응답이 반환됩니다.

인증 요청 제한에 대한 자세한 내용은 Git 및 컨테이너 레지스트리 인증 실패 차단을 참고합니다.

로그에서 만료된 액세스 토큰 확인하기#

사전 요구 사항:

다음을 완료해야 합니다.

• 관리자여야 합니다.
• api_json.log 파일에 액세스할 수 있어야 합니다.

만료된 액세스 토큰으로 인해 실패하는 401 Unauthorized 요청을 확인하려면 api_json.log 파일의 다음 필드를 사용합니다.

사용자가 만료된 토큰을 사용하려고 하면 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_token_id는 ID가 12 인 액세스 토큰이 사용되었음을 나타냅니다. GitLab 18.9 이상에서는 실패한 요청에 사용된 토큰과 연결된 사용자 이름이 있는 경우 meta.user에도 채워집니다.

이 토큰에 대한 자세한 정보를 확인하려면 개인 액세스 토큰 API를 사용합니다. API를 사용해 토큰을 로테이션할 수도 있습니다.

만료된 액세스 토큰 교체하기#

토큰을 교체하려면 다음과 같이 진행합니다.

1. 이 토큰이 이전에 어디에서 사용되었는지 확인하고, 여전히 이 토큰을 사용할 수 있는 자동화 작업에서 제거합니다.
   • 개인 액세스 토큰의 경우 API를 사용해 최근 만료된 토큰 목록을 확인합니다. 예를 들어 https://gitlab.com/api/v4/personal_access_tokens로 이동해 특정 expires_at 날짜를 가진 토큰을 찾습니다.
   • 프로젝트 액세스 토큰의 경우 프로젝트 액세스 토큰 API를 사용해 최근 만료된 토큰 목록을 확인합니다.
   • 그룹 액세스 토큰의 경우 그룹 액세스 토큰 API를 사용해 최근 만료된 토큰 목록을 확인합니다.
2. 새 액세스 토큰을 생성합니다.
   • 개인 액세스 토큰의 경우 UI를 사용하거나 사용자 토큰 API를 사용합니다.
   • 프로젝트 액세스 토큰의 경우 UI를 사용하거나 프로젝트 액세스 토큰 API를 사용합니다.
   • 그룹 액세스 토큰의 경우 UI를 사용하거나 그룹 액세스 토큰 API를 사용합니다.
3. 기존 액세스 토큰을 새 액세스 토큰으로 교체합니다. 이 과정은 토큰을 어떻게 사용하는지에 따라 달라집니다. 예를 들어 시크릿으로 구성되었는지, 애플리케이션에 내장되었는지에 따라 다릅니다. 새 토큰을 사용하는 요청은 더 이상 401 응답을 반환하지 않습니다.

개인 액세스 토큰 복원하기#

GitLab Self-Managed 또는 GitLab Dedicated 인스턴스에서는 관리자가 실수로 취소된 개인 액세스 토큰을 복원할 수 있습니다. GitLab.com에서는 복원 기능을 사용할 수 없습니다.

1. Rails 콘솔을 엽니다.

2. 토큰을 복원합니다.

   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 작업을 사용합니다.

관련 주제#

• 컨테이너 레지스트리 인증
• CI/CD job 토큰 인증
• 2단계 인증 문제 해결
• Git 문제 해결