접근 토큰의 발급 및 갱신과 이를 이용하여 리소스에 접근하는 과정을 설명합니다.
접근 토큰 요청이 유효하고 인가되면, 인가 서버는 [Section 5.2]에 기술된 대로 접근 토큰과 선택적으로 갱신 토큰을 발급한다. 요청이 클라이언트 인증에 실패하거나 유효하지 않으면, 인가 서버는 [Section 5.2]에 기술된 대로 오류 응답을 반환한다.
인가 서버는 접근 토큰과 선택적으로 갱신 토큰을 발급하고 다음 파라미터를 200(OK) 상태 코드와 함께 HTTP 엔티티 바디에 추가하여 응답을 만든다:
access_tokentoken_typeexpires_inrefresh_tokenscope파라미터는 [RFC4627]에 기술된 “application/json” 미디어 유형을 사용하는 HTTP 응답의 엔티티 바디에 포함된다. 파라미터는 각 파라미터를 가장 높은 구조 수준에 추가하여 JavaScript Object Notation(JSON) 구조로 직렬화(serialized)된다. 숫자 값은 JSON 숫자로 보함된다. 파라미터의 순서는 중요하지 않으며 바뀔 수 있다.
인가 서버는 “Pragma” 응답 헤더 필드[RFC2616]를 “no-cache” 값으로 할 뿐만 아니라, 토큰, 자격 증명 또는 다른 민감한 정보를 포함하는 응답에 “no-store” 값으로 된 HTTP “Cache-Control” 응답 헤더 필드[RFC2616]를 포함해야 한다.
예를 들어:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"example",
"expires_in":3600,
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
"example_parameter":"example_value"
}
클라이언트는 응답에서 인식할 수 없는 값 이름은 무시해야 한다. 토큰과 인가 서버로부터 받은 다른 값의 크기는 정의되지 않은 채 남겨진다. 클라이언트는 값 크기에 대해 가정하는 것을 피해야 한다. 인가 서버는 자신이 발급하는 값의 크기를 문서화하는 것이 좋다.
인가 서버는 HTTP 400 (Bad Request) 상태 코드로 응답하고 다음 파라미터를 포함한다:
error필수. 다음으로부터의 단일 ASCII [USASCII] 에러 코드:
invalid_request
“error” 파라미터 값은 %x20-21 / %x23-5B / %x5D-7E 집합 밖에 있는 문자를 포함해서는 안된다.
error_description선택사항. 클라이언트 개발자가 발생한 오류를 이해하는 데 도움을 주는 추가적인 정보를 제공하는 사람이 읽을 수 있는 ASCII [USASCII] 텍스트. “error_desciption” 파라미터 값은 %x20-21 / %x23-5B / %x5D-7E 집합 밖에 있는 문자를 포함해서는 안된다.
error_uri선택사항. 오류에 대한 추가 정보와 함께 클라이언트 개발자에게 제공되는 것으로, 사람이 읽을 수 있는 오류에 대한 웹 페이지를 식별하는 URI. “error_uri” 파라미터 값은 URI 참조 문법을 따라야 하며 이에 따라 %x21 / %x23-5B / %x5D-7E 집합 밖의 문자열을 포함해서는 안된다.
파라미터는 [RFC4627]에 기술된 “application/json” 미디어 유형을 사용하는 HTTP 응답의 엔티티 바디에 포함된다. 파라미터는 각 파라미터를 가장 높은 구조 수준에 추가하여 JavaScript Object Notation(JSON) 구조로 직렬화(serialized)된다. 숫자 값은 JSON 숫자로 보함된다. 파라미터의 순서는 중요하지 않으며 바뀔 수 있다.
예를 들어:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"error":"invalid_request"
}
인가 서버가 클라이언트에게 갱신 토큰을 발급하면, 클라이언트는 HTTP 요청 엔티티 바디에 UTF-8 문자 인코딩으로 [부록 B]에 따라 “application/x-www-form-urlencoded”를 사용하여 다음 파라미터들을 추가하여 토큰 엔드포인트에 갱신 요청을 보낸다:
grant_typerefresh_tokenscope갱신 토큰은 주로 추가적인 접근 토큰을 요청하는데 사용되는 긴 수명을 가진 자격 증명이기 때문에, 갱신 토큰은 발급된 클라이언트에 바인딩된다. 클라이언트 유형이 기밀이거나 클라이언트가 클라이언트 자격 증명을 발급받(았거나 다른 인증 요구사항이 할당된)은 경우, 클라이언트는 [Section 3.2.1]에 기술된 대로 인가 서버에 인증해야 한다.
예를 들어, 클라이언트는 TLS를 사용하여 다음의 HTTP 요청을 보낸다(추가 개행은 보여주기 위함이다):
POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
인가 서버는 다음과 같이 해야 한다:
요청이 유효하고 인가되면, 인가 서버는 [Section 5.1]에 기술된 접근 토큰을 발급한다. 요청이 확인에 실패하거나 유효하지 않으면, 인가 서버는 [Section 5.2]에 기술된 대로 오류 응답을 반환한다.
클라이언트가 오래된 갱신 토큰을 버리고 새 갱신 토큰으로 대체해야 하는 경우, 인가 서버는 새로운 갱신 토큰을 발급할 수도 있다. 인가 서버는 클라이언트에게 새 갱신 토큰을 발급한 뒤 오래된 갱신 토큰을 취소할 수도 있다. 새 갱신 토큰이 발급되면, 갱신 토큰 범위는 클라이언트가 요청에 포함한 갱신 토큰과 같아야 한다.
클라이언트는 리소스 서버에 접근 토큰을 제시하여 보호된 리소스에 접근한다. 리소스 서버는 접근 토큰을 확인해야 하고 토큰이 만료되지 않았으며 범위가 요청된 리소스의 범위를 포함한다는 것을 보장해야 한다. 리소스 서버가 (오류 응답 뿐만 아니라)접근 토큰이 유효한지 확인하는 데 사용되는 방법은 이 명세의 범위를 벗어나지만 일반적으로 리소스 서버와 인가 서버 간의 상호 작용과 조정을 동반한다.
클라이언트가 리소스 서버와의 인증에 접근 토큰을 활용하는 방법은 인가 서버가 발급한 접근 토큰의 유형에 달렸다. 주로, [RFC6750]과 같이, 사용된 접근 토큰 유형의 명세에 정의된 인증 방식과 함께 HTTP “Authorization” 요청 헤더 필드[RFC2617]를 동반한다.
접근 토큰 유형은 클라이언트에게 (유형별 특성과 함께)보호된 리소스 요청을 보내는 데 성공적으로 접근 토큰을 활용하기 위해 필요한 정보를 제공한다. 클라이언트는 토큰 유형을 이해하지 않고 접근 토큰을 사용해선 안된다.
예를 들어, [RFC6750]의 “bearer” 토큰 유형은 요청에 접근 토큰을 간단하게 포함하는 데 활용된다.
GET /resource/1 HTTP/1.1
Host: example.com
Authorization: Bearer mF_9.B5f-4.1JqM
반면에 OAuth-HTTP-MAC에 정의된 “mac” 토큰 유형은 메시지 인증 코드(MAC) 키를 HTTP 요청의 특정 컴포넌트에 서명하는 데 사용되는 접근 토큰과 함께 발급하는 데 활용된다.
GET /resource/1 HTTP/1.1
Host: example.com
Authorization: MAC id="h480djs93hd8",
nonce="274312:dj83hs9s",
mac="kDZvddkndxvhGRXZhvuDjEWhGeE="
위 예시는 설명을 위한 목적으로만 제공됐다. 개발자는 사용하기 전에 [RFC6750]과 OAuth-HTTP-MAC을 찾아보는 것이 좋다.
각 접근 토큰 유형 정의는 “access_token” 응답 파라미터와 함께 클라이언트에게 보내지는 추가적인 특성을 명시한다. 또한 보호된 리소스 요청을 보낼 때 접근 토큰을 포함하는 HTTP 인증 방법에 대해서도 정의한다.
리소스 접근 요청이 실패하면, 리소스 서버는 클라이언트에게 오류에 대해 알리는 것이 좋다. 이러한 오류 응답의 세부 사항이 이 명세의 범위를 벗어나는 반면, 이 문서는 [Section 11.4]에서 OAuth 토큰 인증 방식 사이에서 공유되는 오류 값들에 대한 공용 레지스트리를 설정한다.
주로 OAuth 토큰 인증을 위해 설계된 인증 새 인증 방식들은, 허용된 오류 값이 이 문서에서 설정된 오류 레지스트리에 등록된 경우 오류 상태를 클라이언트에게 제공하는 메커니즘을 정의하는 것이 좋다.
그러한 방식은 유효한 오류의 집합을 등록된 값의 일부로 제한할 수도 있다. 오류 코드가 명명된 파라미터를 사용하여 반환되면, 파라미터의 이름은 “error”인 것이 좋다.
OAuth 토큰 인증에서 사용될 수 있지만 주로 해당 목적을 위해 설계된 것이 아닌 다른 방식은 같은 방식으로 각각의 오류 값을 레지스트리에 바인드할 수도 있다.
새로운 인증 방식은 또한 “error_description”과 “error_uri” 파라미터의 사용을 명시하여 이 명세에서 사용하는 것과 동일한 방식으로 오류 정보를 반환하도록 선택할 수 있다.