Using basic authentication with the Redis provider

This topic explains how to implement basic authentication in an a127 API using the Redis security provider.

About basic auth security

For basic auth, 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 basic 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 basic auth enabled, your API must be called with a valid username/password passed in an Authorization header. For example:

curl 'http://127.0.0.1:10010/hello?name=Scott' -H 'Authorization: Basic c2NvdHQ6YXBpZ2Vl'

Step by step configuration

1. If you do not have them already, create an a127 account and project.

   a127 account create myaccount

   a127 project create myproject

2. Add a basic auth security definition to your project's api/swagger/swagger.yaml file. You can put this definition at the end of the swagger file:

       securityDefinitions:
         basic:
           type: basic
   

3. Declare a service called basic in x-a127-services. The name of the service must match the name in specified in the securityDefinitions section (described in the previous step). The encryptionKey and passwordCheck options are required. This encryption key is used to encrypt/decrypt the credentials. The passwordCheck option is explained in the next step.

       x-a127-services:
          basic:
            provider: volos-oauth-redis
            options:
              encryptionKey: 123456
              passwordCheck:
                helper: helper
                function: passwordCheck
   

4. Implement the helper to validate the user credentials.

Note that the service declaration includes the passwordCheck helper function. The function must be implemented in a file called helper.js, located in ./api/helpers/helper.js. To learn more about helper functions, see [Understanding helper functions(https://github.com/apigee-127/a127-documentation/wiki/Helper-functions).

Here's a sample helper. A real implementation might call on an authentication service, like LDAP, to perform the validation. This function is obviously for demo purposes only. The key is that whenever a path that is protected with basic auth security is called, this function will be executed to check the credentials that are passed in the request, as we'll see shortly.

       'use strict';

        module.exports = {
          passwordCheck: passwordCheck,
        };

        function passwordCheck(username, password, cb) {
          var passwordOk = (username === 'scott' && password === 'apigee');
          cb(null, passwordOk);
        }

5. Apply the basic security policy to an API path operation. You can apply the policy to one or more paths:

      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:
                - basic: []
   

6. Start the Redis database. You can use a shell script like this to download and 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

Call the API

To try out this example, use a Base-64 encoder to encode the username:password values that are checked in the helper (in our example case, they are scott:apigee). The Base-64 code for this combination is: c2NvdHQ6YXBpZ2Vl. Here's how to call the API using curl:

curl 'http://127.0.0.1:10010/hello?name=Scott' -H 'Authorization: Basic c2NvdHQ6YXBpZ2Vl'

The call succeeds because the credentials passed in the header match the username/password checked in the helper function. Substitute different credentials, and the API returns a security error.