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 (this library supports both callbacks or promises for async flow).

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).
• Client Credentials Flow (the client can request an access token using only its client credentials)

Thanks to Open Source

Simple OAuth 2.0 come to life thanks to the work I've made in Lelylan, an open source microservices architecture for the Internet of Things. If this project helped you in any way, think about giving us a star on Github.

Table of Contents

• Requirements
• Installation
• Getting started
  • Express and Github example
• OAuth2 Supported flows
  • Authorization Code flow
  • Password Credentials Flow
  • Client Credentials Flow
• Helpers
  • Access Token object
  • Errors
• Configuration
• Contributing
• Authors
  • Contributors
• Changelog
• License

Requirements

Node client library is tested against the latest minor Node versions: 0.10.x, 0.11.x, 0.12.x and 4.2.x.

Installation

Install the client library using npm:

$ npm install --save simple-oauth2

Install the client library using git:

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

Getting started

Express and Github example

var express = require('express'),
    app = express();

var oauth2 = require('simple-oauth2')({
  clientID: CLIENT_ID,
  clientSecret: CLIENT_SECRET,
  site: 'https://github.com/login',
  tokenPath: '/oauth/access_token',
  authorizationPath: '/oauth/authorize'
});

// Authorization uri definition
var authorization_uri = oauth2.authCode.authorizeURL({
  redirect_uri: 'http://localhost:3000/callback',
  scope: 'notifications',
  state: '3(#0/!~'
});

// Initial page redirecting to Github
app.get('/auth', function (req, res) {
    res.redirect(authorization_uri);
});

// Callback service parsing the authorization token and asking for the access token
app.get('/callback', function (req, res) {
  var code = req.query.code;

  oauth2.authCode.getToken({
    code: code,
    redirect_uri: 'http://localhost:3000/callback'
  }, saveToken);

  function saveToken(error, result) {
    if (error) { console.log('Access Token Error', error.message); }
    token = oauth2.accessToken.create(result);
  }
});

app.get('/', function (req, res) {
  res.send('Hello<br><a href="/auth">Log in with Github</a>');
});

app.listen(3000);

console.log('Express server started on port 3000');

Credits to @lazybean

OAuth2 Supported flows

Authorization Code flow

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 the OAuth2 server 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.

// Set the client credentials and the OAuth2 server
var credentials = {
  clientID: '<client-id>',
  clientSecret: '<client-secret>',
  site: 'https://api.oauth.com'
};

// 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',
  scope: '<scope>',
  state: '<state>'
});

// 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;
var tokenConfig = {
  code: '<code>',
  redirect_uri: 'http://localhost:3000/callback'
};

// Callbacks
// Save the access token
oauth2.authCode.getToken(tokenConfig, function saveToken(error, result) {
  if (error) { console.log('Access Token Error', error.message); }

  token = oauth2.accessToken.create(result);
});

// Promises
// Save the access token
oauth2.authCode.getToken(tokenConfig)
.then(function saveToken(result) {
  token = oauth2.accessToken.create(result);
})
.catch(function logError(error) {
  console.log('Access Token Error', error.message);
});

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.

// Get the access token object.
var token;
var tokenConfig = {
  username: 'username',
  password: 'password' 
};

// Callbacks
// Save the access token
oauth2.password.getToken(tokenConfig, function saveToken(error, result) {
  if (error) { console.log('Access Token Error', error.message); }
  token = oauth2.accessToken.create(result);

  oauth2.api('GET', '/users', {
    access_token: token.token.access_token
  }, function (err, data) {
    console.log(data);
  });
});

// Promises
// Save the access token
oauth2.password
  .getToken(tokenConfig)
  .then(function saveToken(result) {
    token = oauth2.accessToken.create(result);
    return oauth2.api('GET', '/users', { access_token: token.token.access_token });
  })
  .then(function evalResource(data) {
    console.log(data);
  });

Client Credentials Flow

This flow is suitable when client is requesting access to the protected resources under its control.

