OAuthV2 ポリシー

このページの内容は Apigee と Apigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示する。

概要

OAuthV2 は OAuth 2.0 権限付与タイプ オペレーションを実行するための多角的なポリシーです。これは、Apigee で OAuth 2.0 エンドポイントを構成するために使用される最も重要なポリシーです。

このポリシーは拡張可能なポリシーであり、Apigee ライセンスによっては、このポリシーの使用によって費用や使用率に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

Apigee での OAuth の詳細については、OAuth ホームページをご覧ください。リソース、サンプル、動画などへのリンクが記載されています。

サンプル

<OAuthV2 name="OAuthV2-Verify-Access-Token">
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

$ curl https://API_ENDPOINT/weather/forecastrss?w=12797282 \
  -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z"

<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <AppEndUser>Doe</AppEndUser>
    <UserName>jdoe</UserName>
    <PassWord>jdoe</PassWord>
    <GrantType>grant_type</GrantType>
    <ClientId>a_valid_client_id</ClientId>
    <SupportedGrantTypes>
        <GrantType>password</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

var clientId = context.getVariable("local_clientid");
var clientSecret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+ CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(clientId + ':' + clientSecret)));

基本認証用の認証情報のエンコードもご覧ください。

要素リファレンス

このポリシー リファレンスでは、OAuthV2 ポリシーの要素と属性について説明します。

次に示すサンプル ポリシーは、多くの可能な構成の 1 つです。このサンプルでは、GenerateAccessToken オペレーション向けに構成された OAuthV2 ポリシーを示しています。必須の要素と省略可能な要素が含まれています。詳しくは、このセクションの要素の説明をご覧ください。

<OAuthV2 name="GenerateAccessToken">
  <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in millseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

<OAuthV2> 属性

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

次の表に、すべてのポリシーの親要素に共通する属性を示します。

<DisplayName> 要素

管理 UI プロキシ エディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。

<DisplayName>Policy Display Name</DisplayName>

<AccessToken> 要素

<AccessToken>request.header.access_token</AccessToken>

デフォルトでは、Operation が VerifyAccessToken の場合、アクセス トークンが Authorization ヘッダーで署名なしトークンとして送信されることがポリシーで想定されます。つまり、接頭辞「Bearer」の後に 1 つの空白スペースが続きます。この要素を使用して、検証するアクセス トークンを含む変数の名前を指定し、デフォルトを変更できます。この要素を使用する場合、デフォルトではポリシー内で変数の内容の接頭辞は検索されません。ポリシーで接頭辞を検索するように指定する場合は、AccessTokenPrefix 要素も使用します。

例:

• ポリシー構成が以下に該当する場合:

    <OAuthV2 name="OAuthV2-Verify-Access-Token-in-Header">
        <Operation>VerifyAccessToken</Operation>
        <AccessToken>request.header.access_token</AccessToken>
    </OAuthV2>

  curl を使用してトークンを渡すには、次のコマンドを使用します。

    curl https://API_ENDPOINT/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

• ポリシー構成が以下に該当する場合:

    <OAuthV2 name="OAuthV2-Verify-Access-Token-in-QueryParam">
        <Operation>VerifyAccessToken</Operation>
        <AccessToken>request.queryparam.token</AccessToken>
    </OAuthV2>

  curl を使用してトークンを渡すには、次のコマンドを使用します。

    curl "https://API_ENDPOINT/oauth2/validate?token=Rft3dqrs56Blirls56a"

ここで、API_ENDPOINT は Apigee システムで構成された API へのアクセスに使用されるドメインです。

<AccessTokenPrefix> 要素

<AccessTokenPrefix>Prefix</AccessTokenPrefix>

デフォルトでは、Operation が VerifyAccessToken の場合、アクセス トークンが Authorization ヘッダーで署名なしトークンとして送信されることがポリシーで想定されます。つまり、接頭辞「Bearer」の後に 1 つの空白スペースが続きます。AccessToken 要素を使用して受信アクセス トークンの別の場所を指定している場合は、この要素 AccessTokenPrefix を使用して別の標準以外の接頭辞を指定することもできます。

たとえば、次のように指定するとします。

<OAuthV2 name="OAuthV2-Verify-Access-Token-Alternative-Header">
    <Operation>VerifyAccessToken</Operation>
    <AccessToken>request.header.token</AccessToken>
    <AccessTokenPrefix>KEY</AccessTokenPrefix>
</OAuthV2>

次に、ポリシーは token リクエスト ヘッダーからインバウンド アクセス トークンを抽出します。ヘッダーが「KEY」という単語で始まり、その後にスペースが続く場合、ポリシーによってこの接頭辞と残りの値をアクセス トークンと解釈します。指定された接頭辞がヘッダーに存在しない場合、ポリシーはエラーをスローします。

