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 プロキシをダウンロードします。

Cloud コンソールの Apigee

1. Google Cloud コンソールで、[プロキシ開発] > [API プロキシ] ページに移動します。

   [API プロキシ] に移動

   注: 続行する前に、API プロキシのリストを閲覧または検索してください。oauth という名前のプロキシがすでに存在する場合は、それをクリックして次のセクションまでスキップし、説明どおり構成されていることを確認します。内容が異なる場合は、削除してこれらの手順を続行するか、説明されている構成と一致するように変更してください。
2. [API Proxies] ペインで [+ Create] をクリックします。
3. [Create a proxy] ペインで、[Proxy template] の [Upload proxy bundle] を選択します。
4. ダウンロードした oauth.zip ファイルを選択し、[Next] をクリックします。
5. [Next] をクリックします。
6. Deploy（省略可）:
   • Deployment environments: 省略可。チェックボックスを使用して、プロキシをデプロイする環境を 1 つ以上選択します。この時点でプロキシをデプロイしない場合は、[Deployment environments] フィールドを空白のままにします。プロキシは、後でいつでもデプロイできます。
   • Service Account: 省略可。サービス アカウントをデプロイに関連付け、サービス アカウントのロールと権限で指定されているように、プロキシが Google Cloud サービスにアクセスできるようにします。
7. [Create] をクリックします。

従来の Apigee

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

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

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

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

Apigee Cloud コンソール

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

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

   

   左側のペインに 2 つのポリシーが表示されます。また、[Proxy Endpoints] セクションには、2 つの POST フローが表示されます。

