PKCE를 사용하는 OAuth 2.0 인가 코드 플로우

​

PKCE를 사용하는 OAuth 2.0 권한 부여 코드 플로우

​

소개

OAuth 2.0은 애플리케이션의 범위(scope)와 여러 기기에 걸친 인가 플로우를 보다 세밀하게 제어할 수 있게 해 주는 업계 표준 인가 프로토콜입니다. OAuth 2.0을 사용하면 사용자 대신 특정 권한을 부여하는 세분화된 범위를 선택할 수 있습니다. 

App에서 OAuth 2.0을 사용하려면 개발자 콘솔의 App 설정 섹션에 있는 App 인증 설정에서 OAuth 2.0을 활성화해야 합니다.

​

내 자격 증명은 얼마나 오래 유효한가요?

기본적으로 PKCE를 사용하는 Authorization Code Flow를 통해 발급한 access token은 offline.access scope를 사용하지 않은 경우 2시간만 유효합니다.

​

리프레시 토큰

리프레시 토큰을 사용하면 리프레시 토큰 플로를 통해 사용자에게 다시 동의를 요청하지 않고도 애플리케이션이 새 액세스 토큰을 발급받을 수 있습니다.

요청에 offline.access 스코프가 포함되면 OAuth 2.0 리프레시 토큰이 발급됩니다. 이 리프레시 토큰을 사용해 액세스 토큰을 발급받을 수 있습니다. 이 스코프가 포함되지 않으면 리프레시 토큰은 생성되지 않습니다.

리프레시 토큰을 사용해 새 액세스 토큰을 발급받기 위해 수행하는 요청 예시는 다음과 같습니다.

POST 'https://api.x.com/2/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'refresh_token=bWRWa3gzdnk3WHRGU1o0bmRRcTJ5VUxWX1lZTDdJSUtmaWcxbTVxdEFXcW5tOjE2MjIxNDc3NDM5MTQ6MToxOnJ0OjE' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id=rG9n6402A3dbUJKzXTNX4oWHJ

​

App 설정

App의 인증 설정을 OAuth 1.0a 또는 OAuth 2.0으로 구성할 수 있습니다. App이 OAuth 1.0a와 OAuth 2.0 둘 다를 사용하도록 설정할 수도 있습니다.

OAuth 2.0은 X API v2와만 함께 사용할 수 있습니다. OAuth 2.0을 선택한 경우 App의 Keys and Tokens 섹션에서 Client ID를 확인할 수 있습니다. 

​

기밀 클라이언트

기밀 클라이언트는 자격 증명을 무단 당사자에게 노출하지 않고 안전하게 보관할 수 있으며, 인증 서버와 안전하게 통신하여 클라이언트 시크릿을 보호할 수 있습니다. 반면 Public 클라이언트는 일반적으로 브라우저나 모바일 기기에서 실행되므로 클라이언트 시크릿을 안전하게 사용할 수 없습니다. App 유형에서 기밀 클라이언트를 선택하면 Client Secret이 제공됩니다. 

개발자 콘솔에서 클라이언트 유형으로 기밀 클라이언트를 선택한 경우, Client Secret도 확인할 수 있습니다. 선택 가능한 옵션은 Native App, Single page App, Web App, Automated App, 또는 bot입니다. Native App과 Single page App은 Public 클라이언트이며, Web App과 Automated App 또는 bot은 기밀 클라이언트입니다.

유효한 Authorization 헤더를 사용하는 기밀 클라이언트의 경우 client id는 필요하지 않습니다. Public 클라이언트로 요청을 보낼 때는 요청 본문에 Client Id를 포함해야 합니다. 

​

Scopes

Scopes를 사용하면 App에 대해 세분화된 액세스 권한을 설정하여, App이 필요한 권한만 갖도록 할 수 있습니다. 각 scope가 어떤 endpoint에 매핑되는지 자세히 알아보려면 인증 매핑 가이드를 확인하세요.

Scope	Description
tweet.read	보호된 계정을 포함해, 사용자가 볼 수 있는 모든 Tweet을 조회합니다.
tweet.write	사용자를 대신해 Tweet을 작성하고 리트윗합니다.
tweet.moderate.write	사용자의 Tweet에 대한 답글을 숨기거나 다시 표시합니다.
users.email	인증된 사용자의 이메일 주소를 조회합니다.
users.read	보호된 계정을 포함해, 사용자가 볼 수 있는 모든 계정을 조회합니다.
follows.read	사용자를 팔로우하는 사람과 사용자가 팔로우하는 사람을 조회합니다.
follows.write	사용자를 대신해 다른 사용자를 팔로우하거나 언팔로우합니다.
offline.access	사용자가 액세스를 취소할 때까지 계정과의 연결 상태를 유지합니다.
space.read	사용자가 볼 수 있는 모든 Space를 조회합니다.
mute.read	사용자가 뮤트한 계정을 조회합니다.
mute.write	사용자를 대신해 계정을 뮤트하거나 뮤트를 해제합니다.
like.read	사용자가 좋아요를 누른 Tweet과 사용자가 볼 수 있는 좋아요를 조회합니다.
like.write	사용자를 대신해 Tweet에 좋아요를 누르거나 좋아요를 취소합니다.
list.read	사용자가 생성했거나 멤버로 속해 있는 리스트(비공개 리스트 포함)와 해당 리스트의 멤버 및 팔로워를 조회합니다.
list.write	사용자를 대신해 리스트를 생성하고 관리합니다.
block.read	사용자가 차단한 계정을 조회합니다.
block.write	사용자를 대신해 계정을 차단하거나 차단을 해제합니다.
bookmark.read	인증된 사용자의 북마크된 Tweet을 조회합니다.
bookmark.write	Tweet을 북마크하거나 북마크를 제거합니다.
media.write	미디어를 업로드합니다.

