이 페이지는 Cloud Translation API를 통해 번역되었습니다.

데이터 요금제 에이전트용 OAuth API

개요

일반적으로 서드 파티 애플리케이션이 데이터 요금제 및 지갑 세부정보와 같은 제한된 리소스에 액세스할 수 있도록 하려면 최종 사용자 (리소스 소유자)가 사용자 인증 정보를 서드 파티와 공유해야 합니다. 이로 인해 사용자 인증 정보 저장, 비밀번호 인증, 최종 사용자의 리소스에 대한 광범위한 액세스, 비밀번호 유출 등 여러 문제와 제한사항이 발생합니다. OAuth2.0은 승인 레이어를 도입하여 이러한 문제를 해결하고 최종 사용자의 보호된 리소스에 대한 액세스를 보호하고 제한합니다.

GTAF는 데이터 요금제 세부정보와 같은 보호된 리소스에 액세스하기 위해 최종 사용자의 사용자 인증 정보를 사용하는 대신 액세스 토큰을 획득합니다. 액세스 토큰은 GTAF의 사용자 인증 정보를 대신하여 GTAF에 발급됩니다. 그런 다음 GTAF는 액세스 토큰을 사용하여 DPA에서 호스팅하는 데이터 요금제 세부정보에 액세스합니다.

다음 그림은 대략적인 정보 흐름을 보여줍니다.

그림 1. 추상 OAuth 흐름입니다.

액세스 토큰

액세스 토큰은 GTAF가 이동통신사의 DPA에서 데이터 요금제 세부정보에 액세스하는 데 사용하는 사용자 인증 정보입니다. 액세스 토큰은 GTAF에 발급된 승인을 나타내는 문자열입니다. 문자열은 일반적으로 GTAF에 불투명합니다. 토큰은 최종 사용자가 이동통신사에 부여하고 DPA와 이동통신사의 OAuth 서버에서 시행하는 액세스의 특정 범위와 기간을 나타냅니다.

액세스 토큰은 추상화 계층을 제공하여 다양한 승인 구조 (예: 사용자 이름 및 비밀번호)를 DPA에서 이해하는 단일 토큰으로 대체합니다. 이 추상화를 통해 액세스 토큰을 획득하는 데 사용된 승인 부여보다 더 제한적인 액세스 토큰을 발급할 수 있으며, DPA가 광범위한 인증 방법을 이해할 필요가 없습니다.

액세스 토큰은 이동통신사의 보안 요구사항에 따라 다양한 형식, 구조, 활용 방법(예: 암호화 속성)을 가질 수 있습니다. GTAF는 [RFC6750]에 정의된 운반자 유형 액세스 토큰만 지원합니다.

클라이언트 인증

GTAF는 '기밀 클라이언트'로 작동하며 비밀번호를 안전하게 유지할 수 있습니다. GTAF는 현재 DPA로 인증하기 위한 HTTP 기본 인증만 지원합니다. 클라이언트 식별자는 'application/x-www-form-urlencoded' 인코딩 알고리즘을 사용하여 인코딩되며 인코딩된 값은 사용자 이름으로 사용됩니다. 비밀번호는 동일한 알고리즘을 사용하여 인코딩되며 비밀번호로 사용됩니다.

클라이언트 사용자 인증 정보가 발급된 GTAF와 같은 컨피덴셜 클라이언트는 토큰 엔드포인트에 요청하는 동안 이동통신사의 OAuth 서버로 인증합니다. 클라이언트 인증은 다음 용도로 사용됩니다. \

클라이언트를 사용 중지하거나 클라이언트의 사용자 인증 정보를 변경하여 클라이언트가 손상된 상태에서 복구합니다. 이렇게 하면 공격자가 도용된 새로고침 토큰을 악용하지 못합니다. 단일 클라이언트 사용자 인증 정보를 변경하는 것이 전체 새로고침 토큰 집합을 취소하는 것보다 훨씬 빠릅니다.
인증 관리 권장사항을 구현합니다. 여기에는 주기적인 사용자 인증 정보 순환이 필요합니다.

GTAF는 토큰 엔드포인트에 요청을 보낼 때 'client_id' 요청 매개변수를 사용하여 자체를 식별합니다.

