Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

Secure an API by requiring API keys

学習内容

このチュートリアルを通じて、以下のことを学びます。

  • Create an API proxy that requires an API key.
  • Add a developer and register an app.
  • Call your API with an API key.

It's important to protect your API from unauthorized access. One way to do that is with API keys (also called "public keys", "consumer keys" or "app keys").

アプリでは、API にリクエストを行うときに、有効なキーを提供する必要があります。Verify API Key ポリシーでは、実行時に提供された API キーを次の点に関して確認します。

  • API キーが有効であること
  • API キーが失効していないこと
  • API キーが、要求したリソースを公開する API 製品 (product) の API キーと一致していること

キーが有効である場合、リクエストは許可されます。キーが無効である場合は、リクエストは認証エラーになります。

In this tutorial, you'll create an API proxy that requires a valid API key to access it.

必要なもの

  • Apigee Edge アカウント。まだ持っていない場合は、「Apigee Edge アカウントの作成」の指示に従ってサインアップできます。
  • A web browser to make an API call.
  • (For the extra credit section, not required) cURL installed on your machine to make API calls from the command line.

API プロキシの作成

About the 'mocktarget'

The mocktarget service is hosted at Apigee and returns simple data. It requires no API key or access token. In fact, you can access it in a web browser. Try it out by clicking the following:

http://mocktarget.apigee.net

The target returns Hello, Guest!. Use the /help resource to get a help page of other API resources that are available

  1. Go to https://apigee.com/edge and log in. This is the New Edge experience UI. (You could also use the classic management UI, which has slightly different navigation. Both UIs create the proxy in your organization.)
  2. Switch to the organization you want by clicking your user name at the top of the side navigation bar to display the user profile menu, and then selecting t the organization from the list.
  3. Click API Proxies on the landing page to display the API proxies list.

  4. Click + Proxy.
  5. 「Build a Proxy」ウィザードで、「Reverse proxy (most common)」を選択し、「Next」をクリックします。
  6. Configure the proxy as follows:
    フィールド 操作内容
    Proxy Name Enter: helloworld_apikey
    Project Base Path

    Change to: /helloapikey

    The Project Base Path is part of the URL used to make requests to the API proxy.

    Note: For Apigee's recommendations on API versioning, see Versioning in the Web API Design: The Missing Link e-book.

    Existing API

    次のように入力します: http://mocktarget.apigee.net

    これは、Apigee Edge が API プロキシに対するリクエストで呼び出すターゲット URL を定義します。

    説明 Enter: hello world protected by API key
  7. 「Next」をクリックします。
  8. On the Security page:
    フィールド 操作内容
    Authorization Select the following options:
    • API Key
    • Publish API Product

    These options are very handy. They'll automatically add two policies to your API proxy and create an API product needed for generating the API key.

  9. 「Virtual Hosts」ページで、「Next」をクリックします。
  10. On the Build page, make sure the test deployment environment is selected, and click Build and Deploy.
  11. On the Summary page, you see an acknowledgment that your new API proxy and an API product were created successfully, and that the API proxy was deployed to your test environment.
  12. Click View the helloworld_apikey proxy in the editor to display the Overview page for the API proxy.

View the policies

  1. In the API proxy editor, click the Develop tab. You'll see that two policies have been added to the request flow of the API proxy:
    • Verify API Key – Checks the API call to make sure a valid API key is present (sent as a query parameter).
    • Remove Query Param apikey – An Assign Message policy that removes the API key after it's checked, so that it doesn't get passed around and exposed unnecessarily.
  2. Click the Verify API Key policy icon in the flow view, and look at the policy's XML configuration in the lower code view. The <APIKey> element tells the policy where it should look for the API key when the call is made. By default, it looks for the key as a query parameter called apikey in the HTTP request:

    <APIKey ref="request.queryparam.apikey" />
    

    The name apikey is arbitrary and can be any property that contains the API key.

Try to call the API

