OAuth 2.0 で API を保護する

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

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

このチュートリアルでは、OAuth 2.0 アクセストークンを使用して API プロキシを保護する方法を説明します。

始める前に

このチュートリアルを完了するには、次の権限を持つ Apigee 組織にアクセスできる必要があります。

API プロキシの作成とデプロイ
API プロダクトを作成する
デベロッパーアプリを作成する

また、Apigee API プロキシ呼び出しに使用できる、適切に構成された環境グループのホスト名が必要です。使用する環境グループのホスト名がわからない場合は、Apigee 管理者にお問い合わせください。

OAuth 2.0 プロキシをデプロイする

OAuth 2.0 アクセストークンを生成するように構成された API プロキシを GitHub で提供しています。この API プロキシをダウンロードして環境にデプロイする手順は次のとおりです。

ファイルシステム上のディレクトリに oauth サンプル API プロキシをダウンロードします。
Apigee UI に移動し、ログインして Apigee 組織を選択します。
左側のナビゲーションバーで [Develop] > [API Proxies] を選択します。
注: 続行する前に、API プロキシのリストを閲覧または検索してください。oauth という名前のプロキシがすでに存在する場合は、それをクリックして次のセクションまでスキップし、説明どおり構成されていることを確認します。内容が異なる場合は、削除してこれらの手順を続行するか、説明されている構成と一致するように変更してください。
[CREATE NEW] をクリックします。
[Create Proxy] ウィザードで、[Upload proxy bundle] を選択します。
ダウンロードした oauth.zip ファイルを選択し、[Next] をクリックします。
[Create] をクリックします。
構築が完了したら、[Edit Proxy] をクリックして API プロキシエディタで新しいプロキシを表示します。
[Deploy] をクリックします。
デプロイ先のリビジョンと環境を選択します。[Service account] フィールドは空白のままで構いません。
[Deploy] をクリックします。

アクセストークンを生成する API プロキシをダウンロードして Apegee 組織に正常にデプロイしました。

OAuth 2.0 のフローとポリシーを表示する

OAuth 2.0 ポリシーの構成を確認します。

新しいプロキシエディタ

次は、API プロキシの内容を詳しく確認します。

API プロキシエディタで [Develop] タブをクリックします。

左側のペインに 2 つのポリシーが表示されます。また、[Proxy Endpoints] セクションには、2 つの POST フローが表示されます。
[Proxy Endpoints] で [AccessTokenClientCredential] をクリックします。テキストエディタに、AccessTokenClientCredential 条件付きフローの XML コードが表示されます。
```
<Flow name="AccessTokenClientCredential">
    <Description/>
    <Request>
        <Step>
            <Name>GenerateAccessTokenClient</Name>
        </Step>
    </Request>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/accesstoken") and (request.verb = "POST")</Condition>
</Flow>
```
フローとは、API プロキシの処理ステップです。この場合、フローは特定の条件を満たす場合にトリガーされます（「条件付きフロー」と呼ばれます）。<Condition> 要素には、/accesstoken リソースに対して API プロキシ呼び出しが行われ、かつリクエスト動詞が POST である場合に、GenerateAccessTokenClient ポリシーを実行してアクセストークンが生成されるという条件が定義されています。
次に、条件付きフローによってトリガーされるポリシーを確認します。[Request] ペインで [GenerateAccessTokenClient] ポリシーをクリックします。

従来バージョンのプロキシエディタ

次は、API プロキシの内容を詳しく確認します。

API プロキシエディタで [Develop] タブをクリックします。左側の [Navigator] ペインに 2 つのポリシーが表示されます。また、[Proxy Endpoints] セクションには、2 つの POST フローが表示されます。
[Proxy Endpoints] で [AccessTokenClientCredential] をクリックします。

