security basic auth apigee

Using basic authentication with the Apigee provider

This topic explains how to implement basic authentication in an a127 API using the Apigee 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 Apigee provider. To read about the Redis provider, see Using basic authentication with the Redis 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 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 your project's 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 a basic auth security definition to your swagger file. You can put this definition at the end of the swagger file:

       securityDefinitions:
         basic:
           type: basic

5. Declare a service called basic (or any other name you choose) 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 key and uri options are required.

      x-a127-services:
         basic:
           provider: volos-oauth-apigee
           options:
             key: *apigeeProxyKey
             uri: *apigeeProxyUri
             passwordCheck:
               helper: helper
               function: passwordCheck

6. 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);
        }

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

Call the API

Start the a127 project:

a127 project start

To try out this example, use a Base-64 encoder and 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 an error.