OAuth 2.0 認可コードフロー（PKCE 対応）

​

OAuth 2.0 認可コードフロー（PKCE）

​

はじめに

OAuth 2.0 は業界標準の認可プロトコルで、アプリケーションのスコープや、複数デバイスにまたがる認可フローをより細かく制御できます。OAuth 2.0 を用いると、ユーザーに代わって特定の権限を付与するための、きめ細かなスコープを選択できます。

App で OAuth 2.0 を有効にするには、developer portal の App 設定セクションにある認証設定で有効化してください。

​

資格情報はどのくらいの期間有効ですか?  

デフォルトでは、PKCE を用いた Authorization Code Flow で作成した access token は、offline.access スコープを使用しない限り、2 時間のみ有効です。

​

リフレッシュトークン

リフレッシュトークンを使用すると、リフレッシュトークンフローにより、ユーザーに再度の操作を求めることなく、アプリケーションが新しい access token を取得できます。

スコープ offline.access が適用されている場合は、OAuth 2.0 のリフレッシュトークンが発行されます。このリフレッシュトークンを用いて access token を取得します。このスコープが指定されていない場合は、リフレッシュトークンは発行されません。

リフレッシュトークンを使用して新しい access 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

​

App settings

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 が表示されます。 

​

Confidential Clients

Confidential clients は、資格情報を不正な第三者にさらすことなく安全に保持し、認可サーバーに対して安全に認証を行うことで、クライアントシークレットを保護できます。Public clients は通常、ブラウザーやモバイルデバイス上で動作するため、クライアントシークレットを使用できません。Confidential client に該当する App の種類を選択した場合は、クライアントシークレットが付与されます。

developer portal で confidential client に該当するクライアントタイプを選択した場合、Client Secret も確認できます。選択肢は Native App、Single page App、Web App、Automated App、または bot です。Native App と Single page App は public clients、Web App と Automated App または bot は confidential clients です。

有効な Authorization Header を使用する confidential clients では client id は不要です。public client からのリクエストでは、本文に Client Id を引き続き含める必要があります。 

​

スコープ

スコープを使用すると、App に必要な権限だけを付与する細かなアクセス制御を設定できます。各スコープがどの endpoint に対応するかの詳細は、認証マッピングガイドをご覧ください。

Scope	説明
tweet.read	閲覧可能なすべての Tweet（保護されたアカウントの Tweet を含む）。
tweet.write	あなたに代わって Tweet および リツイート を実行。
tweet.moderate.write	あなたの Tweet への返信を非表示/再表示。
users.email	認証済みユーザーのメールアドレス。
users.read	閲覧可能なすべてのアカウント（保護されたアカウントを含む）。
follows.read	あなたのフォロワーと、あなたがフォローしている人。
follows.write	あなたに代わってフォロー/フォロー解除を実行。
offline.access	アクセスを取り消すまで、あなたのアカウントへの接続を維持。
space.read	閲覧可能なすべての Spaces。
mute.read	ミュートしているアカウント。
mute.write	あなたに代わってアカウントのミュート/ミュート解除を実行。
like.read	あなたが like した Tweet と、閲覧可能な like。
like.write	あなたに代わって Tweet を like/like 解除。
list.read	あなたが作成またはメンバーである List、リストメンバー、リストのフォロワー（非公開リストを含む）。
list.write	あなたに代わって List を作成および管理。
block.read	ブロックしているアカウント。
block.write	あなたに代わってアカウントのブロック/ブロック解除を実行。
bookmark.read	認証済みユーザーのブックマーク済み Tweet を取得。
bookmark.write	Tweet のブックマークを追加/削除。
media.write	メディアをアップロード。

​

レートリミット

ほとんどの場合、レートリミットは OAuth 1.0a 認証時と同じですが、Tweets lookup と Users lookup は例外です。Tweet lookup および user lookup に OAuth 2.0 を使用する場合、15 分あたりの App ごとの上限を 300 リクエストから 900 リクエストに引き上げます。詳しくは、レートリミットに関するドキュメントをご確認ください。

​

グラントタイプ

この初期リリースでサポートするグラントタイプは、PKCE を用いたauthorization codeとrefresh tokenのみです。今後、対応するグラントタイプを拡充する可能性があります。

​

OAuth 2.0 フロー

OAuth 2.0 は、現在 OAuth 1.0a で用いているものと同様のフローを使用します。図表と詳細な説明は、このトピックに関するドキュメントをご参照ください。 

​

用語集

用語	説明
Grant types	OAuth フレームワークは、さまざまなユースケース向けに複数のグラントタイプを規定し、新しいグラントタイプを作成するための枠組みを提供します。例として authorization code、client credentials、device code、refresh token などがあります。
Confidential client	認可サーバーに対して安全に認証できるアプリケーションを指します。たとえば、登録済みの client secret を安全に保持できます。
Public client	ブラウザやモバイルデバイス上で実行されるアプリケーションなど、登録済みの client secret を使用できないクライアントを指します。
Authorization code flow	機密クライアントおよびパブリッククライアントの双方が、authorization code を access token と交換するために使用します。
PKCE	Authorization code flow の拡張で、複数の攻撃を防ぎ、パブリッククライアントからでも安全に OAuth のやり取りを実施できるようにします。
Client ID	developer portal のキーおよびトークンのセクション内、ヘッダー「Client ID」の下にあります。表示されない場合は、当チームまで直接ご連絡ください。Client ID は authorize URL の生成に必要です。
Redirect URI	コールバック URL のことです。exact match validation が必要です。
Authorization code	アプリケーションがユーザーに代わって API を呼び出せるようにするコードです。auth_code として知られています。ユーザーから承認済みの auth_code を App の所有者が受け取ってから、有効期限は 30 秒です。30 秒以内に access token と交換する必要があり、過ぎると auth_code は失効します。
Access token	access token は、アプリケーションがユーザーに代わって API リクエストを行う際に使用するトークンです。
Refresh token	refresh token フローにより、ユーザーに再度プロンプトを表示することなく新しい access token を取得できます。
Client Secret	機密クライアントである App タイプを選択した場合、App のキーおよびトークンのセクション内の「Client ID」の下に「Client Secret」が提供されます。

​

パラメータ

OAuth 2.0 の認可 URL を構築するには、認可 URL に次のパラメータが含まれていることを確認してください。

Parameter	Description
response_type	“code” と指定して、認可コードであることを示す必要があります。
client_id	developer portal の「Client ID」見出しの下にあります。
redirect_uri	コールバック URL。この値は、App の設定で定義された Callback URLs のいずれかと一致している必要があります。OAuth 2.0 では、コールバック URL に対してexact match validationが必要です。
state	CSRF 攻撃を防ぐために検証に用いる、任意のランダムな文字列です。長さは最大 500 文字まで指定できます。
code_challenge	PKCE のパラメータで、各リクエストごとに使用するランダムなシークレットです。
code_challenge_method	使用する方式を指定します（S256 または plain）。

​

認可 URL 

OAuth 2.0 では、X の「Sign in」と同様の認証フローを通じてユーザーが認証できるようにするための認可 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を正しく動作させるには、適切なエンコードが必要です。パーセントエンコーディングに関するドキュメントを必ずご確認ください。