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

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

개요

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

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

다음 그림은 대략적인 정보 흐름을 제공합니다.

그림 1. 추상 OAuth 흐름

액세스 토큰

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

액세스 토큰은 추상화 계층을 제공하여 다양한 승인 구조 (예: 사용자 이름 및 비밀번호)를 DPA에서 파악되는 단일 토큰으로 바꿉니다. 이 추상화는 액세스 토큰을 발급하는 데 사용되는 승인 부여보다 더 제한적인 액세스 권한을 발급할 수 있을 뿐만 아니라 DPA가 광범위한 인증 방법을 알아야 할 필요가 없습니다.

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

클라이언트 인증

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

클라이언트 사용자 인증 정보가 발급되는 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는 Bearer 유형 액세스 토큰만 지원합니다.

액세스 토큰 범위

승인 및 토큰 엔드포인트를 사용하면 클라이언트가 '범위' 요청 매개변수를 사용하여 액세스 요청의 범위를 지정할 수 있습니다. 그러면 승인 서버는 '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는 토큰 엔드포인트가 Bearer 토큰을 반환할 것으로 예상합니다.
expires_in: 필수 항목입니다. 액세스 토큰의 수명(초)입니다. 예를 들어 값 "3600"는 액세스 토큰이 응답이 생성된 시점으로부터 1시간 후에 만료됩니다. 생략된 경우 OAuth 서버는 다른 수단을 통해 만료 시간을 제공하거나 기본값을 문서화해야 합니다.
token_type: 필수 항목입니다. 발급된 토큰 유형입니다. 여러 유형의 토큰에 대한 자세한 내용은 RFC 6749의 섹션 7.1을 참조하세요. 이 값은 대소문자를 구분하지 않습니다. GTAF는 이 문서 작성 시점의 Bearer 토큰만 지원합니다.
refresh_token: 선택사항입니다. 갱신 토큰: 동일한 승인 부여를 사용하여 새 액세스 토큰을 받는 데 사용할 수 있습니다.
범위: 선택사항으로, 구현되고 GTAF에서 요청한 범위와 동일한 경우 필요하며, 그렇지 않으면 필수입니다.

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

승인 서버는 토큰, 사용자 인증 정보 또는 기타 민감한 정보가 포함된 응답과 'no-cache'가 포함된 HTTP 'Cache-Control' 응답 헤더 필드와 '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' 값(수명)과 함께 반환될 것으로 예상합니다. expiration_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	잘못된 요청	요청에 필수 매개변수가 누락되어 있거나, 지원되지 않는 매개변수 값이 포함되어 있거나 (부여 유형 제외), 매개변수를 반복하거나, 여러 사용자 인증 정보를 포함하거나, GTAF를 통해 인증하는 데 둘 이상의 메커니즘을 활용하거나, 형식이 잘못되었습니다.
HTTP 401	잘못된 클라이언트	클라이언트 인증 실패 (예: 알 수 없는 클라이언트, 포함된 클라이언트 인증 없음 또는 지원되지 않는 인증 방법) OAuth 서버가 지원되는 HTTP 인증 스킴을 나타내는 HTTP 401 (승인되지 않음) 상태 코드를 반환할 수 있습니다. 클라이언트가 '승인' 요청 헤더 필드를 통해 인증을 시도하는 경우 OAuth 서버는 HTTP 401 (승인되지 않음) 상태 코드로 응답하고 클라이언트에서 사용하는 인증 스킴과 일치하는 'WWW-Authenticate' 응답 헤더 필드를 포함해야 합니다.
HTTP 500	OAuth 서버 오류

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