메인 콘텐츠로 건너뛰기

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

​
소개

OAuth 2.0은 여러 기기 전반에서 애플리케이션의 스코프와 인증 흐름을 보다 정교하게 제어할 수 있게 해주는 업계 표준 권한 부여 프로토콜입니다. OAuth 2.0을 사용하면 사용자를 대신해 특정 권한을 부여하는 세분화된 스코프를 선택할 수 있습니다. 앱에서 OAuth 2.0을 사용하려면 개발자 포털의 앱 설정 섹션에 있는 앱 인증 설정에서 이를 활성화해야 합니다.

​
내 자격 증명은 얼마나 오래 유효하나요?  

기본적으로 PKCE를 사용하는 Authorization Code Flow로 발급한 액세스 토큰은 offline.access 스코프를 사용하지 않은 경우 두 시간만 유효합니다.

​
리프레시 토큰

리프레시 토큰은 리프레시 토큰 플로우를 통해 사용자 상호작용 없이 애플리케이션이 새 액세스 토큰을 받을 수 있도록 합니다. 스코프 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

​
앱 설정

앱의 인증 설정을 OAuth 1.0a 또는 OAuth 2.0으로 선택할 수 있습니다. 또한 앱이 OAuth 1.0a와 OAuth 2.0을 모두 사용하도록 설정할 수도 있습니다. OAuth 2.0은 X API v2에서만 사용할 수 있습니다. OAuth 2.0을 선택한 경우, 앱의 키와 토큰 섹션에서 Client ID를 확인할 수 있습니다. 

​
기밀 클라이언트

기밀 클라이언트는 자격 증명을 무단 당사자에게 노출하지 않고 안전하게 보관하며, 권한 부여 서버에 안전하게 인증해 클라이언트 시크릿을 보호할 수 있습니다. 퍼블릭 클라이언트는 보통 브라우저나 모바일 기기에서 실행되므로 클라이언트 시크릿을 사용할 수 없습니다. 기밀 클라이언트 유형의 앱을 선택하면 클라이언트 시크릿이 제공됩니다. 개발자 포털에서 기밀 클라이언트 유형을 선택했다면 Client Secret도 확인할 수 있습니다. 선택 가능한 옵션은 Native App, Single Page App, Web App, Automated App, 또는 Bot입니다. Native App과 Single Page App은 퍼블릭 클라이언트이고, Web App과 Automated App 또는 Bot은 기밀 클라이언트입니다. 유효한 Authorization Header를 사용하는 기밀 클라이언트는 client id가 필요하지 않습니다. 퍼블릭 클라이언트로 요청하는 경우에는 본문에 Client Id를 포함해야 합니다. 

​
스코프

스코프를 사용하면 앱이 필요한 권한만 갖도록 세분화된 액세스를 설정할 수 있습니다. 스코프와 엔드포인트의 매핑에 대해 자세히 알아보려면 authentication mapping guide를 확인하세요.
Scope설명
tweet.read보호된 계정을 포함해 사용자가 볼 수 있는 모든 트윗.
tweet.write사용자를 대신해 트윗 작성 및 리트윗.
tweet.moderate.write사용자의 트윗에 달린 답글 숨기기 및 숨김 해제.
users.email인증된 사용자의 이메일.
users.read보호된 계정을 포함해 사용자가 볼 수 있는 모든 계정.
follows.read사용자를 팔로우하는 사람과 사용자가 팔로우하는 사람.
follows.write사용자를 대신해 팔로우 및 언팔로우.
offline.access액세스를 해지할 때까지 계정 연결 상태 유지.
space.read사용자가 볼 수 있는 모든 스페이스.
mute.read사용자가 뮤트한 계정.
mute.write사용자를 대신해 계정 뮤트 및 뮤트 해제.
like.read사용자가 좋아요한 트윗 및 사용자가 볼 수 있는 좋아요.
like.write사용자를 대신해 트윗에 좋아요 및 좋아요 취소.
list.read비공개 목록을 포함해 사용자가 만든 또는 구성원으로 있는 목록, 목록 멤버, 목록 팔로워.
list.write사용자를 대신해 목록 생성 및 관리.
block.read사용자가 차단한 계정.
block.write사용자를 대신해 계정 차단 및 차단 해제.
bookmark.read인증된 사용자의 북마크한 트윗 가져오기.
bookmark.write트윗에 북마크 추가 및 제거.
media.write미디어 업로드.