특히 클라이언트 사용자 인증 정보를 순환할 수 있는 기능이 중요합니다. OAuth 서버는 순환 중에 두 개의 동시 사용자 인증 정보 쌍을 지원할 수 있어야 하며 사용자 인증 정보를 사용 중지할 수 있어야 합니다. 일반적인 사용자 인증 정보 순환에서는 다음을 수행합니다.

운송업체는 OAuth 서버에서 새 사용자 인증 정보를 만들고 보안 방식으로 기술 계정 관리자에게 사용자 인증 정보를 전달합니다.
Google에서 새 사용자 인증 정보를 테스트하고 새 사용자 인증 정보를 사용하도록 GTAF 구성을 변경합니다.
Google에서 이동통신사에 이전 사용자 인증 정보가 사용 중지될 수 있음을 알립니다.
운송업체가 사용자 인증 정보를 사용 중지하고 Google에 알림을 보냅니다.
Google에서 이전 사용자 인증 정보가 더 이상 작동하지 않는지 확인합니다.

OAuth 서버는 위의 순환 프로세스를 지원할 수 있어야 합니다.

토큰 엔드포인트

토큰 엔드포인트는 GTAF가 승인 부여 또는 갱신 토큰을 제시하여 액세스 토큰을 획득하는 데 사용됩니다. 토큰 엔드포인트는 암시적 부여 유형을 제외한 모든 승인 부여와 함께 사용됩니다 (액세스 토큰이 직접 발급되므로).

다음은 토큰 엔드포인트를 구성할 때 고려해야 할 몇 가지 사항입니다.

토큰 엔드포인트의 위치는 서비스 문서에 제공되어야 합니다.
엔드포인트 URI에는 추가 쿼리 매개변수를 추가할 때 유지해야 하는 'application/x-www-form-urlencoded' 형식의 쿼리 구성요소가 포함될 수 있습니다. 엔드포인트 URI에는 프래그먼트 구성요소가 포함되어서는 안 됩니다.
토큰 엔드포인트에 대한 요청은 일반 텍스트 사용자 인증 정보 (HTTP 요청 및 응답)의 전송을 초래하므로 이동통신사의 OAuth 서버는 토큰 엔드포인트에 요청을 전송할 때 TLS를 사용해야 합니다.
GTAF는 액세스 토큰을 요청할 때 HTTP 'POST' 메서드를 사용합니다.
값이 없는 상태로 전송된 매개변수는 요청에서 생략된 것으로 처리해야 합니다. OAuth 서버는 인식할 수 없는 요청 매개변수를 무시해야 합니다. 요청 및 응답 매개변수는 두 번 이상 포함하면 안 됩니다.
GTAF는 베어러 유형 액세스 토큰만 지원합니다.

액세스 토큰 범위

승인 및 토큰 엔드포인트를 사용하면 클라이언트가 'scope' 요청 매개변수를 사용하여 액세스 요청의 범위를 지정할 수 있습니다. 그러면 승인 서버는 'scope' 응답 매개변수를 사용하여 발급된 액세스 토큰의 범위를 클라이언트에 알립니다.

범위 매개변수의 값은 공백으로 구분되고 대소문자를 구분하는 문자열 목록으로 표현됩니다. 문자열은 승인 서버에 의해 정의됩니다. 값에 공백으로 구분된 문자열이 여러 개 포함된 경우 순서는 중요하지 않으며 각 문자열은 요청된 범위에 추가 액세스 범위를 추가합니다.

 scope = scope-token *( SP scope-token )
 scope-token = 1*( %x21 / %x23-5B / %x5D-7E )

GTAF는 범위를 구현하도록 요구하지는 않지만 이 기능을 지원합니다. 자세한 내용은 RFC 6749의 섹션 3.3을 참고하세요.

액세스 토큰 발급

GTAF에서 보낸 액세스 토큰 요청이 유효하고 승인된 경우 OAuth 서버는 액세스 토큰과 선택적 갱신 토큰을 발급합니다. 요청이 클라이언트 인증에 실패하거나 유효하지 않으면 OAuth 서버는 다음 섹션에 설명된 대로 오류 응답을 반환합니다.

