OAuth 2.0 식별 공급자 API

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

GitLab은 OAuth 2.0 프로토콜을 사용하여 제3자 서비스가 사용자를 대신하여 GitLab 리소스에 액세스할 수 있는 API를 제공합니다.

이를 구성하려면 GitLab을 OAuth 2.0 인증 식별 공급자로 구성을 참조하십시오.

이 기능은 doorkeeper Ruby gem에 기반합니다.

GitLab 15.1에서 도입된 CORS 사전 검사 요청 지원

많은 /oauth 엔드포인트가 Cross-origin resource sharing (CORS)을 지원합니다. GitLab 15.1부터 다음 엔드포인트도 CORS 사전 검사 요청을 지원합니다:

/oauth/revoke
/oauth/token
/oauth/userinfo

사전 검사 요청에는 특정 헤더만 사용할 수 있습니다:

단순 요청에 나열된 헤더
Authorization 헤더

예를 들어, X-Requested-With 헤더는 사전 검사 요청에 사용할 수 없습니다.

지원되는 OAuth 2.0 플로우

GitLab은 다음과 같은 인가 플로우를 지원합니다:

Proof Key for Code Exchange (PKCE)를 사용하는 인가 코드: 가장 안전합니다. PKCE를 사용하지 않으면 모바일 클라이언트에서 클라이언트 비밀을 포함해야 하며, 클라이언트 및 서버 앱 모두에게 권장됩니다.
인가 코드: 안전하고 일반적인 플로우입니다. 안전한 서버 앱의 권장 옵션입니다.
리소스 소유자 암호 자격 증명: 안전하게 호스팅된 1급 서비스에서 만 사용됩니다. GitLab은 이 플로우 사용을 권장하지 않습니다.

장치 인가 그랜트는 지원되지 않습니다. 이슈 332682에서 지원 추가가 제안되었습니다.

OAuth 2.1의 초안 명세는 명시적 그랜트 및 리소스 소유자 암호 자격 증명 플로우를 특별히 제외합니다.

모든 이러한 플로우가 어떻게 작동하며 사용 사례에 맞는 올바른 것을 선택하려면 OAuth RFC를 참조하십시오.

인가 코드(PKCE 사용 유무에 관계없이) 플로우에는 먼저 /user_settings/applications 페이지에서 application을 등록해야 합니다. 등록할 때 적절한 범위를 활성화하여 application이 액세스할 수 있는 리소스 범위를 제한할 수 있습니다. 생성되면 application 자격 증명인 Application ID 및 Client Secret_을 얻게 됩니다. _Client Secret_는 반드시 안전하게 보관해야 합니다. 애플리케이션 아키텍처가 허용하는 경우 _Application ID 비밀도 유지하는 것이 유리합니다.

GitLab 범위 디렉터리에 대한 자세한 내용은 공급자 문서를 참조하십시오.

CSRF 공격 방지

리디렉트 기반 플로우를 보호하려면 OAuth 명세에서는 “사용자 에이전트에 안전하게 바인딩된 상태 매개변수에 포함된 일회용 CSRF 토큰의 사용”을 권장합니다. 이렇게 함으로써 CSRF 공격을 방지할 수 있습니다.

프로덕션에서 HTTPS 사용

프로덕션에는 redirect_uri에 HTTPS를 사용하십시오. 개발 중에는 GitLab이 보안되지 않은 HTTP 리디렉트 URI를 허용합니다.

OAuth 2.0은 보안을 전적으로 전송 계층에 의존하기 때문에 보호되지 않은 URI를 사용해서는 안됩니다. 자세한 내용은 OAuth 2.0 RFC 및 OAuth 2.0 Threat Model RFC을 참조하십시오.

다음 섹션에서 각 플로우로 인가를 얻는 방법에 대해 자세히 설명되어 있습니다.

Proof Key for Code Exchange (PKCE)를 사용하는 인가 코드

PKCE RFC에는 인가 요청부터 액세스 토큰까지 자세한 플로우 설명이 포함되어 있습니다. 다음 단계에서는 해당 플로우의 구현을 설명합니다.

인가 코드와 PKCE 플로우 덕분에 클라이언트 시크릿에 전혀 액세스할 필요 없이 공개 클라이언트에서 클라이언트 자격 증명을 안전하게 액세스 토큰으로 교환할 수 있습니다. 따라서 PKCE 플로우는 사용자에게 비밀을 숨길 수 없는 단일 페이지 JavaScript 애플리케이션 또는 다른 클라이언트 측 앱에서 유리합니다.

플로우를 시작하기 전에 STATE, CODE_VERIFIER, CODE_CHALLENGE를 생성합니다.