In this step, you'll make a successful API call directly to the target service, then you'll make an unsuccessful call the API proxy to see how it's being protected by the policies.

  1. Success

    In a web browser, go to the following address. This is the target service that the API proxy is configured to forward the request to, but you'll hit it directly for now:

    http://mocktarget.apigee.net

    You should get this successful response: Hello, Guest!

  2. Failure

    Now try to call your API proxy:

    http://{org-name}-test.apigee.net/helloapikey

    replacing {org-name} with the name of your Edge organization.

    Without the Verify API Key policy, this call would give you the same response as the previous call. But in this case, you should get the following error response:

    {"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

    which means, correctly, that you didn't pass a valid API key (as a query parameter).

In the next steps, you'll get the required API key.

About the API product

Without getting into too much detail for this tutorial, an API product in Edge (among other nifty features) generates API keys for developers; or more accurately, for the apps developers register with Edge.

If you're curious, you can view the API product that was automatically created when your API proxy was generated. Select Publish > API Products > helloworld_apikey-Product in the UI.

Notice that the Key Approval Type is Automatic. That means developers get an API key automatically when they register an app, as opposed to you manually approving keys before they're given to developers.

Moving on.

Add a developer and app to your organization

Next, we're going to simulate the workflow of a developer signing up to use your APIs. A developer will have one or more apps that call your APIs, and each app gets a unique API key. This gives you, the API provider, more granular control over access to your APIs and more granular reporting on API traffic by app.

Create a developer

To create a developer:

  1. Select Publish > Developers in the menu.
  2. Click + Developer.
  3. Enter the following in the New Developer window:
    フィールド enter
    First Name Keyser
    Last Name Soze
    Username keyser
    メール keyser@example.com
  4. 「Save」をクリックします。 

Register an app

To register a developer app:

  1. Select Publish > Apps.
  2. Click + App.
  3. Enter the following in the New Developer App window:
    フィールド 操作内容
    Name and Display Name Enter: keyser_app
    デベロッパ Select: Keyser Soze (keyser@example.com)
    Callback URL and Notes Leave blank
  4. Under Products, click + Product.
  5. Select helloworld_apikey-Product.
  6. 「Save」をクリックします。 

Get the API key

To get the API key:

  1. On the Apps page (Publish > Apps), click keyser_app.
  2. On the keyser_app page, click Show in the Consumer Key column. Notice that the key is associated with the "helloworld_apikey-Product".
  3. Select and copy the Consumer Key. You'll use it in the next step.

Call the API with a key

Now that you have an API key, you can use it to call the API proxy. Enter the following in your web browser. Substitute your Edge organization name for {org-name}, and paste the API (Consumer) key as shown, as a query parameter. Make sure there are no extra spaces in the query parameter.

http://{org-name}-test.apigee.net/helloapikey?apikey={paste_api_key_here}

Now when you call to the API proxy, you should get this response: Hello, Guest!

Congratulations! You've created an API proxy and protected it by requiring that a valid API key be included in the call.

Extra credit: Passing the key in the HTTP header

This step isn't required, but it gives you a different way that the API key can be provided: in the HTTP header instead of as a query parameter.

  1. Edit the API proxy. Select Develop > API Proxies > helloworld_apikey, and go to the Develop view.
  2. Select the Verify API Key policy, and modify the policy XML to tell the policy to look in the header rather than in the queryparam:

    <APIKey ref="request.header.apikey"/>
    
  3. Save the API proxy to deploy the change.
  4. Make the following API call using cURL to pass the API key as a header called apikey. Don't forget to substitute your organization name.

    curl -v -H "apikey: {api_key_goes_here}" http://{org-name}-test.apigee.net/helloapikey

Note that to fully complete the change, you'd also need to configure the Assign Message policy to remove the header instead of the query parameter.

You could also pass the API key as a form parameter. If you did, the Verify API Key policy would be configured like this:

<APIKey ref="request.formparam.apikey"/>

関連トピック

Here are some topics that directly relate to this tutorial:

Going a bit deeper, protecting APIs with API keys is only part of the story. Oftentimes, API protection involves additional security such as OAuth. Here are a couple of topics that describe other security features:

  • OAuth – OAuth is an open protocol that, in a nutshell, exchanges credentials (like username and password) for access tokens. Access tokens are long, random strings that can be passed around a message pipeline, even from app to app, without compromising the original credentials. Access tokens often have short lives, so new ones are always being generated.
  • StreetCarts project – Built on Apigee Edge, StreetCarts is a sample API for food trucks. It uses API proxies with API BaaS as a data store. Security includes API keys, OAuth, a vault to store credentials, and role-based access control.
  • For the rest, see the "Secure" section of the Apigee Edge documentation.

 

 

Help or comments?