​
요청 한도

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

​
그랜트 타입

초기 출시에서는 지원되는 그랜트 타입으로 PKCE를 사용하는 authorization code와 refresh token만 제공합니다. 향후 더 많은 그랜트 타입을 지원할 수 있습니다.

​
OAuth 2.0 플로우

OAuth 2.0은 현재 OAuth 1.0a에서 사용하는 플로우와 유사합니다. 이 주제에 대한 문서에서 다이어그램과 자세한 설명을 확인하실 수 있습니다. 

​
용어집

용어설명
그랜트 타입OAuth 프레임워크는 다양한 사용 사례를 위한 여러 그랜트 타입과 새로운 그랜트 타입을 만들기 위한 프레임워크를 정의합니다. 예로 authorization code, client credentials, device code, refresh token이 있습니다.
기밀 클라이언트등록된 client secret을 안전하게 보관하는 등 권한 부여 서버에 안전하게 인증할 수 있는 애플리케이션을 말합니다.
퍼블릭 클라이언트브라우저나 모바일 기기에서 실행되는 애플리케이션처럼 등록된 client secret을 사용할 수 없는 클라이언트를 말합니다.
Authorization code 플로우기밀 및 퍼블릭 클라이언트가 authorization code를 액세스 토큰으로 교환할 때 사용됩니다.
PKCE여러 공격을 방지하고 퍼블릭 클라이언트에서도 OAuth 교환을 안전하게 수행할 수 있도록 authorization code 플로우를 확장한 것입니다.
Client ID개발자 포털의 키와 토큰 섹션에서 “Client ID” 헤더 아래에서 확인할 수 있습니다. 보이지 않는 경우 저희 팀에 직접 문의해 주세요. Client ID는 authorize URL을 생성하는 데 필요합니다.
Redirect URI콜백 URL입니다. 정확 일치 검증이 필요합니다.
Authorization code애플리케이션이 사용자를 대신해 API를 호출할 수 있도록 합니다. auth_code로 알려져 있습니다. App 소유자가 사용자로부터 승인된 auth_code를 받으면 해당 코드의 유효 시간은 30초입니다. 30초 이내에 액세스 토큰으로 교환해야 하며, 그렇지 않으면 auth_code가 만료됩니다.
액세스 토큰애플리케이션이 사용자를 대신해 API 요청을 수행하는 데 사용하는 토큰입니다.
리프레시 토큰리프레시 토큰 플로우를 통해 사용자 프롬프트 없이 새 액세스 토큰을 발급받을 수 있도록 합니다.
Client Secret기밀 클라이언트 유형의 App을 선택했다면 App의 키와 토큰 섹션에서 “Client ID” 아래에 “Client Secret”이 제공됩니다.

​
매개변수

OAuth 2.0 authorize URL을 구성하려면 인가 URL에 다음 매개변수가 포함되어 있어야 합니다. 
ParameterDescription
response_type이 값이 코드임을 “code”로 지정해야 합니다.
client_id개발자 포털의 “Client ID” 항목에서 확인할 수 있습니다.
redirect_uri앱의 콜백 URL입니다. 이 값은 앱 설정에 정의된 Callback URLs 중 하나와 정확히 일치해야 합니다. OAuth 2.0의 경우 콜백 URL에 대해 정확 일치 검증이 필요합니다.
stateCSRF 공격을 방지하기 위한 검증용 임의 문자열입니다. 길이는 최대 500자입니다.
code_challengePKCE 매개변수로, 요청마다 생성하는 임의의 시크릿입니다.
code_challenge_method요청에 사용할 방법을 지정합니다(S256 또는 plain).

​
Authorize URL 

OAuth 2.0를 사용하면 사용자가 X의 “로그인”과 유사한 인증 플로우를 통해 인증할 수 있도록 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이 제대로 작동하려면 올바른 인코딩이 필요합니다. percent encoding 관련 문서를 꼭 확인하세요.