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

​

PKCE を使用した OAuth 2.0 認可コードフロー

​

はじめに

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

アプリで OAuth 2.0 を有効にするには、開発者ポータルのアプリ設定にある認証設定で有効化してください。

​

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

デフォルトでは、PKCE を用いた Authorization Code フローで作成したアクセストークンは、offline.access スコープを使用していない限り、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

​

アプリ設定

アプリの認証設定は、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 が表示されます。 

​

機密クライアント

機密クライアントは、資格情報を不正な第三者に開示することなく安全に保持し、認可サーバーに対して安全に認証できるため、クライアントシークレットを安全に保てます。パブリッククライアントは通常、ブラウザやモバイルデバイス上で動作するため、クライアントシークレットを使用できません。機密クライアントに該当するタイプのアプリを選択した場合、クライアントシークレットが提供されます。

開発者ポータルで機密クライアントに該当するクライアントタイプを選択した場合は、Client Secret も表示されます。選択肢は Native App、Single Page App、Web App、Automated App、または bot です。Native App と Single Page App はパブリッククライアント、Web App と Automated App または bot は機密クライアントです。

有効な Authorization ヘッダーを用いる機密クライアントでは client id は不要です。パブリッククライアントでのリクエストでは、本文に 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	閲覧可能なすべてのSpaces。
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 ルックアップとユーザー ルックアップは例外です。OAuth 2.0 を使用する場合、Tweet ルックアップおよびユーザー ルックアップの15分あたりのアプリごとの上限を、300 リクエストから 900 リクエストに引き上げます。詳しくは、レート制限に関するドキュメントをご確認ください。

​

グラントタイプ

この初期リリースでは、サポート対象のグラントタイプとして、PKCEを用いた認可コードとリフレッシュトークンのみを提供します。将来的に、グラントタイプを追加する可能性があります。

​

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 は失効します。
Access token	アクセストークンは、アプリケーションがユーザーに代わって API リクエストを行うために使用するトークンです。
Refresh token	ユーザーに再承認を求めることなく、refresh token フローを通じて新しいアクセストークンを取得できるようにします。
Client Secret	機密クライアントの App タイプを選択している場合、App の「キーとトークン」セクション内の「Client ID」の下に「Client Secret」が表示されます。

​

パラメータ

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

パラメータ	説明
response_type	これは認可コードであることを “code” という語で指定する必要があります。
client_id	開発者ポータルの「Client ID」ヘッダーの下にあります。
redirect_uri	コールバック URL。この値はアプリの設定で定義されている Callback URLs のいずれかと一致している必要があります。OAuth 2.0 では、コールバック URL に対して厳密一致の検証が必要です。
state	あなたが提供するランダムな文字列で、CSRF 攻撃に対する検証に使用します。文字列の長さは最大 500 文字です。
code_challenge	PKCE のパラメータで、各リクエストごとのランダムなシークレットです。
code_challenge_method	リクエストに使用する方式を指定します（S256 または plain）。

​

認可URL 

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