AccessToken 要素を指定していて、AccessTokenPrefix 要素を指定しない場合、ポリシーは AccessToken 要素内で指定された変数の値全体をアクセス トークンとして解釈します。

この要素は、AccessToken 要素も使用されている場合にのみ有効になります。

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

JWT アクセス トークンの署名に使用される暗号化アルゴリズムを指定します。RSA（RS*）アルゴリズムは公開鍵 / 秘密鍵ペアを使用し、HMAC（HS*）アルゴリズムは共有シークレットを使用します。この要素は、GenerateJWTAccessToken、VerifyJWTAccessToken、RefreshJWTAccessToken のオペレーションに必要です。

<AppEndUser> 要素

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

アプリ エンドユーザー ID を認可サーバーに送信する必要がある場合、この要素を使用すると、エンドユーザー ID をどこで探すかを Apigee に指示できます。この ID は、たとえばクエリ パラメータとして、または HTTP ヘッダーに含めて送信できます。

たとえば、request.queryparam.app_enduser は AppEndUser がクエリ パラメータとして存在する必要があることを示します（例: ?app_enduser=ntesla@theramin.com）。たとえば、HTTP ヘッダーでその AppEndUser を要求するには、この値を request.header.app_enduser に設定します。

この設定を指定すると、アプリ エンドユーザー ID をアクセス トークンに含めることができます。この機能は、エンドユーザー ID で OAuth 2.0 アクセス トークンを取得または取り消す場合に便利です。詳細については、エンドユーザー ID、アプリ ID、またはこの両方を使用して OAuth 2.0 アクセス トークンの取得と取り消しを可能にするをご覧ください。

<Attributes/Attribute>

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

この要素は、アクセス トークンまた認可コードにカスタム属性を追加する場合に使用します。たとえば、実行時に抽出と確認ができるユーザー ID またはセッション識別子をアクセス トークンに埋め込む場合などです。

この要素を使用すると、フロー変数やリテラル文字列から値を指定できます。変数と文字列の両方を指定すると、フロー変数で指定された値が使用されます。変数を解決できない場合は、文字列がデフォルトとして使用されます。

この要素の使用方法について詳しくは、トークンと認証コードのカスタマイズをご覧ください。

レスポンスでカスタム属性を表示または非表示にする

このポリシーの GenerateResponse 要素を true に設定すると、設定したカスタム属性を含む、トークン内の完全な JSON 表現が返されます。場合によっては、レスポンス内のカスタム属性の一部またはすべてを非表示にして、クライアント アプリに表示されないようにすることもできます。

デフォルトでは、カスタム属性がレスポンスで表示されます。非表示にする場合は、display パラメータを false に設定します。例:

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

display 属性の値は保持されません。たとえば、レスポンスでカスタム属性が非表示になるように指定してアクセス トークンを生成するとしましょう。display=false を設定すると、その目標を達成できます。しかし、リフレッシュ トークンを使用して後から新しいアクセス トークンを生成すると、アクセス トークンの元のカスタム属性がリフレッシュ トークンのレスポンスで表示されます。これは、Apigee がアクセス トークンの生成ポリシーで display 属性が最初に false に設定されたことを覚えていないためです。カスタム属性は単にアクセス トークンのメタデータの一部です。

認証コードにカスタム属性を追加した場合にも同じ動作が見られます。そのコードを使用してアクセス トークンを生成すると、それらのカスタム属性がアクセス トークンのレスポンスで表示されます。これもユーザーの意図する動作ではないかもしれません。

このような場合にカスタム属性を非表示にする選択肢は、次のとおりです。

• リフレッシュ トークン ポリシーのカスタム属性を明示的にリセットし、表示を false に設定します。この場合、GetOAuthV2Info ポリシーを使用して、元のアクセス トークンから元のカスタム値を取得する必要が生じることがあります。
• 後処理の JavaScript ポリシーを使用して、レスポンスに表示しない任意のカスタム属性を手動で抽出します。

トークンと認証コードのカスタマイズもご覧ください。

<CacheExpiryInSeconds> 要素

<CacheExpiryInSeconds ref="propertyset.settings.token-ttl">60</CacheExpiryInSeconds>

この要素は VerifyAccessToken オペレーションでのみ使用できます。特定のポリシー実行のアクセス トークン キャッシュの有効期間（TTL）を指定します。Apigee が OAuth 2 アクセス トークンを初めて検証する場合は、永続ストアからアクセス トークンを取得する必要があります。これは比較的コストの高いオペレーションであるため、Apigee はトークンの検索結果（トークンのステータス、トークンが有効なプロダクトのリスト、トークンに適用されているカスタム属性など）をキャッシュに保存します。TTL が切れるまで OAuthV2/VerifyAccessToken を呼び出すと、メモリ内のキャッシュに保存された結果が読み込まれるため、トークンの検証が大幅に高速化されます。