STATE는 클라이언트가 요청과 콜백 사이의 상태를 유지하기 위해 사용되는 예측할 수 없는 값입니다. 또한 CSRF 토큰으로 사용되어야 합니다.
CODE_VERIFIER는 43자에서 128자까지의 무작위 문자열이며 A-Z, a-z, 0-9, -, ., _, 및 ~ 문자를 사용합니다.
CODE_CHALLENGE는 CODE_VERIFIER의 SHA256 해시의 URL 안전한 base64 인코딩 문자열입니다.
- SHA256 해시는 인코딩하기 전에 이진 형식이어야 합니다.
- Ruby에서는 Base64.urlsafe_encode64(Digest::SHA256.digest(CODE_VERIFIER), padding: false)로 설정할 수 있습니다.
- 참고로, Ruby 스니펫을 사용하여 CODE_VERIFIER 문자열이 위에서 제시된 방법으로 해싱 및 인코딩된 경우 CODE_CHALLENGE 문자열은 2i0WFA-0AerkjQm4X4oDEhqA17QIAKNjXpagHBXmO_U가 됩니다.

인가 코드를 요청합니다. 이를 위해 다음 쿼리 매개변수를 사용하여 사용자를 /oauth/authorize 페이지로 리디렉션해야 합니다:
```
https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=code&state=STATE&scope=REQUESTED_SCOPES&code_challenge=CODE_CHALLENGE&code_challenge_method=S256
```
이 페이지에서 사용자는 REQUESTED_SCOPES에 지정된 범위에 따라 계정에 대한 앱의 요청을 승인하도록 요청됩니다. 그런 다음 사용자는 지정된 REDIRECT_URI로 다시 리디렉션됩니다. scope 매개변수는 사용자와 연결된 범위의 공백으로 구분된 디렉터리입니다. 예를 들어, scope=read_user+profile은 read_user 및 profile 범위를 요청합니다. 리디렉트에는 인가 코드가 포함됩니다. 예를 들어:
```
https://example.com/oauth/redirect?code=1234567890&state=STATE
```

이전 요청에서 반환된 인가 코드(RETURNED_CODE로 표시)를 사용하여 어떤 HTTP 클라이언트든지 access_token을 요청할 수 있습니다. 다음 예에서는 Ruby의 rest-client를 사용합니다.

parameters = 'client_id=APP_ID&code=RETURNED_CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI&code_verifier=CODE_VERIFIER'
RestClient.post 'https://gitlab.example.com/oauth/token', parameters

예시 응답:

{
 "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
 "token_type": "bearer",
 "expires_in": 7200,
 "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1",
 "created_at": 1607635748
}

새 access_token을 검색하려면 refresh_token 매개변수를 사용합니다. access_token 자체가 만료된 후에도 refresh_token을 사용할 수 있습니다. 이 요청은 다음과 같은 작업을 수행합니다:

기존 access_token 및 refresh_token을 무효화합니다.
응답에서 새 토큰을 보냅니다.

  parameters = 'client_id=APP_ID&refresh_token=REFRESH_TOKEN&grant_type=refresh_token&redirect_uri=REDIRECT_URI&code_verifier=CODE_VERIFIER'
  RestClient.post 'https://gitlab.example.com/oauth/token', parameters

예시 응답:

{
  "access_token": "c97d1fe52119f38c7f67f0a14db68d60caa35ddc86fd12401718b649dcfa9c68",
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token": "803c1fd487fec35562c205dac93e9d8e08f9d3652a24079d704df3039df1158f",
  "created_at": 1628711391
}

redirect_uri는 원래 인가 요청에서 사용된 redirect_uri와 일치해야 합니다.

이제 액세스 토큰으로 API에 요청할 수 있습니다.

인가 코드 플로우

상세한 플로우 설명은 RFC 사양을 확인하세요.

인가 코드 플로우는 기본적으로 PKCE를 사용한 인가 코드 플로우와 동일합니다.

플로우를 시작하기 전에 STATE를 생성하세요. 이 값은 클라이언트가 요청과 콜백 간의 상태를 유지하는 데 사용되는 예측할 수 없는 값입니다. 또한 CSRF 토큰으로 사용해야 합니다.

인가 코드를 요청합니다. 이를 위해 다음 쿼리 매개변수를 사용하여 사용자를 /oauth/authorize 페이지로 리디렉션해야 합니다.
```
https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=code&state=STATE&scope=REQUESTED_SCOPES
```
이 페이지는 사용자에게 REQUESTED_SCOPES에 지정된 범위를 기반으로 앱의 계정 액세스 요청을 승인할 것인지 묻습니다. 사용자는 지정된 REDIRECT_URI로 다시 리디렉션됩니다. 범위 매개변수는 사용자와 관련된 범위의 공백으로 구분된 디렉터리입니다. 예를 들어 scope=read_user+profile는 read_user 및 profile 범위를 요청합니다. 인가에는 인가 code가 포함됩니다.
```
https://example.com/oauth/redirect?code=1234567890&state=STATE
```

