Plugins development

Plugins development

Please take into account that this article is a draft and is not yet finished

oauthd is built to be extendable, thanks to plugins, which can add a lot of different features, like statistics, user management, or other API unifications.

oauthd acts as an OAuth backend to your front-end application, and provides you with a set of endpoints.

How to develop a plugin

Needed setup

To follow this tutorial, you'll need a working oauthd instance, and oauthd installed with all required dependencies.

If you don't already have an instance to work with, just run the following command:

$ oauthd init

This will ask you for an instance name, and create an instance folder, containing four default plugins (front, admin-auth, request and slashme).

Creating the plugin

In your instance, run the following command:

$ oauthd plugins create myplugin

This adds an entry in your plugins.json file and creates a folder in the plugins directory with the following structure:

plugins/myplugin
    plugin.json     # the plugin's descriptor, containing its name, its type etc.
    index.js        # the plugin's entry point, which should return an object
    package.json    # the plugin's package.json, if external npm packages are needed
    Gruntfile.js    # a basic gruntfile, with no rule by default
    public/         # the plugin's front end application (to be shown in the default front)

That's the folder in which you are going to develop your plugin. This folder is also a git repository by default, in which you should add a remote to publish the plugin.

Editing the plugin.json

The plugin.json file describes your plugin. Here are the list of available fields:

• name: (required) Your plugin's name.
• description (optional) A brief message describing your plugin
• interface_enabled: (optional) tells oauthd if your plugin has an interface. If you're using the default front, this interface will be shown in the dashboard.
• type: (optional) If the plugin implements a specific interface that's used by other plugins, the type is the way these other plugins will access its features. For example, a plugin with the type auth will give a middleware that checks a user's authentication, and allow them to login. The default admin-auth plugin implements the auth interface.

You can add any other field, which will be available to other plugins.

Getting to the code

The entry point of the plugin is the index.js file, which is loaded at startup by oauthd.

In this file, you'll find the following prepared code:

module.exports = function(env) {
    return {};
}

All your plugin's code should be written in the function returned to module.exports.

env argument

This function takes an object env as argument, which provides you with a complete interface with oauthd's core features and to other plugins features. The env variable represents the oauthd environment for your plugin.

Please consult the wiki page describing the env object here to get an exhaustive list of core features.

These are the most commonly used elements of the env object.

• env.server: The restify server, which allows you to create endpoints
• env.plugins: An array containing all the plugins's interface.

Return object

The function's return value must be an object containing the plugin's interface. It may also contain special methods that are called at specific times (for example, methods that will allow you to add endpoints to the server, etc.).

You should use these special methods to ensure that what you do is done at the right time. For example, if you're trying to add an endpoint before the server is created, or if you're calling other plugins before they are loaded, you'll most probably have problems.

Among these special methods, you have:

• init: This method is called for each installed plugin right before the server.listen is called, but after the default middlewares. These middlewares include parsing the body of the request, if the request's Content-Type is or in application/x-www-form-urlencoded.
• raw: This method is called for each installed plugin right before the default middlewares are added.

Other methods or objects returned in this object will be available to other plugins in env.plugins["yourpluginname"], or env.plugins["yourplugintype"] if you specified a type in the plugin.json file.

Creating an endpoint

Usually, you'll create your server endpoints in the init method returned by your plugin.

For example, let's say we want our plugin to catch GET requests to /helloworld and respond with HELLO WORLD:

module.exports = function(env) {
    return {
        init: function () {
            env.server.get('/helloworld', function (req, res) {
                res.send 200, 'HELLO WORLD'
            });
        }
    };
}