認証

アプリケーション単独認証とOAuth 2.0ベアラートークン

概要

Twitterは、特定のユーザーに代わってではなく、アプリケーション自身に代わって認証されたリクエストを発行する機能をアプリケーションに提供します。Twitterの実装は、OAuth 2仕様のクライアント認証情報付与フローに基づきます。

アプリケーション単独認証は、ユーザーコンテキストを含まず、アプリケーションが自身の代わりにAPIリクエストを行う認証形式です。これは、公開情報への読み取り専用アクセスのみを必要とする開発者向けの方法です。 

アプリケーション単独認証は、アプリのコンシューマーAPIキーを使用して、またはベアラートークンを使用して実行できます。つまりこれは、Twitter APIに対して行える単独リクエストでは、認証されたユーザーを要求する必要がないことを意味します。

アプリケーション単独認証では、次のことを実行できます。

  • ユーザータイムラインを取得する
  • 任意のアカウントの友人とフォロワーにアクセスする
  • リストリソースにアクセスする
  • ツイートを検索する

 

ユーザーに代わってリクエストを発行するには、引き続きOAuth 1.0aが必要です。 APIリファレンスのページには、APIを利用するために必要な認証方法が記載されています。以下を実行するには、アクセストークンを持つユーザー認証、ユーザーコンテキストが必要です。

  • ツイートまたはその他のリソースを投稿する
  • ユーザーを検索する
  • 位置情報のエンドポイントを使用する
  • ダイレクトメッセージやアカウントの認証情報にアクセスする
  • ユーザーのメールアドレスを取得する

 

認証フロー

このメソッドを使用するには、ベアラートークンを使用する必要があります。POST oauth2/tokenエンドポイントを介してコンシューマーキーとシークレットを渡すと、ベアラートークンを生成できます。 

アプリケーション単独認証のフローは以下の手順に従います。

  • アプリケーションが、そのコンシューマーキーとシークレットを特別にエンコードされた認証情報のセットにエンコードします。
  • アプリケーションが、POST oauth2/tokenエンドポイントにリクエストを行い、これらの認証情報をベアラートークンと交換します。
  • REST APIにアクセスするときに、アプリケーションはベアラートークンを使用して認証します。

リクエストに署名する必要がないため、このアプローチは標準的なOAuth 1.0aモデルよりもはるかにシンプルです。

 

アプリケーション単独認証の概要

トークンはパスワード

コンシューマーキーとシークレット、およびベアラートークン自体が、アプリケーションに代わってリクエストするためのアクセス権を付与します。これらの値は、パスワードと同様に秘密性の高いものとお考えください。信頼されていない相手と共有したり、信頼されていない相手に配信したりしてはいけません。

SSLが必須

すべてのリクエスト（トークンの取得と使用の両方）でHTTPSエンドポイントを使用する必要があります。「TLSを使用しTwitter APIに接続」に記載されているベストプラクティスに従ってください。ピアは常に検証される必要があります。

ユーザーコンテキストは不要

アプリケーション単独認証を使用してリクエストを発行する場合、「現在のユーザー」という概念はありません。そのため、POST statuses/updateのようなエンドポイントは、アプリケーション単独認証では機能しません。ユーザーに代わってリクエストを発行する方法の詳細については、「OAuthの使用」を参照してください。

レート制限

アプリケーションには2種類のレート制限プールがあります。

ユーザーコンテキストとも呼ばれるアクセストークンを使用してユーザーに代わって行われるリクエストは、アプリケーション単独認証で使用されるレート制限コンテキストではなく、異なるレート制限コンテキストから消費されます。つまり、別の言い方をすると、ユーザーに代わって行われるリクエストは、アプリケーション単独認証で利用可能なレート制限からは消費されません。また、アプリケーション単独認証で行われるリクエストは、ユーザーベース認証で使用されるレート制限からは消費されません。

アプリケーション単独認証をサポートしているGET application/rate_limit_statusエンドポイントを使用すると、レート制限を確認できます。アプリケーションベアラートークンを使用してこのメソッドにリクエストを発行すると、現在のウィンドウのリソースごとのレート制限コンテキストを示す応答を受け取ります。使用されているアクセストークンを示す「rate_limit_context」フィールドを受け取る代わりに、「application」フィールドを受け取ります。このフィールドの値は、アプリケーションのコンシューマーキーです。

{
  "rate_limit_context": {
      "application": "nXtEH7H0mi0qT8kSyo7DQ"
  },
  "resources": {
    "search": {
      "/search/tweets": {
        "limit": 450,
        "remaining": 420,
        "reset": 1362436375 }
    }
  }
}

 

APIレート制限の詳細を読み、制限を確認してください。

 

アプリケーション単独リクエストの発行

手順1:コンシューマーキーとシークレットをエンコードする

アプリケーションのコンシューマーキーとシークレットを一連の認証情報にエンコードしてベアラートークンを取得する手順は、以下のとおりです。

  1. RFC 1738に従って、コンシューマーキーとコンシューマーシークレットをURLエンコードします。執筆時点では、これによってコンシューマーキーとシークレットが実際に変更されることはありませんが、将来的にこれらの値の形式が変更される場合に備えて、本手順を実行しておく必要があります。
  2. エンコードしたコンシューマーキー、コロン「:」、エンコードしたコンシューマーシークレットを1つの文字列に連結します。
  3. 前の手順の文字列をBase64でエンコードします。

