このページは Cloud Translation API によって翻訳されました。

Data Plan Agent API 向けの OAuth

概要

通常、サードパーティのアプリケーションにデータプランやウォレットの詳細などの制限付きリソースへのアクセス権を付与するには、エンドユーザー（リソースオーナー）が認証情報をサードパーティと共有する必要があります。これにより、認証情報の保存、パスワード認証、エンドユーザーのリソースへの広範なアクセス、パスワードの漏洩など、いくつかの問題と制限が生じます。OAuth2.0 は、認可レイヤを導入することでこれらの問題に対処し、エンドユーザーの保護されたリソースへのアクセスを保護して制限します。

GTAF は、エンドユーザーの認証情報を使用してデータプランの詳細などの保護リソースにアクセスするのではなく、アクセストークンを取得します。アクセストークンは、GTAF の認証情報に代わって GTAF に発行されます。GTAF はアクセストークンを使用して、DPA がホストするデータプランの詳細にアクセスします。

次の図は、情報のフローの概要を示しています。

図 1. OAuth フローを抽象化します。

アクセストークン

アクセストークンは、GTAF が携帯通信会社の DPA からデータプランの詳細にアクセスするために使用する認証情報です。アクセストークンは、GTAF に発行された認可を表す文字列です。通常、この文字列は GTAF に対して不透明です。トークンは、エンドユーザーが携帯通信会社に付与し、DPA と携帯通信会社の OAuth サーバーによって適用される、特定のスコープとアクセス期間を表します。

アクセストークンは、さまざまな認証構成（ユーザー名やパスワードなど）を DPA が認識できる単一のトークンに置き換えることで、抽象化レイヤを提供します。この抽象化により、アクセストークンを取得するために使用された認可付与よりも制限の厳しいアクセストークンを発行できます。また、DPA が幅広い認証方法を理解する必要もなくなります。

アクセストークンは、携帯通信会社のセキュリティ要件に基づいて、さまざまな形式、構造、利用方法（暗号プロパティなど）を持つことができます。GTAF は、[RFC6750] で定義されているベアラータイプのアクセストークンのみをサポートします。

クライアント認証

GTAF は「機密クライアント」として機能し、パスワードを安全に保つことができます。GTAF は現在、DPA での認証に HTTP 基本認証のみをサポートしています。クライアント識別子は「application/x-www-form-urlencoded」エンコードアルゴリズムを使用してエンコードされ、エンコードされた値がユーザー名として使用されます。パスワードは同じアルゴリズムを使用してエンコードされ、パスワードとして使用されます。

クライアント認証情報が発行される GTAF などの機密クライアントは、トークンエンドポイントにリクエストを行う際に、携帯通信会社の OAuth サーバーで認証を行います。クライアント認証は、次の目的で使用されます。

クライアントを無効にするか、認証情報を変更して、侵害されたクライアントから復元します。これにより、攻撃者が盗まれた更新トークンを不正使用することを防ぎます。クライアント認証情報の単一セットを変更する方が、更新トークンのセット全体を取り消すよりも大幅に高速です。
認証管理のベストプラクティスを実装する。これには、定期的な認証情報のローテーションが必要です。

GTAF は、トークンエンドポイントにリクエストを送信するときに、"client_id" リクエストパラメータを使用して自身を識別します。

特に重要なのは、クライアント認証情報をローテーションする機能です。OAuth サーバーは、ローテーション中に 2 つの認証情報ペアを同時にサポートでき、認証情報を無効にする機能が必要です。一般的な認証情報のローテーションでは、次の処理が行われます。

携帯通信会社は OAuth サーバーで新しい認証情報を作成し、安全な方法でテクニカルアカウントマネージャーに認証情報を送信します。
Google は新しい認証情報をテストし、新しい認証情報を使用するように GTAF 構成を変更します。
Google は、古い認証情報が無効になる可能性があることを携帯通信会社に通知します。
運送業者が認証情報を無効にして Google に通知する
Google が古い認証情報が動作していないことを確認します。

OAuth サーバーは、上記のローテーションプロセスをサポートできる必要があります。

トークンエンドポイント

トークンエンドポイントは、GTAF が認証付与または更新トークンを提示してアクセストークンを取得するために使用されます。トークンエンドポイントは、暗黙的権限付与タイプを除くすべての認可付与で使用されます（アクセストークンが直接発行されるため）。

トークンエンドポイントを構成する際は、次の点に注意してください。

