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 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 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 ポリシーから返されるエラーは、エラーコード参照で説明されている一貫した形式に従います。

The OAuthV1 Policy type defines the following error codes.

For OAuth-related HTTP error codes, see OAuth HTTP error response reference.

Error Code	Message

`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}`

OAuthv1.0a ポリシー

概要

サンプル

使用上の注意

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

簡単なフォーム

詳細なフォーム

アクセス トークンの生成

簡単なフォーム

詳細なフォーム

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

詳細なフォーム

パラメータ

サンプル レスポンス

アクセス トークンの検証

簡単なフォーム

詳細なフォーム

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

スキーマ

フロー変数

エラーコード

関連トピック

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

アクセストークンの生成

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

サンプルレスポンス

アクセストークンの検証

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