OAuthv1.0a ポリシー

概要

OAuth 1.0a では、アプリのユーザーがプロセスでアプリにパスワードを公開しなくても、アプリがユーザーの代わりに API を使用することを許可する標準的なプロトコルを定義しています。Apigee Edge では、アプリのユーザーが API を使用するアプリを認可することで、API を保護できます。また、ポリシーベースの機能により、アプリのデベロッパーがアクセス トークンの取得に使用できるエンドポイントを構成できます。

サンプル

次のサンプルの詳細については、使用上の注意をご覧ください。

使用上の注意

Apigee Edge では OAuth v1.0a ポリシータイプを提供しています。これにより、OAuth 1.0a でアプリを認可できます。OAuthV1 ポリシータイプは、OAuth 1.0a 仕様に基づいて、リクエスト トークンの生成、アクセス トークンの生成、アクセス トークンの検証を行います。

API で OAuth ポリシーを構成した場合は、アプリでアクセス トークンを取得して使用する必要があります。この操作を行うには、アプリがアクセス トークン用にリクエスト トークンを交換する必要があります。OAuth では、API にアクセスする各アプリでマスターキーのように同じパスワードを使用するのではなく、このトークンを使用することで API とアプリ間で認証を行います。リソース オーナーは、制限付きのスコープと存続期間を設定してアクセス トークンを発行し、個別に取り消すことができます。

トークン リクエストで、Apigee OAuth 1.0a は oauth_signature_method ヘッダー パラメータ向けには HMAC-SHA 署名アルゴリズムのみをサポートします（詳しくは OAuth 1.0a 仕様をご覧ください）。

このポリシーの name 属性で使用できる文字は A-Z0-9._\-$ % 文字に制限されています。ただし、管理 UI では、英数字以外の文字を自動的に削除するなど、追加の制限が適用されます。

リクエスト トークンの生成

リクエスト トークンは、コンシューマ アプリがアプリのエンドユーザーから認可を得るときに使用されます。トークン エンドポイントに渡され、アクセス トークンと交換されます。リクエスト トークンは、有効なコンシューマ キーから生成されます。以下に、リクエスト トークンを生成する簡単なフォームと詳細なフォームを示します。

簡単なフォーム

<OAuthV1 name="OAuthV1-GenerateRequestToken-1">
  <Operation>GenerateRequestToken</Operation>
</OAuthV1>

詳細なフォーム

<OAuthV1 name="OAuthV1-GenerateRequestToken-1">
  <Operation>GenerateRequestToken</Operation>
    <URL ref="flow.variable">value</URL>
    <GenerateResponse enabled="true">
      <Format>FORM_PARAM | XML</Format>
    </GenerateResponse>
    <GenerateErrorResponse enabled="true">
      <Format>FORM_PARAM | XML</Format>
      <Realm>http://oauth.apigee.com/oauth/1/</Realm>
    </GenerateErrorResponse>
</OAuthV1>

このポリシーは、次の OAuth セマンティックを適用します。

  • コンシューマ キーが有効
  • 署名が有効

リクエストに成功すると、次のレスポンスが返されます。

  • フロー oauth_token、oauth_token_secret、oauth_callback_confirmed、oauth_response でリクエスト トークンとその属性を生成します。
  • また、コンシューマ トークンとその属性をフロー oauth_consumer_key、oauth_consumer_secret で使用できるようにします。

<URL> 要素により、Elastic Load Balancer（ELB）の背後で実行されている場合でも、OAuthV1 署名の計算が正しく行われます。ref 属性とテキスト値の両方が指定されている場合、ref 属性が優先されます。ref が指定されていない場合、または ref で指定されたフロー変数が NULL の場合、テキスト値が署名の生成対象とみなされます。例:

<URL ref="secretURL">https://example-test.apigee.net/oauth/access_token</URL>

失敗すると、エラー内容を示すレスポンス ステータス コードとエラー メッセージが返されます。

簡単なリクエスト:

https://$org-$env.$api_domain/oauth1-proxy/request_token -H 'Authorization: OAuth oauth_callback="oob", oauth_signature_method="HMAC-SHA1", oauth_token="\", oauth_consumer_key=“{consumerkey}“, oauth_timestamp="{timestamp}", oauth_nonce="{nonce}", oauth_version="1.0", oauth_signature="{signature}"'

アクセス トークンの生成

アクセス トークンは、コンシューマがユーザーの代わりに保護リソースにアクセスするときに使用されます。ユーザーのサービス プロバイダの認証情報の代わりに使用されます。アクセス トークンは有効なキー、リクエスト トークン、検証コードの組み合わせで作成されます。以下に、アクセス トークンを生成する簡単なフォームと詳細なフォームを示します。

簡単なフォーム

<OAuthV1 name="OAuthV1-GenerateAccessToken-1">
   <Operation>GenerateAccessToken</Operation>
</OAuthV1>

詳細なフォーム

<OAuthV1 name="OAuthV1-GenerateAccessToken-1">
  <Operation>GenerateAccessToken</Operation>
  <URL ref="flow.variable">{value}</URL>
  <GenerateResponse enabled="true">
    <Format>FORM_PARAM | XML</Format>
  </GenerateResponse>
  <GenerateErrorResponse enabled="true">
    <Format>FORM_PARAM | XML</Format>
    <Realm>http://oauth.apigee.com/oauth/1/</Realm>
  </GenerateErrorResponse>
</OAuthV1>

このポリシーは、次の OAuth セマンティックを適用します。

  • コンシューマ キーが有効
  • リクエスト トークンが有効
  • 検証コードが有効
  • 署名が有効

リクエストに成功すると、次のレスポンスが返されます。

  • フロー oauth_token、oauth_token_secret、oauth_response でアクセス トークンとその属性を生成します。
  • また、コンシューマ トークンとその属性をフロー oauth_consumer_key、oauth_consumer_secret で使用できるようにします。

<URL> 要素により、Elastic Load Balancer（ELB）の背後で実行されている場合でも、OAuthV1 署名の計算が正しく行われます。ref 属性とテキスト値の両方が指定されている場合、ref 属性が優先されます。ref が指定されていない場合、または ref で指定されたフロー変数が NULL の場合、テキスト値が署名の生成対象とみなされます。例:

<URL ref="secretURL">https://example-test.apigee.net/oauth/access_token</URL>

失敗すると、エラー内容を示すレスポンス ステータス コードとエラー メッセージが返されます。

トークン検証コードとリクエスト トークンの関連付け

以下のポリシーは、トークン検証コードとリクエスト トークンを関連付けます。アクセス トークンを受信するには、検証コードとリクエスト トークンの両方が必要です。

検証コードは、次のように基本的な OAuth フローに適合します。アプリユーザーの認証情報がサービス プロバイダで認証されると、サービス プロバイダは認証情報が承認されたことをコンシューマ アプリに通知します。これは、リクエスト トークンがアクセス トークンと交換可能であることを示します。これは通常 302 リダイレクトで行われます。これとは別に、サービス プロバイダが検証コードを Apigee Edge に送信し、Apigee Edge がこの検証コードをリクエスト トークンに内部的に関連付けます。

その後、アプリがリクエスト トークンとアクセス トークンを交換するときに、リクエスト トークンと検証コードの両方を渡します。Apigee Edge は検証コードが正しいことを確認し、認証されてサービスへのアクセスが許可されたユーザーと、アプリにアクセス トークンの取得を依頼したユーザーが同一であることを確認します。このメッセージ フローの詳細については、OAuth 1.0a 仕様をご覧ください。

詳細なフォーム