성공 응답

GTAF가 요청을 전송하면 OAuth 서버는 액세스 토큰과 선택적 갱신 토큰을 발급하고 200 (OK) 상태 코드가 포함된 HTTP 응답의 엔티티 본문에 다음 매개변수를 추가하여 응답을 구성합니다. \

access_token: 필수입니다. OAuth 서버에서 발급한 액세스 토큰입니다. GTAF는 토큰 엔드포인트가 베어러 토큰을 반환할 것으로 예상합니다.
expires_in: 필수입니다(REQUIRED). 액세스 토큰의 수명(초)입니다. 예를 들어 값 '3600'은 응답이 생성된 시점으로부터 1시간 후에 액세스 토큰이 만료됨을 나타냅니다. 생략된 경우 OAuth 서버는 다른 수단을 통해 만료 시간을 제공하거나 기본값을 문서화해야 합니다.
token_type: 필수입니다. 발급된 토큰의 유형입니다. 다양한 유형의 토큰에 관한 자세한 내용은 RFC 6749의 섹션 7.1을 참고하세요. 값은 대소문자를 구분하지 않습니다. 이 문서 작성 시점을 기준으로 GTAF는 베어러 토큰만 지원합니다.
refresh_token: 선택사항입니다. 동일한 승인 부여를 사용하여 새 액세스 토큰을 획득하는 데 사용할 수 있는 갱신 토큰입니다.
범위: 구현되고 GTAF에서 요청한 범위와 동일한 경우 선택사항, 그렇지 않은 경우 필수

매개변수는 'application/json'을 사용하여 HTTP 응답의 엔티티 본문에 포함됩니다. 매개변수는 각 매개변수를 최상위 구조 수준에 추가하여 JavaScript 객체 표기법 (JSON) 구조로 직렬화됩니다. 매개변수 이름과 문자열 값은 JSON 문자열로 포함됩니다. 숫자 값은 JSON 숫자로 포함됩니다. 매개변수의 순서는 중요하지 않으며 다를 수 있습니다.

인증 서버는 토큰, 사용자 인증 정보 또는 기타 민감한 정보를 포함하는 모든 응답에 'no-store' 값이 있는 HTTP 'Cache-Control' 응답 헤더 필드와 'no-cache' 값이 있는 'Pragma' 응답 헤더 필드를 포함해야 합니다(MUST).

예를 들면 다음과 같습니다.

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"Bearer",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
       "example_parameter":"example_value"
     }

다음은 고려해야 할 몇 가지 중요한 사항입니다.

GTAF는 응답에서 인식할 수 없는 값 이름을 무시합니다.
OAuth 서버에서 수신한 토큰 및 기타 값의 크기는 정의되지 않은 상태로 남아 있습니다.
GTAF는 값 크기에 관해 가정하지 않아야 합니다. OAuth 서버는 발급하는 값의 크기를 문서화해야 합니다.

오류 응답

리디렉션 URI가 누락되거나, 유효하지 않거나, 일치하지 않는 등의 이유로 승인 요청이 실패하거나 클라이언트 식별자가 누락되거나 유효하지 않은 경우 OAuth 서버는 HTTP 400 (잘못된 요청) 상태 코드로 응답해야 하며 (달리 지정되지 않는 한) 오류 응답 및 코드 섹션에 나열된 매개변수 중 하나 이상을 포함해야 합니다.

GTAF의 승인 부여

승인 부여는 GTAF가 액세스 토큰을 획득하는 데 사용하는 최종 사용자의 승인(데이터 잔액 정보와 같은 보호된 리소스에 액세스)을 나타내는 사용자 인증 정보입니다.

GTAF는 client_credentials 부여 유형을 사용합니다. client_credentials 부여 유형에서 GTAF는 HTTP POST 요청과 HTTP 기본 인증을 사용하여 토큰을 요청합니다. 모든 요청은 TLS를 통해 전송됩니다 (예: HTTPS)를 사용해야 하며, GTAF는 유효한 TLS 인증서가 없으면 OAuth 서버와 통합할 수 없습니다. GTAF는 구성 가능한 토큰 범위를 전달할 수 있으며 구성되지 않은 경우 빈 범위를 전달합니다.

