Security Reference

This API project by default has built-in security through the use of a pre-generated unique set of API keys. These keys can be changed at any time by setting them in your configuration file location in the conf directory. However, make sure that you generated sufficiently random values. Do not share these keys with other API projects and be careful with these keys since they control access to your API. By default, two keys were generated: one for production and one for development. When you are running locally (running outside of the Appcelerator Cloud) the server will use the value of the apikey_development key. When you publish your project to the Appcelerator Cloud, it will run in production and use the value of the apikey_production key. To simulate running in production, set the environment variable NODE_ENV to production before running such as NODE_ENV=production appc run. If you want to only use one key, you can set the value of the API Key to apikey in your configuration.

Authentication Strategies

Arrow supports 4 different authentication strategies.

• HTTP Basic Authentication (default). The client will use the HTTP Authorization header to send an encoded version of the API Key using the HTTP Basic Authentication standard. The username part is the value of the API Key and the password part should be blank (empty string). Use the value basic for the key APIKeyAuthType to use this strategy.
• HTTP Header Authentication. The client will set the HTTP APIKey header to the value of the API Key. In this scenario, the server MUST only support HTTPS only endpoints so that the key is not passed in plain text. Use the value apikey for the key APIKeyAuthType to use this strategy.
• LDAP Authentication. The client will use the HTTP Authorization header to send an encoded version of the API Key using the HTTP Basic Authentication standard. The username and password will be sent to the configured LDAP server for authentication. Use the value ldap for the key APIKeyAuthType to use this strategy. See the example below for using LDAP configuration.
• No Authentication. The client does not need any authentication to access these APIs. In this case, all client requests will be accepted without any security. Use the value none for the key APIKeyAuthType to use this strategy.
• Custom Plugin. Using the plugin strategy, you can extend the authentication to use any third-party or custom API authentication. To build your own plugin, set the value plugin for the key APIKeyAuthType to use this strategy and then set the key APIKeyAuthPlugin to the location of your plugin. The location can either be a file path (relative to the current work directory of your server project directory) or the name of the module package available in the standard node_modules location.

Authentication Plugin API

The Plugin must return a JavaScript Class Constructor (function) that can be instantiated to handle authentication requests for every incoming API. The following is a basic API example:

function Plugin(server) {
    this.config = server.config;
}

Plugin.prototype.matchURL = function(req) {
    // match all requests that aren't for our admin
    return req.url.indexOf(this.config.admin.prefix)!==0;
};

Plugin.prototype.validateRequest = function(req, resp) {
    // check the value of the incoming request
    return req.headers.foo === 'bar';
};

Plugin.prototype.applyCredentialsForTest = function(opts) {
    // when testing, use our header key/value
    opts.headers.foo = 'bar';
};

module.exports = Plugin;

The matchURL function is optional. If not provided, all requests will be forwarded to validateRequest.

The validateRequest function can either be synchronous or asyncronous. To use a synchronous implementation, you just define your function with either one or two parameters (req for the HTTP request and/or resp for the HTTP response). The return value must either be true (passed) or false (failed). You can also throw and exception if you would prefer to provide an Error to the client. To use an asynchronous implementation, you must define all 3 function parameters (same as above with the addition of the 3rd parameter which is a function callback to call when you have completed). This is useful in cases where you need to perform some tasks which may not be synchronous. In the asynchoronous callback you must call the callback with 2 parameters. The first parameter is an Error if you want to return an error to the client. The second is a boolean success value (same as above).

The applyCredentialsForTest function will be called by the internal test framework before forwarding the request to your API. This is useful when you have a custom plugin and you need to setup the HTTP request used during testing (from the documentation page for the API).

LDAP Authentication Plugin

To configure the LDAP Authentication plugin, you must set the following in your configuration:

ldap: {
    url: 'url_to_ldap_server',
    adminDn: 'admin-dn',
    adminPassword: 'password',
    searchBase: 'dc=example,dc=com',
    searchFitler: '(uid={{username}})'
}

To test the LDAP configuration, you can use the Open LDAP server with the following configuration:

APIKeyAuthType: 'ldap',
ldap: {
    url: "ldap://ldap.forumsys.com:389",
    adminDn: "cn=read-only-admin,dc=example,dc=com",
    adminPassword: "password",
    searchBase: "dc=example,dc=com",
    searchFilter: "(uid={{username}})"
},

Then use the username einstein and the password password when using the API.