<commit_before>Identity Manager
================
Implement OAuth2.0 and basic authentication cleanly into your NodeJS server application.

# Summary
* [Setup](#setup)
* [Installation](#install)
* [Usage](#usage)
* [Features](#features)
* [About authorizations](#authorization_grants)
  * [Basic authentication](#basic_authentication)
  * [Authorization code](#authorization_code)
  * [User credentials](#user_credentials)
  * [Client credentials](#client_credentials)
  * [Refresh token](#refresh_token)

# <a name="setup"></a>Setup
This module requires a database infrastructure. To automate the creation of schemas and others boring jobs, `ideman` provides a node command line tool called [`ideman-cli`](https://github.com/thinkingmik/ideman-cli).
So, before continue with the installation of this module, go to [`ideman-cli`](https://github.com/thinkingmik/ideman-cli) project and then return here once you have a database infrastructure.

# <a name="install"></a>Installation
**WARNING**:
Remember that before installing `ideman` you MUST create the database schemas, otherwise this module will not work ([`ideman-cli`](https://github.com/thinkingmik/ideman-cli)).

In your project root run from command line:
```
npm install -save ideman
```

# <a name="usage"></a>Usage
Let's start! Install in your application [`Bookshelf`](http://bookshelfjs.org/) and its dependency [`knex`](http://knexjs.org/).  
Create a new file in your project root like:
```javascript
//file: ./ideman.js
var knex = require('knex')({
  client: 'pg',
  connection: 'postgres://postgres:postgres@localhost:5432/test?charset=utf-8&ssl=true',
});
var Bookshelf = require('bookshelf')(knex);
var ideman = require('ideman')(Bookshelf);

ideman.init({
  token: {
    life: 3600 //token expiration in seconds
  },
  oauth: {
    authentications: ['bearer'], //enable bearer token
    grants: ['password'] //enable user credentials grant
  }
});

module.exports = ideman;
```
Then include this file everywhere you need `ideman` methods, for example in your Express application you could have:
```javascript
//file: ./routes/index.js
var express = require('express');
var router = express.Router();
var ideman = require('../ideman');

router.route('/oauth2/token').post(ideman.isClientAuthenticated, ideman.token);
router.route('/protected/resource').post(ideman.isAuthenticated, function() {
  res.json({
    data: 'The protected resource'
  });
});
```
# <a name="features"></a>Features
Coming soon... I'm working hard!

# <a name="authorization_grants"></a>About authorizations
OAuth 2.0 is the next evolution of the OAuth protocol which was originally created in late 2006. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices.

## <a name="basic_authentication"></a>Basic authentication
`HTTP Basic authentication` implementation is the simplest technique for enforcing access controls to web resources because it doesn't require cookies, session identifier and login pages. This authentication method uses static, standard fields in the HTTP header.
## Use cases
* service calls

## Example request
Send in the user credentials directly in the header to call a protected resource:
```
$ curl -u userId:userPwd -X GET http://localhost:3000/users
```

## <a name="authorization_code"></a>Authorization Code
The `Authorization Code` grant type is used when the client wants to request access to protected resources on behalf of another user (i.e. a 3rd party). This is the grant type most often associated with OAuth.

### Use cases
* calls on behalf of a third party

### Example request<commit_msg>update doc<commit_after>Identity Manager
================
Implement OAuth2.0 and basic authentication cleanly into your NodeJS server application.

# Summary
* [Setup](#setup)
* [Installation](#install)
* [Usage](#usage)
* [Features](#features)
* [About authorizations](#authorization_grants)
  * [Basic authentication](#basic_authentication)
  * [Authorization code](#authorization_code)
  * [User credentials](#user_credentials)
  * [Client credentials](#client_credentials)
  * [Refresh token](#refresh_token)

# <a name="setup"></a>Setup
This module requires a database infrastructure. To automate the creation of schemas and others boring jobs, `ideman` provides a node command line tool called [`ideman-cli`](https://github.com/thinkingmik/ideman-cli).
So, before continue with the installation of this module, go to [`ideman-cli`](https://github.com/thinkingmik/ideman-cli) project and then return here once you have a database infrastructure.

# <a name="install"></a>Installation
**WARNING**:
Remember that before installing `ideman` you MUST create the database schemas, otherwise this module will not work ([`ideman-cli`](https://github.com/thinkingmik/ideman-cli)).

In your project root run from command line:
```
npm install -save ideman
```

# <a name="usage"></a>Usage
Let's start! Install in your application [`Bookshelf`](http://bookshelfjs.org/) and its dependency [`knex`](http://knexjs.org/).  
Create a new file in your project root like:
```javascript
//file: ./ideman.js
var knex = require('knex')({
  client: 'pg',
  connection: 'postgres://postgres:postgres@localhost:5432/test?charset=utf-8&ssl=true',
});
var Bookshelf = require('bookshelf')(knex);
var ideman = require('ideman')(Bookshelf);

ideman.init({
  token: {
    life: 3600 //token expiration in seconds
  },
  oauth: {
    authentications: ['bearer' /*, basic*/], //enable bearer token
    grants: ['password' /*, client_credentials*/] //enable user credentials grant
  }
});

module.exports = ideman;
```
Then include this file everywhere you need `ideman` methods, for example in your Express application you could have:
```javascript
//file: ./routes/index.js
var express = require('express');
var router = express.Router();
var ideman = require('../ideman');

router.route('/oauth2/token').post(ideman.isClientAuthenticated, ideman.token);
router.route('/protected/resource').post(ideman.isAuthenticated, function() {
  res.json({
    data: 'The protected resource'
  });
});
```

Now call the endpoint `/oauth2/token` to retrieve an access token:
```
$ curl -H 'Accept: application/x-www-form-urlencoded' -X POST -d 'grant_type=password&client_id=clientId&client_secret=clientSecret&username=userId&password=<PASSWORD>' http://localhost:3000/oauth2/token
```

It will return a JSON response:
```json
{
  "access_token":"<KEY>"
}
```

With the new `access_token` you can call the protected resource `/protected/resource`
```
$ curl -H 'Authorization: Bearer <KEY>' -X POST http://localhost:3000/protected/resource
```

# <a name="features"></a>Features
Coming soon... I'm working hard!

# <a name="authorization_grants"></a>About authorizations
OAuth 2.0 is the next evolution of the OAuth protocol which was originally created in late 2006. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices.

## <a name="basic_authentication"></a>Basic authentication
`HTTP Basic authentication` implementation is the simplest technique for enforcing access controls to web resources because it doesn't require cookies, session identifier and login pages. This authentication method uses static, standard fields in the HTTP header.
## Use cases
* service calls

## Example request
Send in the user credentials directly in the header to call a protected resource:
```
$ curl -u userId:userPwd -X GET http://localhost:3000/users
```

## <a name="authorization_code"></a>Authorization Code
The `Authorization Code` grant type is used when the client wants to request access to protected resources on behalf of another user (i.e. a 3rd party). This is the grant type most often associated with OAuth.

### Use cases
* calls on behalf of a third party

### Example request
{'fraction_non_alphanumeric': 0.1286234157359769, 'fraction_numerical': 0.007529175555276697, 'mean_word_length': 5.335453100158983, 'pattern_counts': {'":': 1, '<': 34, '<?xml version=': 0, '>': 34, 'https://': 6, 'lorem ipsum': 0, 'www.': 1, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1580486', 'n_tokens_mistral': 2288, 'n_tokens_neox': 2172, 'n_words': 802}