simple-oauth2

What is simple-oauth2?

The simple-oauth2 npm package is a straightforward and flexible library for implementing OAuth2 authentication in Node.js applications. It provides a simple API to handle the OAuth2 authorization flows, including obtaining access tokens, refreshing tokens, and revoking tokens.

What are simple-oauth2's main functionalities?

Authorization Code Flow

This feature allows you to generate an authorization URL for the Authorization Code Flow. Users can visit this URL to authorize your application and obtain an authorization code.

const { AuthorizationCode } = require('simple-oauth2');

const client = new AuthorizationCode({
  client: {
    id: 'your-client-id',
    secret: 'your-client-secret',
  },
  auth: {
    tokenHost: 'https://authorization-server.com',
    tokenPath: '/oauth/token',
    authorizePath: '/oauth/authorize',
  },
});

const authorizationUri = client.authorizeURL({
  redirect_uri: 'http://localhost:3000/callback',
  scope: 'user_profile',
  state: 'random-string',
});

console.log('Visit this URL to authorize:', authorizationUri);

Obtaining Access Token

This feature allows you to exchange an authorization code for an access token. The access token can then be used to access protected resources on behalf of the user.

const tokenParams = {
  code: 'authorization-code',
  redirect_uri: 'http://localhost:3000/callback',
  scope: 'user_profile',
};

client.getToken(tokenParams)
  .then((result) => {
    const accessToken = client.createToken(result);
    console.log('Access Token:', accessToken.token);
  })
  .catch((error) => {
    console.error('Access Token Error', error.message);
  });

Refreshing Access Token

This feature allows you to refresh an expired access token using a refresh token. The new access token can then be used to continue accessing protected resources.

const token = client.createToken({
  access_token: 'existing-access-token',
  refresh_token: 'existing-refresh-token',
  expires_in: '3600',
});

token.refresh()
  .then((result) => {
    const refreshedToken = client.createToken(result);
    console.log('Refreshed Token:', refreshedToken.token);
  })
  .catch((error) => {
    console.error('Refresh Token Error', error.message);
  });

Revoking Access Token

This feature allows you to revoke an access token, making it invalid for further use. This is useful for logging out users or invalidating tokens for security reasons.

const token = client.createToken({
  access_token: 'existing-access-token',
  refresh_token: 'existing-refresh-token',
  expires_in: '3600',
});

token.revoke('access_token')
  .then(() => {
    console.log('Access Token Revoked');
  })
  .catch((error) => {
    console.error('Revoke Token Error', error.message);
  });

Other packages similar to simple-oauth2

passport-oauth2

passport-oauth2 is a strategy for the Passport authentication middleware that implements OAuth 2.0. It is highly configurable and can be used with various OAuth 2.0 providers. Compared to simple-oauth2, passport-oauth2 is more integrated with the Passport ecosystem, making it a good choice if you are already using Passport for authentication.

client-oauth2

client-oauth2 is a lightweight and flexible library for OAuth 2.0 in JavaScript. It supports multiple OAuth 2.0 flows and is easy to use in both Node.js and browser environments. Compared to simple-oauth2, client-oauth2 offers a more minimalistic approach and can be a good choice for developers looking for a smaller library.

axios-oauth-client

axios-oauth-client is a library that integrates OAuth 2.0 with the popular Axios HTTP client. It simplifies the process of making authenticated HTTP requests using OAuth 2.0 tokens. Compared to simple-oauth2, axios-oauth-client is more focused on integrating OAuth 2.0 with Axios, making it a good choice if you are already using Axios for HTTP requests.

README

Simple OAuth2

Node.js client library for Oauth2

Requirements

Node client library is tested against Node ~0.8.x

Installation

Install the client library using npm:

$ npm install simple-oath2

Install the client library using git:

$ git clone git://github.com/andrearegianto/simple-oauth2.git
$ cd simple-oauth2
$ npm install

Documentation

• Simple Oauth2 Docs

Getting started

Get the Access Token

var credentials = { client: { id: 'client-id', secret: 'client-secret', site: 'https://example.org' } };
var OAuth2 = require('simple-oauth2')(credentials);

// Returns the URI where to redirect your app
var redirect = Oauth2.AuthCode.authorizeURL({ redirectURI: 'http://localhost:3000/callback', scope: 'user', state: '02afe928b');
// => "https://example.org/oauth/authorization?response_type=code&client_id=client_id&redirect_uri=http://localhost:3000/callback&scope=user&state=02afe928b"

// Get the access token object
vat params = { code: 'authorization-code', redirectURI: 'http://localhost:3000/callback' }
OAuth2.AuthCode.getToken(params, function(error, result) {
  // save the token
})

Refresh the Access Token

token = OAuth2.AccessToken.create(json_token);
if (token.expired()) {
  token.refresh(function(error, refreshedToken) { token = refreshedToken; })
}

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.

// 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);

// 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.

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); }
});

Contributing

Fork the repo on github and send a pull requests with topic branches. Do not forget to provide specs to your contribution.

Running specs

• Fork and clone the repository (dev branch).
• Run npm install for dependencies.
• Run make test to execute all specs.
• Run make test-watch to auto execute all specs when a file change.

Coding guidelines

Follow github guidelines.

Feedback

Use the issue tracker for bugs. Mail or Tweet us for any idea that can improve the project.

Links

• GIT Repository
• Documentation

Authors

Andrea Reginato

Contributors

Special thanks to the following people for submitting patches.

Changelog

See CHANGELOG

Copyright

Copyright (c) 2013 Lelylan. See LICENSE for details.

Changelog

v0.1.1 (21 Jan 2013)

• Added Password credentials flow