以下は、このアルゴリズムの結果を示す値の例です。このページで使用されているコンシューマーシークレットはテスト用であり、実際のリクエストでは機能しません。

コンシューマーキー xvz1evFS4wEEPTGEFPHBog
コンシューマーシークレット L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
RFC 1738に従ってエンコードされたコンシューマー
キー（変更なし）
 xvz1evFS4wEEPTGEFPHBog
RFC 1738に従ってエンコードされたコンシューマー
シークレット（変更なし）
 L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
ベアラートークンの認証情報 xvz1evFS4wEEPTGEFPHBog:L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
Base64エンコードされたベアラートークンの認証情報 :: eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJnNmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==

手順2:ベアラートークンを取得する

手順1で算出した値は、POST oauth2/tokenにリクエストを発行して、ベアラートークンと交換する必要があります。

  • このリクエストはHTTP POSTリクエストである必要があります。
  • リクエストには、Basic <base64 encoded value from step 1>.の値を持つAuthorizationヘッダーを含める必要があります。
  • リクエストには、application/x-www-form-urlencoded;charset=UTF-8.の値を持つContent-Typeヘッダーを含める必要があります。
  • リクエストの本文はgrant_type=client_credentialsである必要があります。

リクエストのサンプル（Authorizationヘッダーはラッピングされています）:

POST /oauth2/token HTTP/1.1
Host: api.x.com
User-Agent: My Twitter App v1.0.23
Authorization: Basic eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJn
                     NmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: 29
Accept-Encoding: gzip

grant_type=client_credentials

 

リクエストが正しくフォーマットされていると、サーバーはJSONでエンコードされたペイロードで応答します。

応答の例:

HTTP/1.1 200 OK
Status: 200 OK
Content-Type: application/json; charset=utf-8
...
Content-Encoding: gzip
Content-Length: 140

{"token_type":"bearer","access_token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}

 

アプリケーションは、返されたオブジェクトのtoken_typeキーに関連付けられた値がbearerであることを確認する必要があります。access_tokenキーに関連付けられた値はベアラートークンです。

1つのアプリケーションに対して一度に1つのベアラートークンが有効です。/oauth2/tokenに対して同じ認証情報を使用した別のリクエストを発行すると、無効化されるまで同じトークンを返します。

手順3:ベアラートークンを使用してAPIリクエストを認証する

ベアラートークンは、アプリケーション単独認証をサポートするAPIエンドポイントへのリクエストを発行するために使用できます。ベアラートークンを使用するには、通常のHTTPSリクエストを構築し、Bearer <base64 bearer token value from step 2>. Signing is not required.の値を持つAuthorizationヘッダーを含めます。

リクエストのサンプル（Authorizationヘッダーはラッピングされています）:

GET /1.1/statuses/user_timeline.json?count=100&screen_name=twitterapi HTTP/1.1
Host: api.x.com
User-Agent: My Twitter App v1.0.23
Authorization: Bearer AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAA
                      AAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Accept-Encoding: gzip

 

ベアラートークンの無効化

ベアラートークンが侵害された場合や、なんらかの理由で無効にする必要がある場合は、POST oauth2/invalidate_tokenへの呼び出しを発行します。

リクエストのサンプル（Authorizationヘッダーはラッピングされています）:

POST /oauth2/invalidate_token HTTP/1.1
Authorization: Basic eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJn
                     NmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
User-Agent: My Twitter App v1.0.23
Host: api.x.com
Accept: */*
Content-Length: 119
Content-Type: application/x-www-form-urlencoded

access_token=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

 

応答の例:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 127
...

{"access_token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}

 

一般的なエラーの事例

このセクションでは、ベアラートークンとのネゴシエーションおよびその使用に関する一般的ないくつかの間違いについて説明します。考えられるすべてのエラー応答がここに記載されているわけではありません。扱われていないエラーコードと応答に注意してください。

ベアラートークンを取得する、または取り消す無効なリクエスト

以下のような場合に発生します。

  • 無効なリクエスト（例:grant_type=client_credentialsが省略されている）でベアラートークンを取得しようとしている。
  • 誤った、または期限切れのアプリの認証情報を使用してベアラートークンを取得しようと、または取り消そうとしている。
  • 誤ったベアラートークンまたは無効化されたベアラートークンを無効にしようとしている。
  • 短期間にあまりにも頻繁にベアラートークンを入手しようとしている。

次のような結果になります。

HTTP/1.1 403 Forbidden
Content-Length: 105
Content-Type: application/json; charset=utf-8
...

{"errors":[{"code":99,"label":"authenticity_token_error","message":"Unable to verify your credentials"}]}

 

APIリクエストに無効なベアラートークンが含まれる

誤ったまたは取り消されたベアラートークンを使用してAPIリクエストをすると、次のような結果になります。

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 61
...

{"errors":[{"message":"Invalid or expired token","code":89}]}

 

アプリケーション単独認証をサポートしていないエンドポイントでベアラートークンが使用されている

ベアラートークンを使用して、ユーザーコンテキスト（statuses/home_timelineなど）が必要なエンドポイントをリクエストすると、以下が生成されます。

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 91
...

{"errors":[{"message":"Your credentials do not allow access to this resource","code":220}]}