Was this helpful?

API keys provide a simple mechanism for authenticating apps. Apigee Edge generates API keys for apps, and enables you to add API key-based authentication to your APIs using policies. Using Apigee Edge, you can issue, administer and validate API keys without writing any code. This topic shows you how to add API key validation to an API. To learn about API key management, start with the Developer Services Overview of API publishing.

API keys go by many names. You may see them referred to as 'API keys', 'app keys', and 'consumer keys'. All of these names are synonymous.

When apps are registered with Edge Developer Services, a consumer key and secret pair is generated for the app. Edge API Services stores the consumer key for future validation. The app developer embeds the consumer key in the client app. The client app must present the consumer key for each request. API Services validates the consumer key before permitting the app's request.

API key validation is the simplest form of app-based security that you can configure for an API. Apps simply present an API key, and Apigee Edge checks to see that the API key is in an approved state for the resource being requested. For this reason the security associated with API keys is limited. API keys can easily be extracted from app code and used to access an API. You may find that API keys work better as unique app identifiers than as security tokens.

A working sample API proxy that enforces API key validation is available in the API Platform Samples available on Github. You can use the sample API proxy to secure your own API. Locate the API proxy found under /sample-proxies/apikey. Modify the TargetEndpoint configuration to point to your URL. Then deploy.

Policy configuration

You can set up API key validation for an API by attaching a policy of type ValidateAPIKey. The only required setting for a ValidateAPIKey policy is the expected location of the API key in the client request. The API proxy will check the location that you specify, and extract the API key. If the API key is not present in the expected location, then an error is thrown and the request is rejected. API keys can be located in a query parameter, a form parameter, or an HTTP header.

For example, the policy configuration below defines the expected key location as a query parameter named apikey. A successful request must present the API key as a query parameter appended to the request, for example,?apikey=Y7yeiuhcbKJHD790.

To validate API keys, create the following policy:

<VerifyAPIKey name="APIKeyValidation">
  <APIKey>request.queryparameter.apikey</APIKey>
</VerifyAPIKey>

This policy can be attached to any API that you need to protect.

API proxies automatically passthrough all HTTP headers and query parameters that are present on the request. Therefore, after the API key has been validated, it's a good idea to strip it from the message so that the API key is not sent over the wire to the backend service. You can do that using a policy of type AssignMessage as follows:

<AssignMessage name="StripApiKey">
    <DisplayName>Remove Query Param</DisplayName>
    <Remove>
        <QueryParams>
            <QueryParam name="apikey"/>
        </QueryParams>
    </Remove>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"></AssignTo>
</AssignMessage>

Policy attachment

The policies must be attached to an API proxy Flow as processing Steps. By applying the policy to the request PreFlow, API keys are verified on every request received by the API proxy from a client app. After verification, the API key is stripped from the outbound request.

Attach the policies to the ProxyEndpoint of the API proxy to be protected as follows:

<ProxyEndpoint name="default">
  <PreFlow>
    <Request>
      <Step><Name>ValidateAPIKey</Name></Step>
      <Step><Name>StripApiKey</Name></Step>
    </Request>
  </PreFlow>

After you attach the policy, deploy the API proxy.

Submitting a request with a valid API key

As an admin in your organization, you can retrieve any app's API key as follows:

$ curl https://api.enterprise.apigee.com/v1/o/{myorg}/developers/{developer_email}/apps/{app_name} -u myname:mypass 
Remember to substitute your organization for {myorg} and your username and password for myname:mypass.

The app profile that is returned for this call provides the consumer key (API key) and secret. The consumer key value is the value you use for the API key in your request to the protected API.

For example, a request that does not include an API key results in an authorization failure.

$ curl http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

The failure message indicates that the policy checked for an API key but did not find a valid key:

OAuth Failure : Could not resolve the app key with variable request.queryparam.apikey

When the consumer key for the app is included as a query parameter, the expected result is successful authorization:

$ curl http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282&"apikey=PulSCqMnXGchW0pC0s5o9ngHVTWMeLqk"

The expected result is a successful response from the weather service.

Modifying the value of the API key value in the request results in an authorization failure:

$ curl http://{org_name}-test.apigee.net/weather?forecastrss?w=12797282&"apikey=PulSCqMnXGchW0"

Results in:

OAuth Failure : Consumer Key is Invalid

Remember, as an admin for your organization, you can retrieve the consumer key for any app registered in an organization:

$ curl https://api.enterprise.apigee.com/v1/o/{myorg}/developers/{developer_email}/apps/{app_name} -u myname:mypass 

A tutorial that demonstrates step-by-step API key configuration is available. See Secure calls to your API through API key validation.

Get help

For help, see Apigee Customer Support.

コメント

Does apigee support LDAP? Do we have any tutorial on this?

LDAP is supported in On-premises deployments.

コメントを追加

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.