XML コードビューに AccessTokenClientCredential という Flow が表示されます。
```
<Flow name="AccessTokenClientCredential">
    <Description/>
    <Request>
        <Step>
            <Name>GenerateAccessTokenClient</Name>
        </Step>
    </Request>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/accesstoken") and (request.verb = "POST")</Condition>
</Flow>
```
フローとは、API プロキシの処理ステップです。この場合、特定の条件が満たされるとフローがトリガーされます。<Condition> 要素には、/accesstoken リソースに対して API プロキシ呼び出しが行われ、かつリクエスト動詞が POST である場合に、GenerateAccessTokenClient ポリシーを実行してアクセストークンが生成されるという条件が定義されています。
次に、条件付きフローによってトリガーされるポリシーを確認します。フロー図の GenerateAccessTokenClient ポリシーのアイコンをクリックします。

次の XML 構成が表示されます。

<OAuthV2 name="GenerateAccessTokenClient">
    <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
    <Operation>GenerateAccessToken</Operation>
    <!-- This is in milliseconds, so expire in an hour -->
    <ExpiresIn>3600000</ExpiresIn>
    <SupportedGrantTypes>
        <!-- This part is very important: most real OAuth 2.0 apps will want to use other
         grant types. In this case it is important to NOT include the "client_credentials"
         type because it allows a client to get access to a token with no user authentication -->
        <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GrantType>request.queryparam.grant_type</GrantType>
    <GenerateResponse/>
</OAuthV2>

構成の内容は次のとおりです。

<Operation>（事前定義された値のいずれか）により、ポリシーの処理内容が定義されます。この場合はアクセストークンが生成されます。
トークンの有効期限は、生成後 1 時間（3,600,000 ミリ秒）です。
<SupportedGrantTypes> では、使用する OAuth 2.0 <GrantType> として client_credentials が指定されています（コンシューマキーおよびコンシューマシークレットと引き換えに OAuth 2.0 トークンが取得されます）。
2 番目の <GrantType> 要素では、OAuth 2.0 仕様によって要求されている権限付与タイプパラメータを API 呼び出しのどこで検索するかをポリシーに指示します（API 呼び出しのこの部分については、後で確認します）。権限付与タイプは、HTTP ヘッダー（request.header.grant_type）で送信することも、フォームパラメータ（request.formparam.grant_type）として送信することも可能です。

現時点では、API プロキシに対してその他の処理を実行する必要はありません。後のステップで、この API プロキシを使用して OAuth 2.0 アクセストークンを生成します。ただし、事前に次の作業を行う必要があります。

OAuth 2.0 で実際に保護する API プロキシを作成する。
アクセストークンを取得する際に引き換えとして必要になるコンシューマキーとコンシューマシークレットの生成に使用されるいくつかのアーティファクトを作成する。

保護された API プロキシを作成する

次に、保護する API プロキシを作成します。この API 呼び出しを通じて目的の情報が返されるようにします。この場合、API プロキシで Apigee の mocktarget サービスを呼び出すことによって、IP アドレスが返されるようにします。ただし、この情報が表示されるのは、API 呼び出しで有効な OAuth 2.0 アクセストークンを渡した場合のみです。

ここで作成する API プロキシには、リクエスト内の OAuth 2.0 トークンを検査するポリシーが組み込まれます。

左側のナビゲーションバーで [Develop] > [API Proxies] を選択します。
[CREATE NEW] をクリックします。
[Build a Proxy] ウィザードで、[Reverse proxy（most common）] を選択します。

プロキシを次のように構成します。

フィールド	操作
Proxy Name	`helloworld_oauth2` を入力します。
Project Base Path	`/hellooauth2` に変更します。 [Project Base Path] は、API プロキシに対してリクエストを行うために使用される URL の一部です。
Existing API	`https://mocktarget.apigee.net/ip` を入力します。 API プロキシへのリクエストに応じて Apigee が呼び出すターゲット URL を定義します。
Description	`hello world protected by OAuth 2.0` を入力します。

