OAuth 2.0 Client Plugin for Catberry Framework
Installation
npm install catberry-oauth2-client --save
This plugin requires UHR registered to the locator.
Description
This plugin implements "Client" and "Resource Server" roles from OAuth 2.0 (RFC-6749).
Supports grant types:
- Client Credentials (authorization middleware + endpoint)
- Resource Owner Password Credentials (endpoint)
- Authorization Code Grant (endpoint for callback)
- Refresh token (endpoint)
Supports Bearer (RFC-6750) token type.
This plugin sets "access" and "refresh" tokens to the specified cookie names and uses them for requesting data from a resource server.
If a resource server returns status code 401, it will try to refresh the access token or unset all token cookies if refreshing process is failed.
If you need OAuth 2.0 Authorization Server you can use a library like node-oauth2-server or a framework for building RESTful APIs like LoopBack.
Usage
Plugin consists of two parts:
- set of middlewares and endpoints compatible with express/connect application.
ResourceServer
type registered in Service Locator
At the server
In server.js
you should register the plugin into the locator and use the factory like this:
'use strict'; const http = ;const path = ; // configurationconst config = ;const isRelease = processargvlength === 3 ? processargv2 === 'release' : undefined;configpublicPath = path;configserverport = configserverport || 3000;configisRelease = isRelease === undefined ? configisRelease : isRelease; // catberry applicationconst catberry = ;const cat = catberry; // the Catberry application objectcatevents; // register Catberry plugins needed on the serverconst templateEngine = ;templateEngine; const loggerPlugin = ;loggerPlugin; const uhrPlugin = ;uhrPlugin; const OAuth2Client = ;// register all types of OAuth 2.0 client pluginOAuth2Client; // web serverconst express = ;const app = ; const serveStatic = ;app; // create factory instance with current configurationconst OAuth2FlowFactory = catlocator;// add all endpoints required for OAuth 2.0 authorization to connect applicationOAuth2FlowFactory; app; // Catberry app as a middleware const errorhandler = ;app; http ;
In a browser
In browser.js
just do the following:
'use strict'; // this config will be replaced by `./config/browser.json` when building// because of `browser` field in `package.json`const config = ; // catberry applicationconst catberry = ;const cat = catberry; // register Catberry plugins needed in a browserconst templateEngine = ;templateEngine; const loggerPlugin = ;loggerPlugin; const uhrPlugin = ;uhrPlugin; const OAuth2Client = ;OAuth2Client; // starts the application when DOM is readycat;
Configuration
For server configuration:
"authorization": // OAuth 2.0 authorization server with "/token" endpoint "authServerUrl": "https://example.org" // client credentials "clientId": "some_client_id" "clientSecret": "some_client_secret" // request timeout (Optional, 30 seconds by default) "timeout": 30000 // authorization server token endpoint path (Optional, /token by default) "tokenEndpointPath": "/token" // is invalid SSL certificate allowed "unsafeHTTPS": true // proxy-endpoints for obtaining access token using client credentials "endpoints": // Client Credentials Grant // http://tools.ietf.org/html/rfc6749#section-4.4 // this grantType also adds middleware that sets access token for // every http request to connect/express application // name of endpoint is a connect/express routing "auth/guest": // grant type from "grantType": "client_credentials" // some scopes specified by resource provider (Optional) "scope": "wall" "cookie": // name of cookie with access token "accessTokenName": "ccat" // name of cookie with refresh token "refreshTokenName": "reccat" // expiration time in seconds for access token cookie // if it is not specified by authorization server // (Optional, 1 hour by default) "accessTokenExpiresIn": 3600 // expiration time in seconds for refresh token cookie // (Optional 100 years by default) "refreshTokenExpiresIn": 3110400000 // domain for cookie (Optional) "domain": "some.example.org" // Path attribute for cookie ('/' by default). "path": "/" // another example of grantType with same parameters // Resource Owner Password Credentials Grant // http://tools.ietf.org/html/rfc6749#section-4.3 "auth/user": "grantType": "password" "scope": "wall, profile, email" "cookie": "accessTokenName": "pcat" "refreshTokenName": "repcat" "accessTokenExpiresIn": 3600 "refreshTokenExpiresIn": 3110400000 "domain": "some.example.org" "path": "/" // this endpoint for redirection URI endpoint when use // OAuth 2.0 Authorization Code Grant // http://tools.ietf.org/html/rfc6749#section-4.1 // 2 additional parameters // and scope parameter is unsupported "auth/social": "grantType": "authorization_code" // redirect URI used for obtaining authorization code "redirectUri": "https://example.org/social" // where to return after access token has been obtained "returnUri": "/" "cookie": "accessTokenName": "acat" "refreshTokenName": "reacat" "accessTokenExpiresIn": 3600 "refreshTokenExpiresIn": 3110400000 "domain": "some.example.org" "path": "/"
For both server and browser configuration:
"authorization": "resourceServers": "clientToken": // is invalid SSL certificate allowed "unsafeHTTPS": true // resource server host "host": "https://example.org" // endpoint to use for authorization "endpoint": // name of endpoint from server configuration "name": "auth/guest" // name of cookie with access token "accessTokenName": "ccat" "passwordToken": "unsafeHTTPS": true "host": "https://example.org" "endpoint": "name": "auth/user" "accessTokenName": "pcat"
WARNING! DO NOT STORE clientId
AND clientSecret
PARAMETERS IN
THE BROWSER CONFIGURATION OBJECT IT BREAKS THE WHOLE SECURITY MECHANISM
Resource Server Usage
For simple access to a resource server using OAuth 2.0 authorization there is a
ResourceServer
implementation.
You can use it in your application like this:
{ const factory = locator; thisclientToken = factory; thispasswordToken = factory; } { query = query || {}; const server = thispasswordToken ? thispasswordToken : thisclientToken; return server; };
As a response you would have:
Please remember that you need to have an instance of ResourceServer
for each
grant type used in your application (like in the example earlier).
ResourceServer
has following methods:
/** * Does request to the resource server. * @param * @param * @param * @param * @param {string?} options.method HTTP method (GET by default). * @param {Object?} options.data Data to send to server. * @returns */ {} /** * Gets current access token; * @param * @returns */ {} /** * Determines if context is now authorized to do requests. * @param * @returns */ {} /** * Refreshes authorization or remove access and refresh tokens if failed. * @param * @returns */ {} /** * Removes access and refresh tokens. * @param * @returns */ {}
Contributing
There are a lot of ways to contribute:
- Give it a star
- Join the Gitter room and leave a feedback or help with answering users' questions
- Submit a bug or a feature request
- Submit a PR
Denis Rechkunov denis.rechkunov@gmail.com