アクセス トークン キャッシュのデフォルトの TTL は 180 秒です。この要素を使用すると、TTL を短縮して、パフォーマンスと正確性のバランスを取ることができます。トークンを無効にすることがある場合に、無効になったトークンを Apigee が有効なまま扱う期間を短縮する場合に、この設定が有効です。

サポートされる値の範囲は 1 ～ 180 秒です。フロー変数とデフォルト値を指定できます。フロー変数を指定し、その変数に数値が含まれている場合、その値は指定されたデフォルト値よりも優先されます。

属性

次の表に、<CacheExpiryInSeconds> 要素の属性を示します。

<ClientId> 要素

<ClientId>request.formparam.client_id</ClientId>

場合によっては、クライアント アプリからクライアント ID を認可サーバーに送信する必要があります。この要素は、Apigee がフロー変数 request.formparam.client_id でクライアント ID を検索することを指定します。ClientId を他の変数に設定することはできません。OAuth 2.0 トークンの取得もご覧ください。

<Code> 要素

<Code>request.queryparam.code</Code>

認可権限付与タイプのフローでは、クライアントが認可コードを認可サーバー（Apigee）に送信する必要があります。この要素を使用すると、認可コードをどこで探すかを Apigee に指示できます。たとえば、クエリ パラメータ、HTTP ヘッダー、フォーム パラメータ（デフォルト）として送信できます。

変数 request.queryparam.auth_code は、認可コードがクエリ パラメータとして存在する必要があることを示します（例: ?auth_code=AfGlvs9）。たとえば、HTTP ヘッダーで認証コードを要求するには、この値を request.header.auth_code に設定します。OAuth 2.0 トークンの取得もご覧ください。

<ExpiresIn> 要素

<ExpiresIn>10000</ExpiresIn>

アクセス トークンと認可コードの有効期限を、ミリ秒単位で適用します（更新トークンの場合は、<RefreshTokenExpiresIn> を使用します）。有効期限の値は、システムが生成した値に <ExpiresIn> 値を加えた値です。<ExpiresIn> が -1 に設定されている場合、トークンまたはコードは OAuth アクセス トークンの最大有効期限に従って期限切れになります。<ExpiresIn> が指定されていない場合、システムはシステムレベルで構成されたデフォルト値を適用します。

ハードコードされたデフォルト値を使用するか、フロー変数を参照することで、実行時に有効期限を動的に設定することもできます。たとえばトークン有効期限値を Key-Value マップに格納し、取得し、変数に割り当て、ポリシーで参照できます。例: kvm.oauth.expires_in。

Apigee では、以下のエンティティはアクセス後最低 180 秒間、キャッシュに保持されます。

• OAuth アクセス トークン。つまり、OAuth v2 ポリシーの ExpiresIn 要素によって、アクセス トークンを 180 秒未満で期限切れにすることはできません。
• Key Management Service（KMS）エンティティ（アプリ、デベロッパー、API プロダクト）。
• OAuth トークンと KMS エンティティのカスタム属性。

次のスタンザでは、フロー変数とデフォルト値も指定しています。フロー変数の値は、指定されたデフォルト値より優先される点に注意してください。

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

Apigee では、トークンの作成後にトークンを強制的に有効期限切れにする方法をサポートしていません。トークンを（たとえば、条件に基づいて）強制的に有効期限切れにする必要がある場合に適用可能なソリューションについては、こちらの Apigee コミュニティの投稿をご覧ください。

デフォルトでは、期限切れのアクセス トークンは、有効期限の 3 日後に自動的に Apigee システムからパージされます。アクセス トークンのパージもご覧ください。

<ExternalAccessToken> 要素

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

外部アクセス トークン（Apigee によって生成されないアクセス トークン）を探す場所を Apigee に指示します。

変数 request.queryparam.external_access_token は、外部アクセス トークンがクエリ パラメータ（?external_access_token=12345678 など）として存在する必要があることを示します。たとえば、HTTP ヘッダーで外部アクセス トークンを要求するには、この値を request.header.external_access_token に設定します。サードパーティ OAuth トークンの使用もご覧ください。

<ExternalAuthorization> 要素

<ExternalAuthorization>true</ExternalAuthorization>

この要素が false であるか存在しない場合、Apigee は通常、Apigee 認証ストアに対して client_id と client_secret を検証します。この要素は、サードパーティの OAuth トークンを操作する場合に使用します。この要素の使用方法については、サードパーティ OAuth トークンの使用をご覧ください。

<ExternalAuthorizationCode> 要素

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

外部認証コード（Apigee で生成されない認証コード）を探す場所を Apigee に指示します。