[Next] をクリックします。

[Common policies] ページで、次の操作を行います。

フィールド	操作
Security: Authorization	次のように選択します。 OAuth 2.0 これらのオプションはとても便利です。2 つのポリシーが API プロキシに自動的に追加され、API プロダクトが作成されます。

フィールド

操作

Security: Authorization

次のように選択します。

OAuth 2.0

これらのオプションはとても便利です。2 つのポリシーが API プロキシに自動的に追加され、API プロダクトが作成されます。

[Next] をクリックします。
[Summary] ページの [Optional Deployment] で環境を選択し、[Create and Deploy] をクリックします。
[Edit proxy] をクリックして、API プロキシの [Overview] ページを表示します。
API プロキシが自動的にデプロイされます。デプロイが完了するまでに少し時間がかかることがあります。

ポリシーを表示する

ここでは、作成した内容を詳しく確認します。

新しいプロキシエディタ

API プロキシエディタで [Develop] タブをクリックします。API プロキシのリクエストフローに次の 2 つのポリシーが追加されていることを確認します。
- Verify OAuth v2.0 Access Token - API 呼び出しを調べて有効な OAuth 2.0 トークンが存在することを確認します。
- Remove Header Authorization - ターゲットサービスに渡されないように、検査後のアクセストークンを削除する Assign Message ポリシーです（ターゲットサービスが OAuth 2.0 アクセストークンを必要とする場合は、このポリシーは使用しません）。
右側のペインにある [Verify OAuth v2.0 Access Token] アイコンをクリックし、テキストエディタでその下にある XML を確認します。

従来バージョンのプロキシエディタ

API プロキシエディタで [Develop] タブをクリックします。API プロキシのリクエストフローに次の 2 つのポリシーが追加されていることを確認します。
- Verify OAuth v2.0 Access Token - API 呼び出しを調べて有効な OAuth 2.0 トークンが存在することを確認します。
- Remove Header Authorization - ターゲットサービスに渡されないように、検査後のアクセストークンを削除する Assign Message ポリシーです（ターゲットサービスが OAuth 2.0 アクセストークンを必要とする場合は、このポリシーは使用しません）。
フロービューで Verify OAuth v2.0 Access Token のアイコンをクリックし、コードペインでその XML を確認します。

<OAuthV2 async="false" continueOnError="false" enabled="true" name="verify-oauth-v2-access-token">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

<Operation> が VerifyAccessToken になっていることに注意してください。Operation ではポリシーの処理内容が定義されます。この場合は、リクエスト内に有効な OAuth 2.0 トークンが存在するかどうかが確認されます。

API プロダクトを追加する

OAuth 2.0 アクセストークンを取得するには、API プロダクト、デベロッパー、デベロッパーアプリの 3 つの Apigee エンティティを作成する必要があります。まず、API プロダクトを作成します。

[Publish] > [API Products] を選択します。
[+Create] をクリックします。

[Product details] に、API プロダクトの詳細を入力します。

フィールド	説明
Name	API プロダクトの内部名。名前には特殊文字を使用しないでください。注: API プロダクトの作成後は、この名前を編集できません。
表示名	API プロダクトの表示名。表示名は UI で使用され、いつでも編集できます。指定しない場合、[Name] の値が使用されます。このフィールドには [Name] の値が自動的に入力されます。入力された値を編集または削除できます。表示名には特殊文字を含めることができます。
Description	API プロダクトの説明。
Environment	API プロダクトでのアクセス許可の対象となる環境。API プロキシをデプロイした環境を選択します。
Access	[Public] を選択します。
Automatically approve access requests	この API プロダクトに対する任意のアプリからのキーリクエストの自動承認を有効にします。
Quota	このチュートリアルでは無視します。
Allowed OAuth 2.0 Scopes	このチュートリアルでは無視します。

