OAuth 2.0 Authorization Code Flow with PKCE

소개

OAuth 2.0은 애플리케이션의 스코프에 대한 더 큰 제어와 여러 디바이스에 걸친 승인 흐름을 허용하는 산업 표준 승인 프로토콜입니다. OAuth 2.0을 사용하면 사용자를 대신하여 특정 권한을 부여하는 세분화된 스코프를 선택할 수 있습니다. 앱에서 OAuth 2.0을 활성화하려면 Developer Console의 앱 설정 섹션에서 찾을 수 있는 앱의 인증 설정에서 활성화해야 합니다.

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

기본적으로 Authorization Code Flow with PKCE를 통해 생성하는 액세스 토큰은 offline.access 스코프를 사용하지 않는 한 두 시간 동안만 유효합니다.

Refresh token

Refresh token을 사용하면 애플리케이션이 refresh token 흐름을 통해 사용자에게 프롬프트하지 않고 새 액세스 토큰을 얻을 수 있습니다. offline.access 스코프가 적용되면 OAuth 2.0 refresh token이 발급됩니다. 이 refresh token으로 액세스 토큰을 얻을 수 있습니다. 이 스코프가 전달되지 않으면 refresh token이 생성되지 않습니다. 새 액세스 토큰을 얻기 위해 refresh token을 사용하는 요청의 예는 다음과 같습니다:

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

앱 설정

앱의 인증 설정을 OAuth 1.0a 또는 OAuth 2.0으로 선택할 수 있습니다. 또한 앱이 OAuth 1.0a와 OAuth 2.0 모두에 액세스하도록 활성화할 수 있습니다. OAuth 2.0은 X API v2에서만 사용할 수 있습니다. OAuth 2.0을 선택한 경우 앱의 Keys and Tokens 섹션에서 Client ID를 볼 수 있습니다.

Confidential client

Confidential client는 자격 증명을 승인되지 않은 당사자에게 노출하지 않고 안전한 방식으로 보유할 수 있으며, 승인 서버와 안전하게 인증하여 client secret을 안전하게 유지합니다. Public client는 일반적으로 브라우저나 모바일 디바이스에서 실행되고 client secret을 사용할 수 없습니다. Confidential client인 앱 유형을 선택하면 client secret이 제공됩니다. Developer Console에서 confidential client인 클라이언트 유형을 선택한 경우, Client Secret도 볼 수 있습니다. 옵션은 Native App, Single page App, Web App, Automated App 또는 bot입니다. Native App과 Single page App은 public client이고 Web App과 Automated App 또는 bot은 confidential client입니다. 유효한 Authorization Header가 있는 confidential client의 경우 client id가 필요하지 않습니다. public client의 요청에는 여전히 요청 본문에 Client Id를 포함해야 합니다.

스코프

스코프를 사용하면 앱에 대한 세분화된 액세스를 설정할 수 있으므로 앱은 필요한 권한만 가집니다. 어떤 스코프가 어떤 엔드포인트에 매핑되는지 자세히 알아보려면 인증 매핑 가이드를 확인하세요.


스코프	설명
tweet.read	보호된 계정의 Tweet을 포함하여 볼 수 있는 모든 Tweet.
tweet.write	나를 대신하여 Tweet 및 Retweet.
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에서 북마크 추가 및 제거.
dm.read	보호된 계정의 Direct Message를 포함하여 볼 수 있는 모든 Direct Message.
dm.write	나를 대신하여 Direct Message 전송 및 관리.
media.write	미디어 업로드.

Rate limit

대부분의 경우, rate limit은 Tweet lookup과 Users lookup을 제외하고 OAuth 1.0a로 인증하는 것과 동일합니다. Tweet lookup과 user lookup에 OAuth 2.0을 사용할 때 App당 제한을 15분당 300에서 900 요청으로 늘리고 있습니다. 자세히 알아보려면 rate limits 문서를 확인하세요.

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	승인 서버와 안전하게 인증할 수 있는 클라이언트로, 예를 들어 등록된 client secret을 안전하게 유지합니다.
Public client	브라우저나 모바일 디바이스에서 실행되는 애플리케이션과 같이 등록된 client secret을 사용할 수 없는 클라이언트입니다.
Authorization code flow	authorization code를 액세스 토큰으로 교환하기 위해 confidential 및 public 클라이언트 모두가 사용합니다.
PKCE	여러 공격을 방지하고 public client에서 안전하게 OAuth 교환을 수행할 수 있도록 하는 authorization code flow의 확장입니다.
Client ID	Developer Console의 keys and tokens 섹션에서 “Client ID” 헤더 아래에서 찾을 수 있습니다. 표시되지 않으면 팀에 직접 문의하세요. authorize URL을 생성하는 데 Client ID가 필요합니다.
Redirect URI	콜백 URL입니다. 정확한 일치 검증이 필요합니다.
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 흐름을 통해 사용자에게 프롬프트하지 않고 새 액세스 토큰을 얻을 수 있게 합니다.
Client Secret	Confidential client인 앱 유형을 선택한 경우 앱의 keys and tokens 섹션의 “Client ID” 아래에 “Client Secret”이 제공됩니다.

매개변수

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


매개변수	설명
response_type	이것이 “code”라는 단어로 코드임을 지정해야 합니다.
client_id	Developer Console의 “Client ID” 헤더 아래에서 찾을 수 있습니다.
redirect_uri	콜백 URL입니다. 이 값은 앱 설정에서 정의된 콜백 URL 중 하나와 일치해야 합니다. OAuth 2.0의 경우, 콜백 URL에 대한 정확한 일치 검증이 필요합니다.
state	CSRF 공격에 대해 검증하기 위해 제공하는 임의의 문자열입니다. 이 문자열의 길이는 최대 500자까지 가능합니다.
code_challenge	PKCE 매개변수로, 요청할 때마다 임의의 시크릿입니다.
code_challenge_method	요청을 하는 데 사용하는 방법을 지정합니다(S256 또는 plain).

Authorize URL

OAuth 2.0을 사용하면 authorize URL을 생성하여, X의 “Sign In”과 유사한 인증 흐름을 통해 사용자가 인증할 수 있도록 할 수 있습니다. 생성하는 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이 작동하려면 적절한 인코딩이 필요하며, 퍼센트 인코딩에 대한 문서를 반드시 확인하세요.

Getting Started

Products

Fundamentals

Partners & Customers

Resources

OAuth 2.0 Authorization Code Flow with PKCE