PKCE を使用した OAuth 2.0 Authorization Code Flow

はじめに

OAuth 2.0 は業界標準の認可プロトコルで、アプリケーションのスコープに対する制御を強化し、複数のデバイス間での認可フローを可能にします。OAuth 2.0 では、ユーザーに代わって特定の権限を付与する、きめ細かなスコープを選択できます。アプリで OAuth 2.0 を有効にするには、Developer Console のアプリ設定セクションにあるアプリの認証設定で有効化する必要があります。

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

デフォルトでは、Authorization Code Flow with PKCE で作成する 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

アプリの設定

アプリの認証設定は 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 clients

Confidential clients は、認証情報を認可されていない当事者に公開することなく、安全に保持できるクライアントです。認可サーバーと安全に認証し、client secret を保護します。Public clients は通常、ブラウザーやモバイルデバイスで実行されるため、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 clients、Web App と Automated App/bots は confidential clients です。有効な Authorization ヘッダーがある confidential client には client id は不要です。public client でのリクエストでは、依然として本文に Client Id を含める必要があります。

スコープ

スコープを使用すると、アプリに必要な権限のみが付与されるように、アプリのアクセスをきめ細かく設定できます。どのスコープがどのエンドポイントに対応するかについて詳しくは、authentication mapping ガイドを参照してください。


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

レート制限

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

grant types

今回の初期リリースでは、サポートする grant types として authorization code with PKCE と refresh token のみを提供しています。将来的にはさらに多くの grant types を提供する可能性があります。

OAuth 2.0 フロー

OAuth 2.0 は現在 OAuth 1.0a で使用しているものと類似したフローを使用します。図と詳細な説明は、こちらのドキュメントを参照してください。

用語集


用語	説明
Grant types	OAuth フレームワークは、さまざまなユースケース向けに複数の grant types を指定しており、新しい grant types を作成するためのフレームワークも規定しています。例には authorization code、client credentials、device code、refresh token があります。
Confidential client	認可サーバーと安全に認証できるクライアント (例えば、登録された client secret を安全に保持できるクライアント)。
Public client	ブラウザーやモバイルデバイスで実行されるアプリケーションなど、登録された client secret を使用できないクライアント。
Authorization code flow	confidential client と public client の両方で authorization code を access token と交換するために使用されます。
PKCE	authorization code flow の拡張機能で、複数の攻撃を防ぎ、public client から OAuth 交換を安全に実行できるようにします。
Client ID	Developer Console の Keys and Tokens セクションの「Client ID」の下に表示されます。表示されない場合は、直接チームまでご連絡ください。Client ID は authorize URL の生成に必要です。
Redirect URI	コールバック URL。完全一致の検証が必要です。
Authorization code	ユーザーに代わって API を呼び出すためのコード。`auth_code` として知られています。アプリ所有者がユーザーから承認済み `auth_code` を受け取ってから 30 秒以内という時間制限があります。30 秒以内に access token と交換する必要があり、それを過ぎると `auth_code` は期限切れになります。
Access token	アプリケーションがユーザーに代わって API リクエストを行うために使用するトークン。
Refresh token	ユーザーに再度促すことなく、リフレッシュトークンフローで新しい access token を取得できるようにします。
Client Secret	confidential client 型のアプリを選択した場合、アプリの keys and tokens セクションの「Client ID」の下に「Client Secret」が表示されます。

パラメーター

OAuth 2.0 authorize URL を構築するには、認可 URL に以下のパラメーターを含める必要があります。


パラメーター	説明
response_type	「code」という単語で 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 の「サインイン」と同様の認証フローでユーザーに認証を許可できます。作成する 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 のドキュメントも合わせてご覧ください。