Skip to content

Commit

Permalink
Completed documentation for docco
Browse files Browse the repository at this point in the history
  • Loading branch information
@andreareginato
andreareginato committed Jan 22, 2013
1 parent a2be8ff commit f79defe
Show file tree
Hide file tree
Showing 6 changed files with 154 additions and 82 deletions.
3 changes: 3 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,6 @@ node_modules

# Procfile env
*.env

# Docs
docs/
52 changes: 4 additions & 48 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,15 +21,8 @@ Install the client library using git:
$ npm install


## Documentation

* [Simple Oauth2 Docs](git://andreareginato.github.com/simple-oauth2)


## Getting started

### Get the Access Token

```javascript
var credentials = { client: { id: 'client-id', secret: 'client-secret', site: 'https://example.org' } };
var OAuth2 = require('simple-oauth2')(credentials);
Expand All @@ -45,51 +38,14 @@ OAuth2.AuthCode.getToken(params, function(error, result) {
})
```
### Refresh the Access Token
```javascript

token = OAuth2.AccessToken.create(json_token);
if (token.expired()) {
token.refresh(function(error, refreshedToken) { token = refreshedToken; })
}
```
## Documentation
### Authorization Grants
Currently the Authorization Code and Resource Owner Password Credentials grant types
have helper strategy classes that simplify client use. They are available via the #authCode
and #password methods respectively.
```javascript
// Authorization code flow
var uri = OAuth2.AuthCode.authorizeURL({ redirect_uri: 'http://localhost:3000/callback');
var token = OAuth2.AuthCode.getToken({ code: 'authorization-code', redirectURI: 'http://localhost:3000/callback' }, callback);
have helper strategy classes that simplify client use. They are available respectively
via #AuthCode and #Password.
Check out the complete [Simple Oauth2 Documentation](git://andreareginato.github.com/simple-oauth2)
// Password credentials flow
var token = OAuth2.Password.getToken({ username: 'username', 'password': 'password' }, callback);
```
If the functions fails an error object is passed as first argument to the callback.
The body response object is always the last argument.
## Errors
Exceptions are raised when a 4xx or 5xx status code is returned.
```javascript
OAtuh2.HTTPError
```
Through the error message attribute you can access the JSON representation
based on HTTP `status` and error `message`.
```javascript
OAuth2.AuthCode.getToken(function(error, token) {
if (error) { console.log(error.message); }
});
```
## Contributing
Expand Down
19 changes: 10 additions & 9 deletions lib/client/access-token.js
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
//
// Access Token class
// ### Wrapper for the Access Token object
//
module.exports = function(config) {

var core = require('./../core')(config);
require('date-utils');

// Returns the OAuth2.AccessToken instance.
//
// ### Creates an OAuth2.AccessToken instance.
//
// * `token` - An object containing the token object returned from the OAuth2 server.
// maintain state between the request and the callback.
//
function create(token) {
this.token = token;
Expand All @@ -19,21 +19,22 @@ module.exports = function(config) {


//
// Returns true if the token is expired, false otherwise.
// ### Check if the access token is expired or not.
//
function expired() {
function expired() {
return (Date.compare(this.token.expires_at, new Date) == -1) ? false : true
}


//
// Refresh the access token
// ### Refresh the access token
//
// * `callback` - The callback function returning the results.
// An error object is passed as first argument and the result as last.
// An error object is passed as first argument and the new access
// token as last.
//
function refresh(callback) {
var params = { grant_type: 'refresh_token', refresh_token: this.token.refresh_token };
function refresh(callback) {
var params = { grant_type: 'refresh_token', refresh_token: this.token.refresh_token };
core.api('POST', config.tokenPath, params, callback);
}

Expand Down
9 changes: 4 additions & 5 deletions lib/client/auth-code.js
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,12 @@
//
// Authorization Code flow implementation
// ### Authorization Code flow implementation
//
module.exports = function(config) {

var core = require('./../core')(config),
qs = require('querystring');

// Returns the OAuth2 authorization URI where the user decides to
// grant or deny the resources' access.
// ### Redirect the user to the authorization page
//
// * `params.redirectURI` - A String that represents the registered application URI where the
// user is redirected after authorization.
Expand All @@ -23,9 +22,9 @@ module.exports = function(config) {
}

//
// Returns the Access Token object.
// ### Returns the Access Token object.
//
// * `params.code` - Authorization code (from the authorization step).
// * `params.code` - Authorization code (from previous step).
// * `params.redirectURI` - A String that represents the callback uri.
// * `callback` - The callback function returning the results.
// An error object is passed as first argument and the result as last.
Expand Down
8 changes: 4 additions & 4 deletions lib/client/password.js
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
//
// Password credentials flow implementation
// ### Password credentials flow implementation
//
module.exports = function(config) {

var core = require('./../core')(config);

//
// Returns the Access Token object.
// ### Returns the Access Token object.
//
// * `params.username` - Authorization code (from the authorization step).
// * `params.password` - A String that represents the callback uri.
// * `params.username` - A string that represents the registered username.
// * `params.password` - A string that represents the registered password.
// * `params.scope` - A String that represents the application privileges.
// * `callback` - The callback function returning the results.
// An error object is passed as first argument and the result as last.
Expand Down
145 changes: 129 additions & 16 deletions lib/simple-oauth2.js
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,123 @@
//
// A NodeJS module for interfacing with OAuth2. It accepts
// an object with the following valid params.
// **Node.js client library for [OAuth2](http://oauth.net/2/)**
//
// **[Github repository](https://github.com/andreareginato/simple-oauth2)**
//
// OAuth2 lets users grant the access to the desired resources to third party applications,
// giving them the possibility to enable and disable those accesses whenever they want.
//
// Simple OAuth2 supports the following flows.
//
// * Authorization Code Flow (for apps with servers that can store persistent information).
// * Password Credentials (when previous flow can't be used or during development).
//
// ### Authorization Code flow implementation
//
// The Authorization Code flow is made up from two parts. At first your application asks to
// the user the permission to access their data. If the user approves Lelylan sends to the
// client an authorization code. In the second part, the client POST the authorization code
// along with its client secret to the Lelylan in order to get the access token.
// [Learn more about](auth-code.html).
//
//
// // Set the client credentials
// var credentials = { client: {
// id: '<client-id>',
// secret: '<client-secret>',
// site: 'https://example.org'
// }};
//
// // Initialize the OAuth2 Library
// var OAuth2 = require('simple-oauth2')(credentials);
//
// // Authorization OAuth2 URI
// var authorization_uri = OAuth2.AuthCode.authorizeURL({
// redirect_uri: 'http://localhost:3000/callback'
// });
//
// // Redirect example using Express
// // See http://expressjs.com/api.html#res.redirect
// res.redirect(authorization_uri);
//
// // Get the access token object.
// // The authorization code is given from the previous step.
// var token;
// OAuth2.AuthCode.getToken({
// code: 'authorization-code',
// redirectURI: 'http://localhost:3000/callback'
// }, function(error, result) { token = result });
//
// // Create the access token wrapper
// var token = OAuth2.AccessToken.create(json_token);
//
// // Check if the token is expired. If expired it is refreshed.
// if (token.expired()) {
// token.refresh(function(error, result) {
// token = result;
// })
// }
//
//
// ### Password Credentials Flow
//
// This flow is suitable when the resource owner has a trust relationship with the
// client, such as its computer operating system or a highly privileged application.
// Use this flow only when other flows are not viable or when you need a fast way to
// test your application. [Learn more about](password.html).
//
//
// // Get the access token object.
// var token;
// OAuth2.Password.getToken({
// username: 'username',
// password: 'password' 
// }, function(error, result) { token = result });
//
//
// ### Access Token object
//
// When a token expires we need to refresh it. Simple OAuth2 offers the
// AccessToken class that add a couple of useful methods to refresh the
// access token when it is expired. [Learn more about](access-token.html).
//
//
// // Get the access token object.
// var token;
// OAuth2.AuthCode.getToken({
// code: 'authorization-code',
// redirectURI: 'http://localhost:3000/callback'
// }, function(error, result) { token = result });
//
// // Create the access token wrapper
// var token = OAuth2.AccessToken.create(json_token);
//
// // Check if the token is expired. If expired it is refreshed.
// if (token.expired()) {
// token.refresh(function(error, result) {
// token = result;
// })
// }
//
//
// ### Errors
//
// Exceptions are raised when a 4xx or 5xx status code is returned.
//
// OAtuh2.HTTPError
//
// Through the error message attribute you can access the JSON representation
// based on HTTP `status` and error `message`.
//
// OAuth2.AuthCode.getToken(function(error, token) {
// if (error) { console.log(error.message); }
// });
// // => { "status": "401", "message": "Unauthorized" }
//

//
// ### Configurations
//
// Simple OAuth2 accepts an object with the following valid params.
//
// * `client.id` - Required registered Client ID.
// * `client.secret` - Required registered Client secret.
Expand All @@ -10,36 +127,32 @@
// * `tokenPath` - Access token path for the OAuth2 server.
// Simple Oauth2 uses `/oauth/token` as default.
//
//
var appConfig = require('./config');


// Configuration merge
function mergeDefaults(o1, o2) {
for (var p in o2) {
try { if (typeof o2[p] == 'object') { o1[p] = mergeDefaults(o1[p], o2[p]); } else if (typeof o1[p] == 'undefined') { o1[p] = o2[p]; } }
catch(e) { o1[p] = o2[p]; }
}
return o1;
}


// Export the client we'll use to make requests
module.exports = function(config) {

// Base configuration
function configure(config) {
config = config || {};
mergeDefaults(config, appConfig);

return config;
}

config = configure(config);
var core = require('./core')(config);

function mergeDefaults(o1, o2) {
for (var p in o2) {
try { if (typeof o2[p] == 'object') { o1[p] = mergeDefaults(o1[p], o2[p]); } else if (typeof o1[p] == 'undefined') { o1[p] = o2[p]; } }
catch(e) { o1[p] = o2[p]; }
}
return o1;
}

return {
'AuthCode': require('./client/auth-code')(config),
'Password': require('./client/password')(config),
'AccessToken': require('./client/access-token')(config)
}
};

0 comments on commit f79defe

Please sign in to comment.