[Operations] セクションで、[Add an Operation] をクリックします。
[API Proxy] フィールドで、作成した API プロキシを選択します。
[Path] フィールドに「/」と入力します。他のフィールドは無視します。
[Save] をクリックして、オペレーションを保存します。
[Save] をクリックして、API プロダクトを保存します。

デベロッパーとアプリを組織に追加する

次に、デベロッパーが API の使用登録を行うためのワークフローをシミュレートします。デベロッパーは自分自身と自分のアプリをデベロッパーポータル経由で登録するのが理想的です。ただし、このステップでは管理者としてデベロッパーとアプリを追加します。

デベロッパーは API を呼び出す 1 つ以上のアプリを所有し、各アプリにはそれぞれ一意のコンシューマキーとコンシューマシークレットが割り当てられます。このようにアプリごとにキーとシークレットを使用することで、どのデベロッパーとアプリがどの OAuth 2.0 トークンに属しているかが Apigee でわかるようになるため、API プロバイダは API へのアクセスをより細かく制御でき、また API トラフィックに関するより詳細な分析レポートを作成できます。

デベロッパーを作成する

ここでは、Nigel Tufnel というデベロッパーを作成します。

メニューで [Publish] > [Developers] を選択します。
[+ Developer] をクリックします。

[New Developer] ウィンドウに次の情報を入力します。

フィールド	入力
First Name	`Nigel`
Last Name	`Tufnel`
Username	`nigel`
Email	`nigel@example.com`

[Save] をクリックします。

アプリを登録する

ここでは、Nigel 用のアプリを作成します。

[Publish] > [Apps] を選択します。
[+ App] をクリックします。

[New Developer App] ウィンドウに次の情報を入力します。

フィールド	操作
Name と Display Name	`nigel_app` を入力します。
Developer	[Developer] をクリックし、`Nigel Tufnel (nigel@example.com)` を選択します。
Callback URL と Notes	空白のまま

[Products] で [Add Product] をクリックします。
作成した API プロダクトを追加します。
[Create] をクリックします。

コンシューマキーとコンシューマシークレットを取得する

ここでは、OAuth 2.0 アクセストークンを取得する際に引き換えとして必要になるコンシューマキーとコンシューマシークレットを取得します。

[nigel_app] ページが表示されていることを確認します。表示されていない場合は、[Apps] ページ（[Publish] > [Apps]）で [nigel_app] をクリックします。
[nigel_app] ページで、[Key] 列と [Secret] 列の [Show] をクリックします。キー / シークレットは、先ほど作成した API プロダクトに関連付けられていることに注意してください。
キーとシークレットを選択してコピーします。一時的なテキストファイルに貼り付けます。これらは後のステップで使用します。そのステップで API プロキシを呼び出し、これらの認証情報と引き換えに OAuth 2.0 アクセストークンを取得します。

API を呼び出して IP アドレスを取得できるか試す（失敗）

作成し、保護された API プロキシを呼び出してみます。この呼び出しでは OAuth 2.0 アクセストークンを渡していないことに注意してください。

ここで、YOUR ENV_GROUP_HOSTNAME は環境グループのホスト名です。環境グループのホスト名を探すをご覧ください。

API プロキシに Verify OAuth v2.0 Access Token ポリシーが含まれており、リクエストに有効な OAuth 2.0 トークンがあるかどうかが検証されるため、この呼び出しは失敗し、次のメッセージが表示されます。

{"fault":{"faultstring":"Invalid access token","detail":{"errorcode":"oauth.v2.InvalidAccessToken"}}}

この場合は、失敗するのが正常です。つまり、API プロキシは厳格に保護されています。この API を正常に呼び出すことができるのは、有効な OAuth 2.0 アクセストークンを持つ信頼できるアプリのみです。

OAuth 2.0 アクセストークンを取得する

次に、コピーしてテキストファイルに貼り付けたキーとシークレットを OAuth 2.0 アクセストークンと交換します。ここでは、インポートした API サンプルプロキシ（oauth）に対して API 呼び出しを行い、API アクセストークンを生成します。

