security apikey apigee

Using API key authentication with the Apigee provider

This topic explains how to implement API key security in an a127 API using the Apigee security provider.

About API key security

API keys are used to validate that an API call is being made from a registered client app.

For API key security, a127 relies on either the a127-oauth-apigee or a127-oauth-redis provider. This topic explains how to use the Apigee provider. To read about the Redis provider, see Using API key authentication with the Redis provider.

The Apigee provider is a good choice if you want to deploy your API to Apigee Edge. With the Apigee provider, you can also run your API locally. The Redis provider works for locally deployed projects, and require access to a Redis database instance.

With API key security enabled, your API must be called with a valid API key. Depending on your configuration, it can be passed in a query param or a header. For example:

curl -i 'http://127.0.0.1:10010/hello?name=Scott&apiKey=f34RUcMxFGwTe6e5KnpZIJfTo2I'

OR --

curl -i 'http://127.0.0.1:10010/hello?name=Scott' -H 'X-API-KEY: f34RUcMxFGwTe6e5KnpZIJfTo2I'

Step by step configuration

1. If you do not have one already, create an a127 account and project. If you intend to use the Apigee provider, be sure to select apigee when you create the account:

   a127 account create myaccount

   a127 project create myproject

2. If you have not done so, create a RemoteProxy service and bind it to your project. See also Understanding remote services.

   a127 service create myremoteservice

   a127 project bind myremoteservice

3. Add required key and uri parameters to x-a127-config in the api/swagger/swagger.yaml file. Be sure to use the name of the RemoteProxy service as the parameter prefix:

   x-a127-config:
     myremoteservice.key: &apigeeProxyKey CONFIGURED
     myremoteservice.uri: &apigeeProxyUri CONFIGURED

4. Add an API key security definintion to your swagger file. In this configuration, the API key will be expected to be passed in a query parameter called apiKey (or whatever is specified in the name option. You can put this definition at the end of the swagger file:

   securityDefinitions:
     apiKeyQuery:
       type: apiKey
       name: apiKey
       in: query

   OR -- if you want to pass the API key in a header instead of a query param, declare the in: header option:

   securityDefinitions:
     apiKeyHeader:
       type: apiKey
       name: X-API-KEY
       in: header

5. Declare the apiKeyQuery service in x-a127-services. The key and uri options are required. The name of the service must match the name in specified in the securityDefinitions section (described in the previous step). In this case, it is apiKeyQuery:

   x-a127-services:
     apiKeyQuery:
       provider: volos-oauth-apigee
       options:
         key: *apigeeProxyKey
         uri: *apigeeProxyUri

   OR -- if you are passing the key in a header, and you defined a service called apiKeyHeader:

   x-a127-services:
     apiKeyHeader:
       provider: volos-oauth-apigee
       options:
         key: *apigeeProxyKey
         uri: *apigeeProxyUri

6. Apply the API key security policy to an API path operation:

   paths:
     /hello:
       # binds a127 app logic to a route
       x-swagger-router-controller: hello_world
       x-a127-apply: {}
       get:
         description: Returns 'Hello' to the caller
         # used as the method name of the controller
         operationId: hello
         security:
           - apiKeyQuery: []

   OR -- if you delcared an API key header service:

   paths:
     /hello:
       # binds a127 app logic to a route
       x-swagger-router-controller: hello_world
       x-a127-apply: {}
       get:
         description: Returns 'Hello' to the caller
         # used as the method name of the controller
         operationId: hello
         security:
           - apiKeyHeader: []

Call the API

Start your a127 project:

a127 project start

Then, using a valid client ID, call the API like this, passing the API key in a query parameter.

Note: For testing purposes, any valid client ID obtained from a developer app on Apigee Edge will work. You can obtain a client ID from a developer app in the Apigee Edge UI or via an Edge API. Or you can use the client ID that was returned when you created the RemoteProxy service.

curl -i 'http://127.0.0.1:10010/hello?name=Scott&apiKey=f34RUcMxFGwTe6e5KnpZIJfTo2I'

OR -- if you chose to pass the key in a header:

curl -i 'http://127.0.0.1:10010/hello?name=Scott' -H 'X-API-KEY: f34RUcMxFGwTe6e5KnpZIJfTo2I'