security apikey redis

Using API key authentication with the Redis provider

This topic explains how to implement API key security in an a127 API using the Redis 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 Redis provider. To read about the Apigee provider, see Using API key authentication with the Apigee provider.

The Apigee provider is a good choice if you want to deploy your API to Apigee Edge. 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 a new project:

   a127 account create myaccount

   a127 project create myproject

2. Add an API key security definintion to your api/swagger/swagger.yaml 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

3. Declare the apiKeyQuery service in x-a127-services. The encryptionKey option is required. This key is used to encrypt/decrypt the credentials.

    x-a127-services:
      apiKeyQuery:
          provider: volos-oauth-redis
          options:
            encryptionKey: 123456

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

```yaml
      x-a127-services:
        apiKeyHeader:
          provider: volos-oauth-redis
          options:
            encryptionKey: 123456
```

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 declared an API key header service:

 ```yaml
    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: []
 ```

8. Start the Redis database. You can use a shell script like this to start Redis:

    #!/bin/bash  
    curl -O http://download.redis.io/releases/redis-2.8.17.tar.gz
    tar xzf redis-2.8.17.tar.gz
    cd redis-2.8.17
    make
    src/redis-server

Obtain a key

The API key is a uniquely identifies a client app that is registered with an authorization server. When using Redis, you'll have to use the volos-oauth-common module API to create a developer and a developer app. When you have the app, you can retrieve the client_id value from the app object, like this:

var key = app.credentials[0].key;

You can then use that key value for the API key in API calls.

For details on using the Volos.js API, see volos-oauth-common module.

Call the API

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

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'