変数 request.queryparam.external_auth_code は、外部認証コードがクエリ パラメータ（?external_auth_code=12345678 など）として存在する必要があることを示します。たとえば、HTTP ヘッダーで外部認可コードを要求するには、この値を request.header.external_auth_code に設定します。サードパーティ OAuth トークンの使用もご覧ください。

<ExternalRefreshToken> 要素

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

外部更新トークン（Apigee によって生成されない更新トークン）を探す場所を Apigee に指示します。

変数 request.queryparam.external_refresh_token は、外部更新トークンがクエリ パラメータ（?external_refresh_token=12345678 など）として存在する必要があることを示します。たとえば、HTTP ヘッダーで外部リフレッシュ トークンを要求するには、この値を request.header.external_refresh_token に設定します。サードパーティ OAuth トークンの使用もご覧ください。

<GenerateResponse> 要素

<GenerateResponse enabled='true'/>

true に設定する場合、または enabled 属性を省略した場合、ポリシーはレスポンスを生成して返します。たとえば、GenerateAccessToken の場合、レスポンスは次のようになります。

{
  "issued_at" : "1467841035013",
  "scope" : "read",
  "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930",
  "refresh_token_issued_at" : "1467841035013",
  "status" : "approved",
  "refresh_token_status" : "approved",
  "api_product_list" : "[Product1, nhl_product]",
  "expires_in" : "1799",
  "developer.email" : "edward@slalom.org",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

false に設定した場合、または <GenerateResponse> 要素を省略した場合、レスポンスは送信されません。代わりに、ポリシーの機能に関連する値が一連のフロー変数に挿入されます。たとえば oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code というフロー変数に、新たに作成された認証コードが挿入されます。レスポンスで expires_in は秒単位で表現されます。

<GenerateErrorResponse> 要素

<GenerateErrorResponse enabled='true'/>

true に設定すると、ContinueOnError 属性が true に設定されている場合、ポリシーはレスポンスを生成して返します。false（デフォルト）の場合、レスポンスは送信されません。代わりに、ポリシーの機能に関連する値が一連のフロー変数に挿入されます。

<GrantType>

<GrantType>request.queryparam.grant_type</GrantType>

渡される権限付与タイプ パラメータをリクエストのどこで探すかをポリシーに指示します。OAuth 2.0 仕様では、アクセス トークンや認可コードのリクエストには権限付与タイプを含めなければなりません。変数として設定できるのは、ヘッダー、クエリ パラメータ、またはフォーム パラメータ（デフォルト）です。

たとえば、request.queryparam.grant_type はパスワードがクエリ パラメータ（?grant_type=password など）として存在する必要があることを示します。 たとえば、HTTP ヘッダーで権限付与タイプを要求するには、この値を request.header.grant_type に設定します。OAuth 2.0 トークンの取得もご覧ください。

<Operation> 要素

<Operation>GenerateAuthorizationCode</Operation>

ポリシーによって実行される OAuth 2.0 オペレーション。

<PassWord> 要素

<PassWord>request.queryparam.password</PassWord>

この要素はパスワード権限付与タイプでのみ使用されます。パスワード権限付与タイプでは、ユーザー認証情報（パスワードとユーザー名）を OAuthV2 ポリシーで使用できるようにする必要があります。<PassWord> 要素と <UserName> 要素は、Apigee でこれらの値を見つけることができる変数を指定するために使用されます。これらの要素が指定されていない場合、ポリシーは username と password という名前のフォーム パラメータで値を検出（デフォルト）することを想定しています。値が見つからない場合、ポリシーはエラーを返します。<PassWord> 要素と <UserName> 要素を使用して、認証情報を含むフロー変数を参照できます。

たとえば、クエリ パラメータを使用してトークン リクエストでパスワードを渡し、<PassWord>request.queryparam.password</PassWord>. のような要素を設定できます。HTTP ヘッダーでパスワードを要求するには、この値を request.header.password に設定します。

OAuthV2 ポリシーは、これらの認証情報の値を使用して他に何も行いません。Apigee ではそれらの値が存在することの検証のみを行います。API デベロッパーは、トークン生成ポリシーの実行前に値のリクエストを取得し、ID プロバイダに送信する必要があります。

OAuth 2.0 トークンの取得もご覧ください。

<PrivateKey>/<Value>

<PrivateKey>
  <Value ref="variable-name-here"/>
</PrivateKey>

RSA アルゴリズムで JWT 形式のアクセス トークンの検証または署名に使用する秘密鍵を提供します。ref 属性を使用して、鍵をフロー変数に渡します。Algorithm 要素の値が RS256、RS384、RS512 のいずれかの場合にのみ使用します。詳しくは、JWT OAuth トークン オペレーションの使用をご覧ください。

<PublicKey>/<Value>

<PublicKey>
   <Value ref="variable-name-here"/>
</PublicKey>

RSA アルゴリズムで署名された JWT 形式のアクセス トークンの署名を検証するために使用される公開鍵または公開証明書を指定します。ref 属性を使用して鍵または証明書をフロー変数に渡します。Algorithm 要素の値が RS256、RS384、RS512 のいずれかの場合にのみ使用します。

<RedirectUri> 要素

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

リクエスト内で Apigee が redirect_uri パラメータを探す場所を指定します。

リダイレクト URI について

リダイレクト URI は、認証コードと暗黙の権限付与タイプで使用されます。リダイレクト URI により、認証コード（認証コード権限付与タイプの場合）またはアクセス トークン（暗黙的権限付与タイプの場合）を送信する場所を認証サーバー（Apigee）に伝えます。このパラメータが必須の場合、省略可能な場合、また使用方法を理解することが重要です。

• （必須）リクエストのクライアント キーに関連付けられているデベロッパー アプリにコールバック URL が登録されており、かつ、redirect_uri がリクエスト内に存在する場合、この 2 つは正確に一致する必要があります。一致しない場合は、エラーが返されます。Apigee でデベロッパー アプリを登録する方法とコールバック URL の指定については、アプリの登録と API キーの管理をご覧ください。

• （省略可）コールバック URL が登録されており、redirect_uri がリクエスト内にない場合、Apigee は登録されたコールバック URL にリダイレクトします。
• （必須）コールバック URL が登録されていない場合、redirect_uri は必須です。この場合、Apigee は任意の URL を受け入れることにご注意ください。このケースではセキュリティ上の問題が発生する可能性があるため、信頼できるクライアント アプリでのみ使用してください。信頼できるクライアント アプリでない場合は、常にコールバック URL の登録を要求することをおすすめします。

このパラメータは、クエリ パラメータやヘッダーに含めて送信できます。変数 request.queryparam.redirect_uri は、RedirectUri が ?redirect_uri=login.myapp.com などのクエリ パラメータとして存在する必要があることを示します。たとえば、HTTP ヘッダーで RedirectUri 状態を要求するには、この値を request.header.redirect_uri に設定します。OAuth 2.0 トークンの取得もご覧ください。

<RefreshToken> 要素

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

リフレッシュ トークンを使用してアクセス トークンをリクエストするときは、リクエストにリフレッシュ トークンを含める必要があります。この要素を使用すると、Apigee がリフレッシュ トークンを検索する場所を指定できます。たとえば、クエリ パラメータ、HTTP ヘッダー、フォーム パラメータ（デフォルト）として送信できます。

変数 request.queryparam.refreshtoken は、更新トークンがクエリ パラメータ（?refresh_token=login.myapp.com など）として存在する必要があることを示します。たとえば、HTTP ヘッダーで RefreshToken を要求するには、この値を request.header.refresh_token に設定します。OAuth 2.0 トークンの取得もご覧ください。

<RefreshTokenExpiresIn> 要素

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

更新トークンの有効期限をミリ秒単位で適用します。有効期限の値は、システムが生成した値に <RefreshTokenExpiresIn> の値を加えたものです。<RefreshTokenExpiresIn> が -1 に設定されている場合、更新トークンは OAuth 更新トークンの有効期限に従って期限切れになります。<RefreshTokenExpiresIn> が指定されていない場合は、デフォルト値が適用されます。

ハードコードされたデフォルト値を使用するか、フロー変数を参照することで、実行時に有効期限を動的に設定することもできます。たとえばトークン有効期限値を Key-Value マップに格納し、取得し、変数に割り当て、ポリシーで参照できます。例: kvm.oauth.expires_in。

次のスタンザでは、フロー変数とデフォルト値も指定しています。フロー変数の値は、指定されたデフォルト値より優先される点に注意してください。

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    86400000 <!--value in milliseconds-->
</RefreshTokenExpiresIn>

<ResponseType> 要素

<ResponseType>request.queryparam.response_type</ResponseType>

この要素は、Apigee に対し、クライアント アプリがどの権限付与タイプを要求しているかを通知します。認可コード付与タイプや暗黙権限付与タイプでのみ使用します。

デフォルトでは、Apigee は response_type クエリ パラメータでレスポンス型の値を検索します。このデフォルトの動作をオーバーライドする場合は、<ResponseType> 要素を使用してレスポンス タイプの値を含むフロー変数を構成します。たとえば、この要素を request.header.response_type に設定した場合、Apigee はリクエスト ヘッダーで渡されるレスポンス タイプを探します。OAuth 2.0 トークンの取得もご覧ください。

<ReuseRefreshToken> 要素

<ReuseRefreshToken>true</ReuseRefreshToken>

true に設定すると、既存の更新トークンは有効期限切れになるまで再利用されます。false の場合は、有効な更新トークンが提示されると、Apigee によって新しい更新トークンが発行されます。

<RFCCompliantRequestResponse> 要素

<RFCCompliantRequestResponse>[true | false]</RFCCompliantRequestResponse>

true の場合、ポリシーは RFC6749 標準に準拠し、次のような準拠動作を有効にします。

• エラーおよびエラー以外のレスポンスには、RFC2616（Hypertext Transfer Protocol-HTTP / 1.1）に準拠するために HTTP Cache-Control レスポンス ヘッダー フィールドが含まれます。同様に、トークン、認証情報、またはその他の機密情報を含むレスポンスには値 no-store が、Pragma レスポンス ヘッダー フィールドには値 no-cache が含まれます。
• expires_in プロパティは英数字の形式になります。整合性を維持するため、refresh_token_expires_in も英数字になります。
• トークン生成の OAuthV2 レスポンスには、BearerToken ではなく RFC 準拠の Bearer ヘッダー フィールドが含まれます。
• レスポンス ペイロードのエラー メッセージは、更新トークン エラーの場合、{"error" : "xxx", "error_description" :"yyy"} の形式です。

<SecretKey>/<Value>

<SecretKey>
  <Value ref="your-variable-name"/>
</SecretKey>

JWT 形式のアクセス トークンを HMAC アルゴリズムで検証または署名するために使用される秘密鍵を提供します。アルゴリズムが HS256、HS384、HS512 のいずれかである場合にのみ使用します。ref 属性を使用して、鍵をフロー変数に渡します。詳しくは、JWT OAuth トークン オペレーションの使用をご覧ください。

Apigee は、HS256 / HS384 / HS512 アルゴリズムに対して最小限の鍵強度を適用します。鍵の最小長は、HS256 では 32 バイト、HS384 では 48 バイト、HS512 では 64 バイトです。強度の低い鍵を使用すると実行時エラーが発生します。

<Scope> 要素

<Scope>request.queryparam.scope</Scope>

この要素が GenerateAccessToken ポリシーか GenerateAuthorizationCode ポリシーのいずれかに存在する場合、トークンやコード権限を付与するスコープを指定するために使用されます。これらの値は通常、クライアント アプリからのリクエストでポリシーに渡されます。この要素がフロー変数を取るように構成して、リクエストでスコープを渡す方法を選択できます。次の例では、request.queryparam.scope はスコープがクエリ パラメータとして存在する必要があることを示します（例: ?scope=READ）。たとえば、HTTP ヘッダーでスコープを要求するには、この値を request.header.scope に設定します。

この要素が「VerifyAccessToken」ポリシー内にある場合、ポリシーが適用するスコープを指定するために使用されます。このタイプのポリシーでは、値は「ハードコードされた」スコープ名である必要があります。変数は使用できません。次に例を示します。

<Scope>A B</Scope>

OAuth2 スコープの使用と OAuth 2.0 トークンのを取得するもご覧ください。

<State> 要素

<State>request.queryparam.state</State>

クライアント アプリから認可サーバーに状態情報を送信する必要がある場合、この要素を使用すると、状態値をどこで探すかを Apigee に指示できます。たとえば、クエリ パラメータとして、または HTTP ヘッダーで送信できます。状態値は通常、CSRF 攻撃を防ぐセキュリティ対策として使用されます。

たとえば、request.queryparam.state は状態がクエリ パラメータとして存在する必要があることを示します（例: ?state=HjoiuKJH32）。たとえば、HTTP ヘッダーで状態を要求するには、この値を request.header.state に設定します。OAuth 2.0 トークンの取得もご覧ください。

<StoreToken> 要素

 <StoreToken>true</StoreToken>

<ExternalAuthorization> 要素が true の場合、この要素を true に設定します。<StoreToken> 要素は、外部アクセス トークンを保存するように Apigee に指示します。それ以外の場合、外部アクセス トークンは維持されません。

<SupportedGrantTypes>/<GrantType> 要素

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

Apigee の OAuth トークン エンドポイントでサポートされる権限付与タイプを指定します。1 つのエンドポイントで、複数の権限付与タイプがサポートされます（つまり、複数の権限付与タイプのアクセス トークンを配布するように、1 つのエンドポイントを構成できます）。エンドポイントの詳細については、OAuth エンドポイントについてをご覧ください。権限付与タイプは、grant_type パラメータのトークン リクエストで渡されます。

サポートされている権限付与タイプが指定されていない場合、許可される権限タイプは authorization_code と implicit のみです。<GrantType> 要素もご覧ください（これは、渡される grant_type パラメータをクライアント リクエストのどこで探すかを Apigee に指示するために使用する上位要素です。Apigee は、サポートされている権限付与タイプの 1 つと grant_type パラメータの値が一致することを確認します）。

<Tokens> / <Token> 要素

ValidateToken オペレーションと InvalidateToken オペレーションで使用します。アクセス トークンの承認と取り消しもご覧ください。<Token> 要素によって、取り消すトークンがどこに含まれているかを定義するフロー変数を識別します。たとえば、access_token という名前のクエリ パラメータとしてアクセス トークンを送信する必要がある場合は、request.queryparam.access_token を使用します。

<UserName> 要素

<UserName>request.queryparam.user_name</UserName>

この要素はパスワード権限付与タイプでのみ使用されます。パスワード権限付与タイプでは、ユーザー認証情報（パスワードとユーザー名）を OAuthV2 ポリシーで使用できるようにする必要があります。<PassWord> 要素と <UserName> 要素は、Apigee でこれらの値を見つけることができる変数を指定するために使用されます。これらの要素が指定されていない場合、ポリシーは username と password という名前のフォーム パラメータで値を検出（デフォルト）することを想定しています。値が見つからない場合、ポリシーはエラーを返します。<PassWord> 要素と <UserName> 要素を使用して、認証情報を含むフロー変数を参照できます。

たとえば、クエリ パラメータでユーザー名を渡し、次のように <UserName> 要素を <UserName>request.queryparam.username</UserName>. に設定できます。HTTP ヘッダーでユーザー名を要求するには、この値を request.header.username に設定します。

OAuthV2 ポリシーは、これらの認証情報の値を使用して他に何も行いません。Apigee ではそれらの値が存在することの検証のみを行います。API デベロッパーは、トークン生成ポリシーの実行前に値のリクエストを取得し、ID プロバイダに送信する必要があります。

OAuth 2.0 トークンの取得もご覧ください。

アクセス トークンの検証

API プロキシにトークン エンドポイントが設定されると、VerifyAccessToken オペレーションを指定する対応する OAuthV2 ポリシーが、保護されたリソースを公開するフローに添付されます。

たとえば、API へのリクエストがすべて認証されるようにするには、次のポリシーでアクセス トークンの検証を行います。

<OAuthV2 name="VerifyOAuthAccessToken">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

保護されている API リソースにこのポリシーが接続されます。API へのリクエストがすべての検証されるようにするには、このポリシーを次のように ProxyEndpoint リクエストの PreFlow に接続します。

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

次に示す省略可の要素を使用すると、VerifyAccessToken オペレーションのデフォルト設定をオーバーライドできます。

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>

アクセス トークンの検証と OAuth 2.0 トークンを取得するもご覧ください。

リクエスト変数の場所の指定

ポリシーは、権限付与タイプごとに、リクエスト メッセージ内の場所や必要な情報を推測します。この推測は、OAuth 2.0 仕様に基づいています。アプリが OAuth 2.0 仕様から外れる必要がある場合は、各パラメータについて想定される場所を指定できます。たとえば認可コードを処理するとき、認可コードの場所、クライアント ID、リダイレクト URI、スコープを指定できます。これらは、HTTP ヘッダー、クエリ パラメータ、またはフォーム パラメータとして指定できます。

次の例では、必要な認可コード パラメータの場所を HTTP ヘッダーとして指定する方法を示しています。

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.header.client_id</ClientId>
  <RedirectUri>request.header.redirect_uri</RedirectUri>
  <Scope>request.header.scope</Scope>
  ...

また、クライアント アプリ ベースをサポートする必要がある場合、ヘッダーとクエリ パラメータを組み合わせ、一致させることもできます。

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.queryparam.client_id</ClientId>
  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>
  <Scope>request.queryparam.scope</Scope>
  ...

パラメータごとに構成できる場所は 1 つのみです。

フロー変数

この表で定義されたフロー変数は、それぞれの OAuth ポリシーが実行されるときに設定されます。したがって、API プロキシフロー実行されている他のポリシーまたはアプリケーションで使用できます。

VerifyAccessToken オペレーション

VerifyAccessToken オペレーションが実行されると、多くのフロー変数がプロキシの実行コンテキストに設定されます。これらの変数は、アクセス トークン、デベロッパー アプリ、デベロッパーに関連するプロパティを提供します。AssignMessage ポリシーや JavaScript ポリシーなどを使用してこれらの変数を読み取り、必要に応じて後続のフローで使用できます。これらの変数は、デバッグの目的にも役立ちます。

トークン固有の変数

アプリ固有の変数

これらの変数は、トークンに関連付けられているデベロッパー アプリに関連します。

AppGroup 固有の変数

トークンの AppGroup に関する情報を含む次のフロー変数は、ポリシーによって設定されます。これらの AppGroup 属性は、verifyapikey.{policy_name}.app.appType が「AppGroup」の場合にのみ入力されます。

デベロッパー固有の変数

app.appType が「Developer」である場合、デベロッパー属性が事前入力されます。

GenerateAuthorizationCode オペレーション

これらの変数は、GenerateAuthorizationCode オペレーションが正常に実行されたときに設定されます。

接頭辞: oauthv2authcode.{policy_name}.{variable_name}

例: oauthv2authcode.GenerateCodePolicy.code

GenerateAccessToken オペレーションと RefreshAccessToken オペレーション

これらの変数は、GenerateAccessToken オペレーションと RefreshAccessToken オペレーションが正常に実行されたときに設定されます。リフレッシュ トークン変数は、クライアント認証情報の権限付与タイプのフローには適用されません。

接頭辞: oauthv2accesstoken.{policy_name}.{variable_name}

例: oauthv2accesstoken.GenerateTokenPolicy.access_token

GenerateAccessTokenImplicitGrant

これらの変数は、GenerateAccessTokenImplicit オペレーションが暗黙権限付与タイプのフローに対して正常に実行されたときに設定されます。

接頭辞: oauthv2accesstoken.{policy_name}.{variable_name}

例: oauthv2accesstoken.RefreshTokenPolicy.access_token

エラー リファレンス

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。

JWT トークン固有のランタイム エラー

JWT 認証トークンのランタイム エラーコードと説明は、OAuth2 フローのコンテキストによって異なります。

• フローのコンテキストがトークンの生成または更新の場合は、次の JWT トークンの生成フローと更新フローのエラーコードをご覧ください。
• トークン検証フローについては、次のトークン検証フローのエラーコードをご覧ください。

JWT トークンの生成フローと更新フローのエラーコード

JWT トークンを生成または更新する OAuth2 フローの場合、エラー レスポンスは RFC6749 で指定されているエラー レスポンスに従います。詳しくは、セクション 5.2 エラー レスポンスをご覧ください。

トークン検証フローのエラーコード

次の表に示すエラーコードは、VerifyAccessToken オペレーションにのみ適用されます。

デプロイエラー

以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。

JWT トークン固有のデプロイエラー

このデプロイエラーは、JWT トークン オペレーションを使用するポリシーに固有のエラーです。

障害変数

次の変数は、このポリシーでランタイム エラーが発生したときに設定されます。

エラー レスポンスの例

<GenerateResponse> 要素が true の場合、これらのレスポンスがクライアントに返されます。

<GenerateResponse> が true の場合、ポリシーはトークンとコードを生成するオペレーションに対して、次の形式のエラーを返します。一覧については、OAuth HTTP エラー レスポンス リファレンスをご覧ください。

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

<GenerateResponse> が true の場合、ポリシーは確認と検証のオペレーションに対して、次の形式のエラーを返します。一覧については、OAuth HTTP エラー レスポンス リファレンスをご覧ください。

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

障害ルールの例

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

ストレージ内のトークンのハッシュ化

Apigee ハイブリッドまたは Apigee を使用している場合、デフォルトでは、OAuthV2 アクセス トークンと更新トークンがランタイム Cassandra データベースに保存されるときにハッシュ化されます。ハッシュ化により、データベースが不正使用されたときにトークンの使用を防ぐことができます。

デフォルトの OAuth 構成の操作

Apigee における各組織（無料トライアル版の組織を含む）は、OAuth トークン エンドポイント付きでプロビジョニングされています。エンドポイントは、oauth という API プロキシのポリシーを使用して事前構成されています。Apigee でアカウントを作成するとすぐに、トークン エンドポイントの使用を開始できます。詳しくは、OAuth エンドポイントについてをご覧ください。

アクセス トークンのパージ

デフォルトでは、OAuth2 トークンは、アクセス トークンと更新トークン（存在する場合）の両方が期限切れになった 3 日（259,200 秒）後に Apigee システムから削除されます。

RFC に準拠していない動作

デフォルトでは、OAuthV2 ポリシーは GenerateAccessToken オペレーションで、トークンのレスポンスを返します。レスポンスには、RFC 準拠ではない特定のプロパティが含まれます。次の表に、OAuthV2 ポリシーによって返される非準拠プロパティと、対応する準拠プロパティを示します。

また、grant_type = refresh_token が以下の場合、期限切れのリフレッシュ トークンのエラー レスポンスは次のとおりです。

{"ErrorCode" : "invalid_request", "Error" :"Refresh Token expired"}

ただし、RFC 準拠のレスポンスは次のとおりです。

{"error" : "invalid_grant", "error_description" :"refresh token expired"}

関連トピック

• OAuth 2.0 の概要