​

요청 한도

대부분의 경우 요청 한도는 OAuth 1.0a로 인증할 때와 동일하지만, Tweet 조회와 사용자 조회는 예외입니다. Tweet 조회 및 사용자 조회에 OAuth 2.0을 사용하는 경우, App당 요청 한도를 15분당 300건에서 900건으로 상향합니다. 자세한 내용은 요청 한도에 대한 문서를 참고하세요.

​

Grant types

이번 초기 출시에서는 지원되는 grant types로 PKCE를 사용하는 authorization code와 refresh token만 지원합니다. 앞으로 더 많은 grant type을 지원할 수 있습니다.

​

OAuth 2.0 플로우

OAuth 2.0는 현재 OAuth 1.0a에서 사용하고 있는 것과 유사한 플로우를 따릅니다. 이 주제에 대한 다이어그램과 자세한 설명은 관련 문서에서 확인할 수 있습니다. 

​

용어 사전

용어	설명
Grant types	OAuth 프레임워크는 다양한 사용 사례를 위한 여러 grant type과, 새로운 grant type을 만들기 위한 프레임워크를 정의합니다. 예로는 authorization code, client credentials, device code, refresh token 등이 있습니다.
Confidential client	Confidential client는 등록된 client secret을 안전하게 보관하는 등, 인가 서버와 안전하게 인증할 수 있는 애플리케이션을 의미합니다.
Public client	Public client는 브라우저나 모바일 기기에서 실행되는 애플리케이션처럼, 등록된 client secret을 사용할 수 없는 클라이언트를 의미합니다.
Authorization code flow	Confidential client와 Public client 모두가 authorization code를 access token으로 교환할 때 사용하는 플로우입니다.
PKCE	Authorization code flow의 확장으로, 여러 종류의 공격을 방지하고 Public client에서 OAuth 교환을 안전하게 수행할 수 있도록 해 줍니다.
Client ID	개발자 콘솔의 Keys and tokens 섹션에서 “Client ID” 헤더 아래에서 확인할 수 있습니다. 이 항목이 보이지 않는다면, 저희 팀에 직접 문의해 주세요. Client ID는 authorize URL을 생성하는 데 필요합니다.
Redirect URI	콜백 URL입니다. exact match validation을 충족해야 합니다.
Authorization code	애플리케이션이 사용자를 대신해 API를 호출할 수 있도록 해 주는 값입니다. auth_code라고도 합니다. auth_code는 App 소유자가 사용자로부터 승인된 auth_code를 받은 시점부터 30초의 유효 기간이 있습니다. 30초 안에 access token으로 교환해야 하며, 그렇지 않으면 auth_code는 만료됩니다.
Access token	Access token은 애플리케이션이 사용자를 대신해 API 요청을 보낼 때 사용하는 토큰입니다.
Refresh token	Refresh token flow를 통해, 사용자에게 다시 동의를 요청하지 않고도 새로운 access token을 얻을 수 있도록 해 줍니다.
Client Secret	Confidential client 유형의 App을 선택한 경우, App의 Keys and tokens 섹션에서 “Client ID” 아래에 “Client Secret”이 제공됩니다.

​

매개변수

OAuth 2.0 authorize URL을 구성하려면 authorization URL에 다음 매개변수들이 포함되어 있는지 확인해야 합니다. 

매개변수	설명
response_type	이 요청에서 authorization code 방식을 사용함을 나타내기 위해 값으로 “code”를 지정해야 합니다.
client_id	개발자 콘솔의 “Client ID” 항목에서 확인할 수 있습니다.
redirect_uri	콜백 URL입니다. 이 값은 App 설정에 정의된 Callback URLs 중 하나와 정확히 일치해야 합니다. OAuth 2.0의 경우 콜백 URL에 대해 정확히 일치하는지 검증이 필요합니다.
state	CSRF 공격을 방지하기 위해 제공하는 임의의 문자열입니다. 이 문자열의 길이는 최대 500자까지 가능합니다.
code_challenge	각 요청마다 사용하는 임의의 비밀 값인 PKCE 매개변수입니다.
code_challenge_method	요청을 보낼 때 사용하는 방식(S256 또는 plain)을 지정합니다.

​

Authorize URL

OAuth 2.0를 사용하면 사용자가 X의 “Sign In”과 유사한 인증 플로를 통해 인증할 수 있도록 사용할 authorize URL을 생성합니다. 

생성할 URL의 예시는 다음과 같습니다:

https://x.com/i/oauth2/authorize?response_type=code&client_id=M1M5R3BMVy13QmpScXkzTUt5OE46MTpjaQ&redirect_uri=https://www.example.com&scope=tweet.read%20users.read%20account.follows.read%20account.follows.write&state=state&code_challenge=challenge&code_challenge_method=plain

이 URL이 올바르게 작동하려면 적절한 인코딩이 필요합니다. 퍼센트 인코딩 관련 문서를 반드시 확인하십시오.