// Get the access token object.
var credentials = {
  clientID: '<client-id>',
  clientSecret: '<client-secret>',
  site: 'https://api.oauth.com'
};

// Initialize the OAuth2 Library
var oauth2 = require('simple-oauth2')(credentials);
var token;
var tokenConfig = {};

// Callbacks
// Get the access token object for the client
oauth2.client.getToken(tokenConfig, function saveToken(error, result) {
  if (error) { console.log('Access Token Error', error.message); }
  token = oauth2.accessToken.create(result);
});


// Promises
// Get the access token object for the client
oauth2.client
  .getToken(tokenConfig)
  .then(function saveToken(result) {
    token = oauth2.accessToken.create(result);
  })
  .catch(function logError(error) {
    console.log('Access Token error', error.message);
  });

Helpers

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.

// Sample of a JSON access token (you got it through previous steps)
var token = {
  'access_token': '<access-token>',
  'refresh_token': '<refresh-token>',
  'expires_in': '7200'
};

// Create the access token wrapper
var token = oauth2.accessToken.create(token);

// Check if the token is expired. If expired it is refreshed.
if (token.expired()) {
  // Callbacks
  token.refresh(function(error, result) {
    token = result;
  })

  // Promises
  token.refresh().then(function saveToken(result) {
    token = result;
  });
}

When you've done with the token or you want to log out, you can revoke the access token and refresh token.

// Callbacks
// Revoke only the access token
token.revoke('access_token', function(error) {
  // Session ended. But the refresh_token is still valid.

  // Revoke the refresh_token
  token.revoke('refresh_token', function(error) {
    console.log('token revoked.');
  });
});

// Promises
// Revoke only the access token
token.revoke('access_token')
  .then(function revokeRefresh() {
    // Revoke the refresh token
    return token.revoke('refresh_token');
  })
  .then(function tokenRevoked() {
    console.log('Token revoked');
  })
  .catch(function logError(error) {
    console.log('Error revoking token.', error.message);
  });

Errors

Exceptions are raised when a 4xx or 5xx status code is returned.

HTTPError

Through the error message attribute you can access the JSON representation based on HTTP status and error message.

// Callbacks
oauth2.authCode.getToken(function(error, token) {
  if (error) { console.log(error.message); }
});

// Promises
oauth2.authCode.getToken().catch(function evalError(error) {
  console.log(error.message);
});

// => { "status": "401", "message": "Unauthorized" }

Configuration

Simple OAuth2 accepts an object with the following valid params.

• clientID - Required registered Client ID.
• clientSecret - Required registered Client secret.
• site - Required OAuth2 server site.
• authorizationPath - Authorization path for the OAuth2 server. Defaults to /oauth/authorize.
• tokenPath - Access token path for the OAuth2 server. Defaults to /oauth/token.
• revocationPath - Revocation token path for the OAuth2 server. Defaults to /oauth/revoke.
• useBasicAuthorizationHeader - Whether or not the Authorization: Basic ... header is set on the request. Defaults to true.
• clientSecretParameterName - Parameter name for the client secret. Defaults to client_secret.
• useBodyAuth - Wheather or not the clientID/clientSecret params are sent in the request body. Defaults to true.

// Set the configuration settings
var credentials = {
  clientID: '<client-id>',
  clientSecret: '<client-secret>',
  site: 'https://www.oauth2.com',
  authorizationPath: '/oauth2/authorization',
  tokenPath: '/oauth2/access_token',
  revocationPath: '/oauth2/revoke'
};

// Initialize the OAuth2 Library
var oauth2 = require('simple-oauth2')(credentials);

Contributing

See CONTRIBUTING

Authors

Andrea Reginato

Contributors

Special thanks to the following people for submitting patches.

• Jonathan Samines

Changelog

See CHANGELOG

License

Simple OAuth 2.0 is licensed under the Apache License, Version 2.0

Changelog

v0.7.0 (22 April 2016)

• Replaced internal logger by the debug module logger.
• Fixed some project metadata.