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

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

はじめに

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

App で OAuth 2.0 を利用できるようにするには、開発者コンソールの App 設定セクションにある認証設定で OAuth 2.0 を有効にする必要があります。

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

デフォルトでは、PKCE を用いた Authorization Code Flow で作成したアクセストークンは、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

App の設定

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 は、認可されていない第三者に資格情報をさらすことなく、安全な方法で資格情報を保持し、認可サーバーと安全に認証を行い、client secret を安全に保管できるクライアントです。Public clients は、通常ブラウザーやモバイルデバイス上で動作するため、client secrets を使用できません。機密クライアントである App の type を選択した場合、client secret が付与されます。 

開発者コンソールで機密クライアントの type を選択した場合、Client Secret も確認できます。選択できるオプションは、Native App、Single page App、Web App、Automated App、bot です。Native App と Single page App は public clients であり、Web App と Automated App または bot は機密クライアントです。

有効な Authorization Header を使用する機密クライアントでは、client id を指定する必要はありません。public client で行うリクエストについては、引き続きリクエストボディに Client Id を含める必要があります。 

スコープ

スコープを使用すると、あなたのAppに対してきめ細かいアクセス権を設定し、必要な権限だけを付与できます。どのスコープがどのエンドポイントに対応しているかの詳細は、認証マッピングガイドを参照してください。

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 で認証する場合と同じですが、Tweet lookup と Users lookup のみ例外となります。OAuth 2.0 を使用した Tweet lookup および Users lookup では、App ごとの上限を 15 分あたり 300 リクエストから 900 リクエストに引き上げています。詳細については、レート制限に関するドキュメントをご覧ください。

グラントタイプ

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

OAuth 2.0 フロー

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

用語集

Term	Description
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	開発者コンソールの keys and tokens セクション内の “Client ID” 見出しの下にあります。これが表示されていない場合は、弊社チームまで直接ご連絡ください。authorize URL を生成する際に Client ID が必要になります。
Redirect URI	アプリケーションの callback 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 flow を通じて、ユーザーに再度プロンプトを表示することなく、新しい access token を取得できるようにします。
Client Secret	機密クライアントである App タイプを選択した場合、開発者コンソールの App の keys and tokens セクション内で、「Client ID」の下に「Client Secret」が表示されます。

パラメーター

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

Parameter	Description
response_type	これがコードであることを示すために、“code” という単語を指定する必要があります。
client_id	開発者コンソールのヘッダー「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)。

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が正しく機能するには、適切なエンコードが必要です。パーセントエンコーディングに関するドキュメントを必ず参照してください。