이전 요청에서 반환된 인가 code (다음 예제에서 RETURNED_CODE로 표시됨)를 사용하여 access_token을 요청할 수 있습니다. 아래 예제는 Ruby의 rest-client를 사용합니다.

parameters = 'client_id=APP_ID&client_secret=APP_SECRET&code=RETURNED_CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI'
RestClient.post 'https://gitlab.example.com/oauth/token', parameters

예시 응답:

{
 "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
 "token_type": "bearer",
 "expires_in": 7200,
 "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1",
 "created_at": 1607635748
}

새 access_token을 검색하려면 refresh_token 매개변수를 사용하세요. access_token 자체가 만료된 후에도 refresh_token을 사용할 수 있습니다. 이 요청은 다음과 같은 작업을 수행합니다:

기존 access_token과 refresh_token을 무효화합니다.
응답에서 새 토큰을 보냅니다.

  parameters = 'client_id=APP_ID&client_secret=APP_SECRET&refresh_token=REFRESH_TOKEN&grant_type=refresh_token&redirect_uri=REDIRECT_URI'
  RestClient.post 'https://gitlab.example.com/oauth/token', parameters

예시 응답:

{
  "access_token": "c97d1fe52119f38c7f67f0a14db68d60caa35ddc86fd12401718b649dcfa9c68",
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token": "803c1fd487fec35562c205dac93e9d8e08f9d3652a24079d704df3039df1158f",
  "created_at": 1628711391
}

redirect_uri는 원래 인가 요청에서 사용된 redirect_uri와 일치해야 합니다.

이제 반환된 액세스 토큰으로 API에 요청을 보낼 수 있습니다.

리소스 소유자 패스워드 자격 증명 플로우

상세한 플로우 설명은 RFC 사양을 확인하세요.

리소스 소유자 패스워드 자격 증명은 이중 인증을 사용하는 사용자에게는 비활성화되어 있습니다. 이러한 사용자는 개인 액세스 토큰을 사용하여 API에 액세스할 수 있습니다.

이 플로우에서는 리소스 소유자 자격 증명(사용자 이름 및 패스워드)와 교환하여 토큰이 요청됩니다.

이 자격 증명은 다음 경우에만 사용해야 합니다:

리소스 소유자와 클라이언트 간에 높은 신뢰가 있을 때. 예를 들어 클라이언트가 장치 운영 체제의 일부이거나 권한이 높은 애플리케이션입니다.
다른 인가 부여 유형을 사용할 수 없는 경우(예: 인가 코드).

사용자의 자격 증명을 저장하거나 클라이언트가 신뢰할 수 있는 환경에 배포되었을 때에만 이 인가 유형을 사용하고, 99%의 경우에는 개인 액세스 토큰을 더 좋은 선택으로 고려해야 합니다.

이 인가 유형은 리소스 소유자 자격 증명에 직접적으로 클라이언트 액세스가 필요하지만, 리소스 소유자 자격 증명은 단일 요청에 사용되어 액세스 토큰과 교환됩니다. 이 인가 유형을 사용하면 클라이언트가 리소스 소유자 자격 증명을 장기적으로 사용할 수 있는 액세스 토큰이나 리프레시 토큰과 교환함으로써 리소스 소유자 자격 증명을 미래에 사용하기 위해 저장할 필요가 없어질 수 있습니다.

액세스 토큰을 요청하려면 다음 매개변수를 사용하여 /oauth/token에 POST 요청을 보내어야 합니다:

{
  "grant_type"    : "password",
  "username"      : "user@example.com",
  "password"      : "secret"
}

예시 cURL 요청:

echo 'grant_type=password&username=<your_username>&password=<your_password>' > auth.txt
curl --data "@auth.txt" --request POST "https://gitlab.example.com/oauth/token"

등록된 OAuth 애플리케이션을 사용하여 이 인가 플로우를 사용하려면, 애플리케이션의 client_id와 client_secret을 사용하여 HTTP 기본 인증을 사용하세요.

echo 'grant_type=password&username=<your_username>&password=<your_password>' > auth.txt
curl --data "@auth.txt" --user client_id:client_secret \
     --request POST "https://gitlab.example.com/oauth/token"

그럼, 액세스 토큰이 포함된 응답을 받게 됩니다:

{
  "access_token": "1f0af717251950dbd4d73154fdf0a474a5c5119adad999683f5b450c460726aa",
  "token_type": "bearer",
  "expires_in": 7200
}

기본적으로 액세스 토큰의 범위는 api로, 완전한 읽기/쓰기 액세스를 제공합니다.

테스트를 위해, oauth2 Ruby gem을 사용할 수 있습니다:

client = OAuth2::Client.new('the_client_id', 'the_client_secret', :site => "https://example.com")
access_token = client.password.get_token('user@example.com', 'secret')
puts access_token.token

`access token`을 사용하여 GitLab API에 액세스

access token을 사용하면 사용자를 대신하여 API에 요청을 보낼 수 있습니다. 토큰을 GET 매개변수로 전달할 수도 있습니다.

GET https://gitlab.example.com/api/v4/user?access_token=OAUTH-TOKEN

또는 Authorization 헤더에 토큰을 넣을 수도 있습니다.

curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/api/v4/user"

`access token`을 사용하여 HTTPS를 통한 Git에 액세스

read_repository 또는 write_repository 스코프를 갖는 토큰은 HTTPS를 통해 Git에 액세스할 수 있습니다. 이때 토큰을 비밀번호로 사용합니다. 사용자 이름은 꼭 oauth2 여야 합니다. 개인 사용자 이름이 아닙니다.

https://oauth2:<your_access_token>@gitlab.example.com/project_path/project_name.git

또는 Git 자격 증명 도우미를 사용하여 OAuth로 GitLab에 인증할 수도 있습니다. 이는 OAuth 토큰 갱신을 자동으로 처리합니다.

토큰 정보 검색

토큰의 세부 정보를 확인하려면 Doorkeeper gem에서 제공하는 token/info 엔드포인트를 사용합니다. 자세한 정보는 다음을 참조하세요. /oauth/token/info.

액세스 토큰을 다음 중 하나로 제공해야 합니다:

매개변수로:

 GET https://gitlab.example.com/oauth/token/info?access_token=<OAUTH-TOKEN>

Authorization 헤더에:

 curl --header "Authorization: Bearer <OAUTH-TOKEN>" "https://gitlab.example.com/oauth/token/info"

다음은 예시 응답입니다:

{
    "resource_owner_id": 1,
    "scope": ["api"],
    "expires_in": null,
    "application": {"uid": "1cb242f495280beb4291e64bee2a17f330902e499882fe8e1e2aa875519cab33"},
    "created_at": 1575890427
}

사용되지 않는 필드

응답에는 scopes 필드와 expires_in_seconds 필드가 포함되어 있지만 현재는 사용되지 않습니다. scopes 필드는 scope의 별칭이고, expires_in_seconds 필드는 expires_in의 별칭입니다. 자세한 내용은 Doorkeeper API 변경사항을 참조하세요.

토큰 취소

토큰을 취소하려면 revoke 엔드포인트를 사용합니다. API는 성공을 나타내기 위해 200 응답 코드와 빈 JSON 해시를 반환합니다.

parameters = 'client_id=APP_ID&client_secret=APP_SECRET&token=TOKEN'
RestClient.post 'https://gitlab.example.com/oauth/revoke', parameters

OAuth 2.0 토큰과 GitLab 레지스트리

표준 OAuth 2.0 토큰은 다음과 같은 방법으로 다양한 수준의 GitLab 레지스트리 액세스를 지원합니다.

사용자를 위해 다음에 대한 인증을 허용하지 않습니다:
- GitLab 컨테이너 레지스트리.
- GitLab 패키지 레지스트리에 나열된 패키지.
컨테이너 레지스트리 API를 통해 레지스트리를 가져오고 나열하며 삭제할 수 있습니다.

OAuth 2.0 식별 공급자 API

지원되는 OAuth 2.0 플로우

CSRF 공격 방지

프로덕션에서 HTTPS 사용

Proof Key for Code Exchange (PKCE)를 사용하는 인가 코드

인가 코드 플로우

리소스 소유자 패스워드 자격 증명 플로우

`access token`을 사용하여 GitLab API에 액세스

`access token`을 사용하여 HTTPS를 통한 Git에 액세스

토큰 정보 검색

사용되지 않는 필드

토큰 취소

OAuth 2.0 토큰과 GitLab 레지스트리

도움말

기능 사용 가능성과 제품 평가판

도움받기

OAuth 2.0 식별 공급자 API

Cross-origin resource sharing

지원되는 OAuth 2.0 플로우

CSRF 공격 방지

프로덕션에서 HTTPS 사용

Proof Key for Code Exchange (PKCE)를 사용하는 인가 코드

인가 코드 플로우

리소스 소유자 패스워드 자격 증명 플로우

access token을 사용하여 GitLab API에 액세스

access token을 사용하여 HTTPS를 통한 Git에 액세스

토큰 정보 검색

사용되지 않는 필드

토큰 취소

OAuth 2.0 토큰과 GitLab 레지스트리

도움말

기능 사용 가능성과 제품 평가판

도움받기

`access token`을 사용하여 GitLab API에 액세스

`access token`을 사용하여 HTTPS를 통한 Git에 액세스