GTAF는 액세스 토큰이 'expires_in' 값(수명)과 함께 반환될 것으로 예상합니다. expires_in 값은 900초 이상이어야 하며 몇 시간을 초과해서는 안 됩니다. 새 토큰을 요청해도 기존 토큰이 조기에 만료되어서는 안 됩니다.

다양한 부여 유형에 관한 자세한 내용은 RFC 6749의 섹션 1.3을 참고하세요.

요청 및 응답 예시

GTAF에 OAuth 서버에 관한 다음 구성이 있다고 가정해 보겠습니다.

URL: https://www.example.com/gettoken/
Client ID: gtaf
Client secret: password
Scope: dpa

참고: 실제 DPA의 클라이언트 보안 비밀번호는 예시에 표시된 것보다 훨씬 더 안전해야 합니다.

승인 문자열을 생성하기 위해 클라이언트 ID, ':', 비밀번호가 연결되고 base64로 인코딩됩니다. 명령줄 인터페이스에서 다음과 같이 복제할 수 있습니다.

$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==

그런 다음 GTAF는 이러한 사용자 인증 정보, client_credentials 부여 유형, 구성된 범위를 사용하여 OAuth 서버에 HTTPS POST 요청을 합니다. 예를 들어 GTAF의 요청은 다음에서 생성된 요청과 유사합니다.

$ curl -H 'Authorization: Basic Z3RhZjpwYXNzd29yZA==' -X POST \
-d 'grant_type=client_credentials&scope=dpa' 'https://www.example.com/gettoken/'

GTAF에서 사용하는 헤더는 curl에서 전송하는 헤더와 일치하지 않지만 승인 헤더는 동일합니다.

GTAF는 다음 형식의 응답을 예상합니다.

{
"access_token":"<token>",
"token_type": "Bearer",
"expires_in":<expiration time>
}

다음은 유효한 응답의 예입니다.

{
"access_token":"YXRudWhhZXVoLGFodWFoaGF1aG9zaHVvYWV1Cg",
"token_type": "Bearer",
"expires_in":3600
}

참고: 응답은 유효한 JSON이어야 합니다.

오류 응답 및 코드

오류 응답 섹션에 명시된 이유로 GTAF의 승인 요청이 실패하는 경우 OAuth 서버는 HTTP 400 (잘못된 요청) 상태 코드로 응답해야 하며 (달리 명시되지 않는 한) 다음 매개변수 중 하나를 응답에 포함해야 합니다.

예: \

     HTTP/1.1 400 Bad Request
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "error":"invalid_request"
     }

GTAF는 OAuth 서버가 다음 오류 응답을 지원할 것으로 예상합니다.

오류 코드	응답	이유
HTTP 400	invalid_request	요청에 필수 매개변수가 누락되었거나, 지원되지 않는 매개변수 값 (승인 유형 제외)이 포함되었거나, 매개변수가 반복되었거나, 여러 사용자 인증 정보가 포함되었거나, GTAF로 인증하는 데 둘 이상의 메커니즘이 사용되었거나, 요청이 잘못된 형식입니다.
HTTP 401	invalid_client	클라이언트 인증이 실패했습니다 (예: 알 수 없는 클라이언트, 클라이언트 인증이 포함되지 않음 또는 지원되지 않는 인증 방법). OAuth 서버는 지원되는 HTTP 인증 스키마를 나타내기 위해 HTTP 401 (승인되지 않음) 상태 코드를 반환할 수 있습니다. 클라이언트가 'Authorization' 요청 헤더 필드를 통해 인증을 시도한 경우 OAuth 서버는 HTTP 401 (Unauthorized) 상태 코드로 응답해야 하며 클라이언트가 사용한 인증 스키마와 일치하는 'WWW-Authenticate' 응답 헤더 필드를 포함해야 합니다.
HTTP 500	OAuth 서버 실패

디버깅에 사용할 수 있는 다른 응답에 관한 자세한 내용은 RFC 6749의 섹션 5.2를 참고하세요.

데이터 요금제 에이전트용 OAuth API 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

관련 문서

개요