トークンエンドポイントの場所は、サービスドキュメントに記載されている必要があります。
エンドポイント URI には、「application/x-www-form-urlencoded」形式のクエリコンポーネントが含まれる場合があります。追加のクエリパラメータを追加する際は、このコンポーネントを保持する必要があります。エンドポイント URI にフラグメントコンポーネントを含めることはできません。
トークンエンドポイントへのリクエストは、クリアテキストの認証情報（HTTP リクエストとレスポンス内）の送信につながるため、携帯通信会社の OAuth サーバーは、トークンエンドポイントへのリクエストの送信に TLS を使用する必要があります。
GTAF は、アクセストークンをリクエストする際に HTTP の「POST」メソッドを使用します。
値なしで送信されたパラメータは、リクエストから省略されたものとして扱われる必要があります。OAuth サーバーは、認識できないリクエストパラメータを無視する必要があります。リクエストパラメータとレスポンスパラメータは 1 回しか含めることができません。
GTAF はベアラータイプのアクセストークンのみをサポートします。

アクセストークンのスコープ

認可エンドポイントとトークンエンドポイントを使用すると、クライアントは「scope」リクエストパラメータを使用してアクセスリクエストのスコープを指定できます。認可サーバーは、発行されたアクセストークンのスコープをクライアントに通知するために、レスポンスパラメータ「scope」を使用します。

スコープパラメータの値は、スペース区切りの大文字と小文字が区別される文字列のリストとして表されます。文字列は認可サーバーによって定義されます。値に複数のスペース区切りの文字列が含まれている場合、その順序は関係ありません。各文字列は、リクエストされたスコープに追加のアクセス範囲を追加します。

 scope = scope-token *( SP scope-token )
 scope-token = 1*( %x21 / %x23-5B / %x5D-7E )

GTAF ではスコープの実装は必須ではありませんが、この機能はサポートしています。詳細については、RFC 6749 のセクション 3.3 を参照してください。

アクセストークンの発行

GTAF から送信されたアクセストークンリクエストが有効で承認されている場合、OAuth サーバーはアクセストークンとオプションの更新トークンを発行します。リクエストがクライアント認証に失敗した場合や、リクエストが無効な場合、OAuth サーバーは次のセクションで説明するようにエラーレスポンスを返します。

成功レスポンス

GTAF がリクエストを送信すると、OAuth サーバーはアクセストークンとオプションの更新トークンを発行し、200（OK）ステータスコードで HTTP レスポンスのエンティティ本文に次のパラメータを追加してレスポンスを構築します。

access_token: 必須。OAuth サーバーによって発行されたアクセストークン。GTAF は、トークンエンドポイントがベアラートークンを返すことを想定しています。
expires_in: 必須。アクセストークンの有効期間（秒単位）。たとえば、値「3600」は、レスポンスが生成された時刻から 1 時間後にアクセストークンが期限切れになることを示します。省略した場合、OAuth サーバーは他の方法で有効期限を提供するか、デフォルト値を文書化する必要があります。
token_type: 必須。発行されたトークンのタイプ。さまざまな種類のトークンの詳細については、RFC 6749 のセクション 7.1 をご覧ください。値では大文字と小文字が区別されません。このドキュメントの作成時点では、GTAF はベアラートークンのみをサポートしています。
refresh_token: 省略可。更新トークン。同じ認可付与を使用して新しいアクセストークンを取得するために使用できます。
scope: 省略可。実装されていて、GTAF がリクエストしたスコープと同じ場合。それ以外の場合は必須。

パラメータは、「application/json」を使用して HTTP レスポンスのエンティティ本文に含まれます。パラメータは、各パラメータを最上位の構造レベルに追加することで、JavaScript Object Notation（JSON）構造にシリアル化されます。パラメータ名と文字列値は JSON 文字列として含まれます。数値は JSON 数値として含まれます。パラメータの順序は関係なく、異なる場合があります。

認可サーバーは、トークン、認証情報、その他の機密情報を含むレスポンスに、値が「no-store」の HTTP「Cache-Control」レスポンスヘッダーフィールドと、値が「no-cache」の「Pragma」レスポンスヘッダーフィールドを含めなければなりません。

例:

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"Bearer",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
       "example_parameter":"example_value"
     }

考慮すべき重要な点は次のとおりです。

GTAF は、レスポンス内の認識できない値名を無視します。
OAuth サーバーから受信したトークンやその他の値のサイズは未定義のままです。
GTAF は値のサイズについて仮定することを避けるべきです。OAuth サーバーは、発行する値のサイズを文書化する必要があります。

エラーレスポンス