<OAuthV1 name="OAuthV1-GenerateVerifier-1">
    <Operation>GenerateVerifier</Operation>
    <RequestToken ref="request.header.requesttoken"/>
    <AppUserId ref="request.header.appuserid"/>
    <VerifierCode ref="request.header.verifiercode"/>
    <GenerateResponse enabled="true">
       <Format>FORM_PARAM | XML</Format>
    </GenerateResponse>
     <Attributes>
       <Attribute name="ver-attr1">ver-attr1</Attribute>
       <Attribute name="ver-attr2" ref="request.header.ver-attr2"></Attribute>
       <Attribute name="ver-attr3" display="false">ver-attr3</Attribute>
    </Attributes>
</OAuthV1>

パラメータ

パラメータ 説明
RequestToken （必須）検証に関連付けるリクエスト トークンを指定します。
AppUserId （必須）アプリケーション ユーザーの ID を指定します。
VerifierCode （必須）検証コードを指定します。このコードは、Apigee 以外の別のステップで生成する必要があります。
属性 （省略可）アクセス トークンに任意の値を関連付けることができます。リクエスト トークンに関連付けることもできます。アプリがアクセス トークンのリクエスト トークンを交換するときに、リクエスト トークンに関連付けられた属性がアクセス トークンに引き継がれます。ポリシーに指定されているカスタム属性が、リクエスト トークンに関連付けられているカスタム属性と同じ名前の場合、ここで指定したカスタム属性が優先されます。このトピックで後述するアクセス トークンのカスタマイズもご覧ください。


このポリシーが実行されると、次のフロー変数が挿入されます。

  • リクエスト トークン: oauthtoken.{policy_name}.oauth_token
  • 検証コード: authtoken.{policy_name}.verifier_code
  • アプリのユーザー ID: oauthtoken.{policy_name}.app_user_id

サンプル レスポンス

GenerateReponse が有効な場合、レスポンスで他の属性と一緒に検証コードが返されます。以下に、XML 形式のレスポンスの例を示します。

<response>
    <oauth_parameter name="issued_at">1389014375368</oauth_parameter>
    <oauth_parameter name="expires_at">1389016175368</oauth_parameter>
    <oauth_parameter name="application_name">f24b582d-701f-4cbd-a1e0-2fc0e77003</oauth_parameter>
    <oauth_parameter name="app_user_id">someappuserid</oauth_parameter>
    <oauth_parameter name="organization_id">0</oauth_parameter>
    <oauth_parameter name="oauth_token">HVEUg3Tb9tM8yMWZAARDcSbgeHp5</oauth_parameter>
    <oauth_parameter name="ver-attr1">ver-attr1-value</oauth_parameter>
    <oauth_parameter name="oauth_verifier">verifier-code</oauth_parameter>
    <oauth_parameter name="verifier_code">verifier-code</oauth_parameter>
</response>

アクセス トークンの検証

以下では、アクセス トークンの検証例を簡単なフォームと詳細なフォームで示します。

簡単なフォーム

<OAuthV1 name="OAuthV1-VerifyAccessToken-1">
  <Operation>VerifyAccessToken</Operation>
</OAuthV1>

詳細なフォーム

<OAuthV1 name="OAuthV1-VerifyAccessToken-1">
  <Operation>VerifyAccessToken</Operation>
  <URL ref="flow.variable">{value}</URL>
  <GenerateErrorResponse enabled="true">
    <Format>FORM_PARAM | XML</Format>
    <Realm>http://oauth.apigee.com/oauth/1/</Realm>
  </GenerateErrorResponse>
</OAuthV1>

このポリシーは、次の OAuth セマンティックを適用します。

  • コンシューマ キーが有効
  • アクセス トークンが有効
  • 署名が有効

検証に成功すると、次のレスポンスが返されます。

  • フロー oauth_token、oauth_token_secret、oauth_response でアクセス トークンとその属性を生成します。
  • また、コンシューマ トークンとその属性をフロー oauth_consumer_key、oauth_consumer_secret で使用できるようにします。

<URL> 要素により、Elastic Load Balancer（ELB）の背後で実行されている場合でも、OAuthV1 署名の計算が正しく行われます。ref 属性とテキスト値の両方が指定されている場合、ref 属性が優先されます。ref が指定されていない場合、または ref で指定されたフロー変数が NULL の場合、テキスト値が署名の生成対象とみなされます。例:

<URL ref="secretURL">https://example-test.apigee.net/oauth/access_token</URL>

リクエストの検証に失敗すると、サーバーは該当するレスポンス ステータス コードとエラー メッセージを返します。

アクセス トークンのカスタマイズ

アクセス トークン、更新トークン、検証トークンでカスタム属性を使用できます。

<Attributes>
  <Attribute name=”attr_name1” ref=”flow.variable” display="true|false">value1</Attribute>
  <Attribute name=”attr_name2” ref=”flow.variable” display="true|false">value2</Attribute>
</Attributes>

表示が true に設定されている場合、カスタム属性はレスポンスで返され、アプリのエンドユーザーが表示できます。

表示が false に設定されている場合、カスタム属性はデータストアに保存されますが、レスポンス メッセージでは返されません。

たとえば、リクエストに関連付けられた User-Agent をアクセス トークンに追加するには、次のように記述します。

<OAuthV1 name="GenerateAccessToken">
  <Operation>GenerateAccessToken</Operation>
  <ExpiresIn>1000</ExpiresIn>
  <GenerateResponse />
  <Attributes>
    <Attribute name=”user-agent” ref=”request.header.user-agent”
            display="false">NONE</Attribute>
  </Attributes>
</OAuthV1>

スキーマ

フロー変数

OAuthV1 と GetOAuthV1Info ポリシータイプは、実行時に次の変数を設定します。

GenerateRequestToken オペレーション

  • oauth_token
  • oauth_token_secret
  • oauth_callback_confirmed
  • oauth_response
  • oauth_consumer_key
  • oauth_consumer_secret

GenerateAccessToken オペレーション

  • oauth_token
  • oauth_token_secret
  • oauth_response
  • oauth_consumer_key
  • oauth_consumer_secret

VerifyAccessToken オペレーション

  • oauth_token
  • oauth_token_secret
  • oauth_response
  • oauth_consumer_key
  • oauth_consumer_secret

GetOAuthV1Info

  • oauth_consumer_key
  • oauth_consumer_secret

エラーコード

Edge ポリシーから返されるエラーは、エラーコード参照で説明されている一貫した形式に従います。

OAuthV1 ポリシータイプは、次のエラーコードを定義します。

OAuth 関連の HTTP エラーコードについては、OAuth HTTP エラー レスポンス リファレンスをご覧ください。

エラーコード メッセージ
AppKeyNotResolved Could not resolve the app key with variable {0}
ConsumerKeyNotResolved Could not resolve the consumer key with variable {0}
RequestTokenNotResolved Could not resolve the request token with the variable {0}
AccessTokenNotResolved Could not resolve the access token with the variable {0}
ResponseGenerationError Error while generating response : {0}
UnableToDetermineOperation Unable to determine an operation for stepDefinition {0}
UnableToResolveOAuthConfig Unable to resolve the OAuth configuration for {0}
AtLeastOneParamRequired At least one of AccessToken, RequestToken or ConsumerKey must be specified in stepDefinition {0}
SpecifyValueOrRefReqToken Specify Request Token as value or ref in stepDefinition {0}
SpecifyValueOrRefAccToken Specify Access Token as value or ref in stepDefinition {0}
SpecifyValueOrRefConKey Specify Consumer Key as value or ref in stepDefinition {0}
SpecifyValueOrRefAppKey Specify App Key as value or ref in stepDefinition {0}
ExpiresInNotApplicableForOperation ExpiresIn element is not valid for operation {0}
InvalidValueForExpiresIn Invalid value for ExpiresIn element for operation {0}
FailedToFetchApiProduct Failed to fetch api product for key {0}
InvalidTokenType Valid token types : {0}, Invalid toke type {1} in stepDefinition {2}
TokenValueRequired Token value is required in stepDefinition {0}
FailedToResolveRealm Failed to resolve realm {0}

関連トピック