キーとシークレットを使用して、次の cURL 呼び出しを行います（プロトコルは https）。

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
"https://YOUR ENV_GROUP_HOSTNAME/oauth/client_credential/accesstoken?grant_type=client_credentials" \
-d "client_id=CLIENT_KEY&client_secret=CLIENT_SECRET"

Postman などのクライアントを使用して呼び出しを行う場合、client_id と client_secret はリクエストの本文に含めて、x-www-form-urlencoded にする必要があります。

次のようなレスポンスが得られるはずです。

{
  "issued_at" : "1466025769306",
  "application_name" : "716bbe61-f14a-4d85-9b56-a62ff8e0d347",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[helloworld_oauth2-Product]",
  "expires_in" : "3599", //--in seconds
  "developer.email" : "nigel@example.com",
  "token_type" : "BearerToken",
  "client_id" : "xNnREu1DNGfiwzQZ5HUN8IAUwZSW1GZW",
  "access_token" : "GTPY9VUHCqKVMRB0cHxnmAp0RXc0",
  "organization_name" : "myOrg",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

これで、OAuth 2.0 アクセストークンを取得できました。access_token 値（引用符なし）をコピーして、テキストファイルに貼り付けます。これはすぐに使用します。

ここでは、何が行われたのでしょうか。

前に確認した oauth プロキシの「条件付きフロー」により、リソース URI が /accesstoken で、リクエスト動詞が POST である場合に GenerateAccessTokenClient OAuth 2.0 ポリシーが実行され、アクセストークンが生成されます。使用した cURL コマンドはこの条件を満たすため、OAuth 2.0 ポリシーが実行されました。さらに、コンシューマキーとコンシューマシークレットが検証され、これらと引き換えに OAuth 2.0 トークンが取得されました。このトークンの有効期限は 1 時間です。

アクセストークンを使用して API を呼び出す（成功）

アクセストークンを取得したら、それを使用して API プロキシを呼び出すことができます。次の cURL 呼び出しを実行します。実際の Apigee 組織名とアクセストークンに置き換えてください。

curl https://YOUR ENV_GROUP_HOSTNAME/hellooauth2 -H "Authorization: Bearer TOKEN"

これで、API プロキシに対する呼び出しが成功し、IP アドレスが返されるはずです。次に例を示します。

{"ip":"::ffff:192.168.14.136"}

アクセストークンの有効期限が切れる 1 時間後までは、同じ API 呼び出しを繰り返すことができます。1 時間後に呼び出しを実行するには、上記の手順で新しいアクセストークンを生成する必要があります。

これで完了です。API プロキシが作成され、有効な OAuth 2.0 アクセストークンを呼び出しに含めるよう要求することでプロキシが保護されるようになりました。

OAuth 2.0 で API を保護する

始める前に

OAuth 2.0 プロキシをデプロイする

OAuth 2.0 のフローとポリシーを表示する

新しいプロキシ エディタ

従来バージョンのプロキシ エディタ

保護された API プロキシを作成する

ポリシーを表示する

新しいプロキシ エディタ

従来バージョンのプロキシ エディタ

API プロダクトを追加する

デベロッパーとアプリを組織に追加する

デベロッパーを作成する

アプリを登録する

コンシューマ キーとコンシューマ シークレットを取得する

API を呼び出して IP アドレスを取得できるか試す（失敗）

OAuth 2.0 アクセス トークンを取得する

アクセス トークンを使用して API を呼び出す（成功）

関連トピック

新しいプロキシエディタ

従来バージョンのプロキシエディタ

新しいプロキシエディタ

従来バージョンのプロキシエディタ

コンシューマキーとコンシューマシークレットを取得する

OAuth 2.0 アクセストークンを取得する

アクセストークンを使用して API を呼び出す（成功）