authmaker-verify-express/Readme.md

[![Build Status](https://img.shields.io/travis/Authmaker/authmaker-verify-express/master.svg)](https://travis-ci.org/Authmaker/authmaker-verify-express)
[![Code Climate](https://img.shields.io/codeclimate/github/Authmaker/authmaker-verify-express.svg)](https://codeclimate.com/github/Authmaker/authmaker-verify-express)

[![Version npm](https://img.shields.io/npm/v/authmaker-verify-express.svg)](https://www.npmjs.com/package/authmaker-verify-express)
[![Dependencies](https://img.shields.io/david/Authmaker/authmaker-verify-express.svg)](https://david-dm.org/Authmaker/authmaker-verify-express)
[![npm Downloads](https://img.shields.io/npm/dm/authmaker-verify-express.svg)](https://www.npmjs.com/package/authmaker-verify-express)

# Authmaker Verify Express
This package allows you to use [Authmaker verify](https://www.npmjs.com/package/authmaker-verify) extremely easily in an ExpressJS based Node application.

## Installation
```
npm install --save authmaker-verify-express
```

### Usage
This package currently makes use of the Mongo connection for Authmaker Verify so you need to initialise the database connection before use:
```
var authmakerVerify = require('authmaker-verify');
authmakerVerify.connectMongo(nconf);
```

You need to pass a [nconf](https://github.com/indexzero/nconf) object into the connectMongo call that has access to at least the following parameters:

```
{
    "mongo": {
        "authmaker": {
            "db": "your-db-name",
            "host": "localhost",
            "port": 27017
        }
    }
}
```

you can also optionally include `username` and `password`. Each of these config entries are accessed asynchronously so you can use any of the asynchronous stores for nconf

#### Middlewares
To actually use this package you just need to include middlewares in your ExpressJS app. Here are a few examples of ways you can use authmaker-verify-express. Please note that all of these examples use a simple "success" callback that does nothing but responds with a 200 response code. They have also already imported required modules:

```
var authmakerVerifyExpress = require('authmaker-verify-express');
var express = require('express');
var app = express();

function success(req, res){
    return res.send("Success");
}
```

Requires users with valid, in date access tokens in the request:
```
app.get('/verify': [authmakerVerifyExpress.mongo(), success]);
```

Requires users with valid, in date access tokens with the scope "my_awesome_permission":
```
app.get('/scope': [authmakerVerifyExpress.mongo("my_awesome_permission"), success]);
```

Requires users with valid, in date access tokens with a rate limited scope (suffix `_limit_<num>_<timeframe>`)
```
app.get('/jointrated': [authmakerVerifyExpress.mongoRateLimited("face"), success]);
```

Requires users with valid, in date access token but if they don't have a rate limited scope it uses `face_limit_10_minutes` as a default scope:
```
app.get('/defaultScope': [authmakerVerifyExpress.mongoRateLimited("face", "face_limit_10_minutes"), success]);
```

### API

#### mongoRateLimited - function - returns middleware
```
mongoRateLimited: function(tag, defaultScope)
```

#### mongoRateLimitedDefault - function - returns middleware
```
mongoRateLimitedDefault: function(tag, defaultScope)
```

#### mongo - function - returns middleware
```
mongo: function(tag, options)
```

options.passError (optional) if true passes error via middleware

#### connectMongo - function
```
connectMongo: function(nconf) {
    //initialise the db
    authmakerVerify.connectMongo(nconf);
}
```

#### authmakerVerify - object
If you ever need to access the [authmaker-verify](https://github.com/Authmaker/authmaker-verify) object that is powering authmaker-verify-express to access any lower level apis you can access it directly like this:
```
var authmakerVerifyExpress = require('authmaker-verify-express');
authmakerVerifyExpress.authmakerVerify;
```