リダイレクト URI の欠落、無効、不一致などの理由で認可リクエストが失敗した場合、またはクライアント ID が欠落しているか無効な場合、OAuth サーバーは（特に指定がない限り）HTTP 400（Bad Request）ステータスコードで応答し、エラーレスポンスとコードのセクションに記載されているパラメータの少なくとも 1 つを含める必要があります。

GTAF の Authorization Grant

認可付与は、GTAF がアクセストークンを取得するために使用する、エンドユーザーの認可（データ残高情報などの保護されたリソースにアクセスするための認可）を表す認証情報です。

GTAF は client_credentials 権限付与タイプを使用します。client_credentials 許可タイプでは、GTAF は HTTP POST リクエストと HTTP 基本認証を使用してトークンをリクエストします。すべてのリクエストは TLS 経由で送信されます（HTTPS）を使用しているため、有効な TLS 証明書がないと GTAF は OAuth サーバーと統合できません。GTAF は構成可能なトークンスコープを渡すことができ、構成されていない場合は空のスコープを渡します。

GTAF は、アクセストークンが "expires_in" 値（有効期間）とともに返されることを想定しています。expires_in の値は 900 秒以上にする必要があります。また、数時間以内にする必要があります。新しいトークンをリクエストしても、既存のトークンが早期に期限切れになることはありません。

さまざまなグラントタイプの詳細については、RFC 6749 のセクション 1.3 をご覧ください。

リクエストとレスポンスの例

GTAF に OAuth サーバーの次の構成があるとします。

URL: https://www.example.com/gettoken/
Client ID: gtaf
Client secret: password
Scope: dpa

注: 実際の DPA のクライアントシークレットは、例に示すものよりもはるかに安全である必要があります。

認証文字列を生成するには、クライアント ID、コロン（:）、パスワードを連結して base64 でエンコードします。これは、コマンドラインインターフェースで次のように複製できます。

$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==

GTAF は、これらの認証情報、client_credentials 許可タイプ、構成されたスコープを使用して、OAuth サーバーに HTTPS POST リクエストを行います。たとえば、GTAF のリクエストは、次のコマンドで生成されるリクエストと似ています。

$ curl -H 'Authorization: Basic Z3RhZjpwYXNzd29yZA==' -X POST \
-d 'grant_type=client_credentials&scope=dpa' 'https://www.example.com/gettoken/'

GTAF で使用されるヘッダーは、curl で送信されるヘッダーと一致しませんが、認証ヘッダーは同じになります。

GTAF は、次の形式のレスポンスを想定しています。

{
"access_token":"<token>",
"token_type": "Bearer",
"expires_in":<expiration time>
}

有効なレスポンスの例を次に示します。

{
"access_token":"YXRudWhhZXVoLGFodWFoaGF1aG9zaHVvYWV1Cg",
"token_type": "Bearer",
"expires_in":3600
}

注: レスポンスは有効な JSON である必要があります。

エラーレスポンスとコード

エラーレスポンスセクションに記載されている理由のいずれかにより GTAF からの認可リクエストが失敗した場合、OAuth サーバーは（特に指定がない限り）HTTP 400（Bad Request）ステータスコードで応答し、レスポンスに次のいずれかのパラメータを含める必要があります。

例: \

     HTTP/1.1 400 Bad Request
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "error":"invalid_request"
     }

GTAF は、OAuth サーバーが次のエラーレスポンスをサポートすることを想定しています。

エラーコード	レスポンス	理由
HTTP 400	invalid_request	リクエストに必須パラメータがない、サポートされていないパラメータ値（グラントタイプ以外）が含まれている、パラメータが繰り返されている、複数の認証情報が含まれている、GTAF での認証に複数のメカニズムが使用されている、または形式が正しくない。
HTTP 401	invalid_client	クライアント認証に失敗しました（不明なクライアント、クライアント認証が含まれていない、サポートされていない認証方法など）。OAuth サーバーは、サポートされている HTTP 認証スキームを示すために HTTP 401（Unauthorized）ステータスコードを返すことがあります。クライアントが「Authorization」リクエストヘッダーフィールドを使用して認証を試みた場合、OAuth サーバーは HTTP 401（Unauthorized）ステータスコードで応答し、クライアントが使用した認証スキームに一致する「WWW-Authenticate」レスポンスヘッダーフィールドを含める必要があります。
HTTP 500	OAuth サーバーの障害

デバッグに使用できる他のレスポンスの詳細については、RFC 6749 のセクション 5.2 を参照してください。

Data Plan Agent API 向けの OAuth コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

関連ドキュメント

概要

アクセス トークン

クライアント認証

トークン エンドポイント

アクセス トークンのスコープ

アクセス トークンの発行