2. [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 ポリシーを実行してアクセス トークンが生成されるという条件が定義されています。

3. 次に、条件付きフローによってトリガーされるポリシーを確認します。[Request] ペインで [GenerateAccessTokenClient] ポリシーをクリックします。

従来の Apigee

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

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

2. [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 ポリシーを実行してアクセス トークンが生成されるという条件が定義されています。

3. 次に、条件付きフローによってトリガーされるポリシーを確認します。フロー図の 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 プロキシの RefreshAccessToken のフローとポリシーは使用しません。またこれは、OAuth 2.0 クライアント認証情報の権限付与タイプではサポートされていません。

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

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

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

Cloud コンソールの Apigee

1. Google Cloud コンソールで、[プロキシ開発] > [API プロキシ] ページに移動します。

   [API プロキシ] に移動

2. [API Proxies] ペインで [+ Create] をクリックします。
3. [Create a proxy] ペインで、[Proxy template] の [Reverse proxy (most common)] を選択します。
4. プロキシを次のように構成します。
   

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

5. [Next] をクリックします。
6. Deploy (optional):
   • Deployment environments: 省略可。チェックボックスを使用して、プロキシをデプロイする環境を 1 つ以上選択します。この時点でプロキシをデプロイしない場合は、[Deployment environments] フィールドを空白のままにします。プロキシは、後でいつでもデプロイできます。
   • Service Account: 省略可。サービス アカウントをデプロイに関連付け、サービス アカウントのロールと権限で指定されているように、プロキシが Google Cloud サービスにアクセスできるようにします。
7. [Create] をクリックします。
8. helloworld_oauth2 プロキシの [Develop] タブをクリックします。
9. [Policies] セクションで、[ Add policy] をクリックします。
10. [Create policy] ペインで、[OAuth 2.0] を選択します。
11. [Create] をクリックします。

従来の Apigee

1. Apigee UI に移動し、ログインして Apigee 組織を選択します。
2. 左側のナビゲーション バーで [Develop] > [API Proxies] を選択します。
3. [CREATE NEW] をクリックします。
   
4. [Build a Proxy] ウィザードで、[Reverse proxy（most common）] を選択します。
5. プロキシを次のように構成します。
   

   フィールド	操作内容
   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」と入力します。

6. [Next] をクリックします。
7. [Common policies] ページで、次の操作を行います。

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

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

ポリシーを表示する

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

Apigee Cloud コンソール

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

2. 右側のペインにある [Verify OAuth v2.0 Access Token] アイコンをクリックし、テキスト エディタでその下にある XML を確認します。

従来の Apigee

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

2. フロービューで 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 エンティティを作成する必要があります。

1. API プロダクトを作成します。

Cloud コンソールの Apigee

Google Cloud コンソールで、[配布] > [API プロダクト] ページに移動します。

[API プロダクト] に移動

従来の Apigee

Apigee UI で、[Publish] > [API products] に移動します。

2. [+ Create] をクリックします。
3. [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	このチュートリアルでは無視します。

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

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

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

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

デベロッパーを作成する

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

Cloud コンソールの Apigee

1. デベロッパー エディタを開きます。

2. Google Cloud コンソールで、[配布] > [デベロッパー] ページに移動します。

   [デベロッパー] に移動

3. [+ Create] をクリックします。
4. [Add Developer] ウィンドウで、次のように入力します。
   

   フィールド	入力
   First Name	Nigel
   Last Name	Tufnel
   Email	[e-mail]
   Username	nigel

5. [Add] をクリックします。

従来の Apigee

1. デベロッパー エディタを開きます。

2. Apigee UI で、[Publish] > [Developers] に移動します。

3. [+ Developer] をクリックします。
4. [Create a Developer] ウィンドウで、次のように入力します。
   

   フィールド	入力
   First Name	Nigel
   Last Name	Tufnel
   Email	[e-mail]
   Username	nigel

5. [Create] をクリックします。

アプリを登録する

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

Cloud コンソールの Apigee

1. Google Cloud コンソールで、[配布] > [アプリ] ページに移動します。

   [アプリ] に移動

2. [+ Create] をクリックします。
3. [New App] ウィンドウで、次のように入力します。
   

   フィールド	操作内容
   Name と Display Name	「nigel_app」と入力します。
   Developer	[Developer] をクリックし、Nigel Tufnel ([e-mail]) を選択します。
   Callback URL と Notes	空白のまま

4. [+ Add Credentials] をクリックします。
5. [+ Add Products] をクリックします。
6. 作成した API プロダクトを選択します。
7. [Add] をクリックします。
8. [Create] をクリックします。

従来の Apigee

1. Apigee UI で、[Publish] > [Developers] に移動します。

2. [+ Developer] をクリックします。
3. [+ App] をクリックします。
4. [New App] ウィンドウで、次のように入力します。
   

   フィールド	操作内容
   Name と Display Name	「nigel_app」と入力します。
   Developer	[Developer] をクリックし、Nigel Tufnel ([e-mail]) を選択します。
   Callback URL と Notes	空白のまま

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

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

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

1. [nigel_app] ページを開きます。

Cloud コンソールの Apigee

1. [nigel_app] ページが表示されていることを確認します。表示されていない場合は、[配布] > [アプリ] ページに移動します。

   [アプリ] に移動

2. [nigel_app] ページで、[Key] 列と [Secret] 列の をクリックします。キー / シークレットは、先ほど作成した API プロダクトに関連付けられていることに注意してください。

従来の Apigee

1. [nigel_app] ページが表示されていることを確認します。表示されていない場合は、[Apps] ページ（[Publish] > [Apps]）で [nigel_app] をクリックします。

2. [nigel_app] ページで、[Key] 列と [Secret] 列の [Show] をクリックします。キー / シークレットは、先ほど作成した API プロダクトに関連付けられていることに注意してください。

2. [Key] と [Secret] の値を選択してコピーします。一時的なテキスト ファイルに貼り付けます。これらは後のステップで使用します。そのステップで 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" : "[e-mail]",
  "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 ホーム
• OAuthV2 ポリシー
• API プロキシのダウンロード（ZIP ファイルのダウンロードなど、API プロキシを ZIP ファイルにバンドルする方法を説明します）