yahoo/spartan-node

Name: spartan-node

Owner: Yahoo Inc.

Description: This module provides authentication and authorization APIs for client & server applications.

Created: 2015-11-05 21:31:13.0

Updated: 2017-08-24 07:01:58.0

Pushed: 2015-12-02 07:48:24.0

Homepage:

Size: 31

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

Spartan Javascript APIs for NodeJS Applications

This module provides authentication and authorization APIs for client & server applications.

How it works?

---

1. The client application calls getToken() API to get a cert token for a the service role.
2. The getToken() fetches token from Spartan Attestation Service for the given role, sign it with client's private key and return back the token to the client application
3. The client place the cert token in the HTTP request to the service. The app request token is passed as a special HTTP parameter - x-spartan-auth-token
4. Upon receiving request, application server validates the app request token passed on x-spartan-auth-token using svcAuth express route handler.
5. If the app request token is valid, application checks whether the client application is authorized to access the requested resource and access is granted based on that check.

---

Getting Started

This section provides a sample NodeJS client and server implementation to demostrate the usage. The client wanted to access a protected service (e.g. /auth-test). To access this endpoint, the client passes the cert token it received from getToken(). The service endpoint validates the cert token and grant access to the requested resource.

The following examples are also available in spartan server demo directory

---

Client

spartan = require('spartan-api');
request = require('request');

pp server you want to connect to. This is a protected endpoint
svc_url = 'https://example.com:3001/v1/service/auth-test'

etCert callback function.
ertCallback = function(error, certs) {

 Attestation server call failed, HTTP non-20X error returned
 (error) {
console.error('Error: failed to return certs from Attestation Service: ' + JSON.stringify(error));
return;


 Application server request parameters
r options = {
uri: svc_url,
method: 'POST',
headers: {
 'x-spartan-auth-token': certs
},
json: { }


 You got the cert token, now, make a call to application server
quest(options, function (error, response, body) {

// Mostly operational error
if (error) {
  console.error('Error: service access error:', error);
  return;
}

// Auth failed
if (response.statusCode != 200) {
  console.error(body);
  return;
}

// Auth was successful
var resp = body;
console.log(resp);
;



PI to fetch app auth token. 'SuperRole' is the role name of the service
ou want to access. The role represents a service
tan.getToken('SuperRole', { app_privkey: fs.readFileSync('priv.key'),  // client app private key
                           app_pubkey: fs.readFileSync('pub.key', 'utf8'), // client app public key 
                           as_pubkey: fs.readFileSync('as-pub.key'), // attestation server's public key
                           as_url: 'https://example.com:3000/v1/as/tokens' // attestation server URL
                         }, getCertCallback); // callback function

---

Application Server (NodeJS Express)

fs = require('fs');
express = require('express');
router = express.Router();
spartan = require('spartan-api');

sp_handlr = new spartan.RouteHandler({ as_pubkey: fs.readFileSync(config.asPubKey, 'utf8'),
                                       role: 'SuperRole' // role for authz
                                     });

ervice endpoint. Auth and authz route handler is chained.
er.post('/auth-test', [sp_handlr.svcAuth.bind(sp_handlr)], function(req, res) {

 If you reach here means client is authorized to access this endpoint
 Your business logic goes here

turn res.status(200).json({ msg: 'app is authenticated!' });


le.exports = router;

API Documentation

The APIs are documented in the source file - index.js