oauth1-signer-nodejs

Table of Contents

• Overview
  • Compatibility
  • Supported Signature Methods
  • References
  • Versioning and Deprecation Policy
• Usage
  • Prerequisites
  • Adding the Library to Your Project
  • Loading the Signing Key
  • Creating the OAuth Authorization Header
  • Integrating with OpenAPI Generator API Client Libraries

Overview

Zero dependency library for generating a Mastercard API compliant OAuth signature.

Compatibility

Node 6.12.3+ in general. Node 8.0.0+ for RSA-PSS signing.

There shouldn't be any Node compatibility issues with this package, but it's a good idea to keep your Node versions up-to-date. It is recommended that you use one of the LTS Node.js releases, or one of the more general recent releases. A Node version manager such as nvm (Mac and Linux) or nvm-windows is a good way to stay on top of this.

Supported Signature Methods

Two cryptographic methods are available for generating OAuth signatures, selected via the SignatureMethod constants:

| Constant | Algorithm | Specification | |---|---|---| | SignatureMethod.RSA_SHA256 (default) | RSASSA-PKCS1-v1_5 with SHA-256 | RFC 8017 §8.2 | | SignatureMethod.RSA_PSS_SHA256 | RSASSA-PSS (Digest: SHA-256, MGF: MGF1 with SHA-256, Salt length: 32 bytes) | RFC 8017 §8.1 |

OAuth.getAuthorizationHeader accepts an optional signatureMethod parameter. When omitted, SignatureMethod.RSA_SHA256 is used by default.

References

• OAuth 1.0a specification
• Body hash extension for non application/x-www-form-urlencoded payloads

Versioning and Deprecation Policy

• Mastercard Versioning and Deprecation Policy

Usage

Prerequisites

Before using this library, you will need to set up a project in the Mastercard Developers Portal.

As part of this set up, you'll receive credentials for your app:

• A consumer key (displayed on the Mastercard Developer Portal)
• A private request signing key (matching the public certificate displayed on the Mastercard Developer Portal)

Adding the Library to Your Project

npm i mastercard-oauth1-signer

Loading the Signing Key

The following code shows how to load the private key using node-forge:

const forge = require("node-forge");
const fs = require("fs");
const p12Content = fs.readFileSync("<insert PKCS#12 key file path>", 'binary');
const p12Asn1 = forge.asn1.fromDer(p12Content, false);
const p12 = forge.pkcs12.pkcs12FromAsn1(p12Asn1, false, "<insert key password>");
const keyObj = p12.getBags({
    friendlyName: "<insert key alias>",
    bagType: forge.pki.oids.pkcs8ShroudedKeyBag
}).friendlyName[0];
const signingKey = forge.pki.privateKeyToPem(keyObj.key);

Creating the OAuth Authorization Header

The method that does all the heavy lifting is getAuthorizationHeader. You can call into it directly and as long as you provide the correct parameters, it will return a string that you can add into your request's Authorization header.

const consumerKey = "<insert consumer key>";
const uri = "https://sandbox.api.mastercard.com/service";
const method = "POST";
const payload = "Hello world!";

const oauth = require('mastercard-oauth1-signer');
const authHeader = oauth.getAuthorizationHeader(uri, method, payload, consumerKey, signingKey); // uses RSA-SHA256 as the default signature method

Alternatively, you can specify the signature method:

const authHeader = oauth.getAuthorizationHeader(uri, method, payload, consumerKey, signingKey, oauth.SignatureMethod.RSA_PSS_SHA256);

Integrating with OpenAPI Generator API Client Libraries

OpenAPI Generator generates API client libraries from OpenAPI Specs. It provides generators and library templates for supporting multiple languages and frameworks.

Generators currently supported:

• javascript

javascript

OpenAPI Generator

Client libraries can be generated using the following command:

openapi-generator-cli generate -i openapi-spec.yaml -g javascript -o out

See also:

• OpenAPI Generator CLI Installation
• CONFIG OPTIONS for javascript

Overriding applyAuthToRequest

The Authorization header can be added before sending the requests by overriding the applyAuthToRequest function:

const service = require('../service/index.js');
const apiClient = require('../service/ApiClient.js');
const client = apiClient.instance;
client.basePath = "https://sandbox.api.mastercard.com";
client.applyAuthToRequest = function(request) {
    const _end = request._end;
    request._end = function() {
        const authHeader = oauth.getAuthorizationHeader(request.url, request.method, request._data, consumerKey, signingKey); // uses RSA-SHA256 as the default signature method
        // You can also specify the signature method:
        // const authHeader = oauth.getAuthorizationHeader(request.url, request.method, request._data, consumerKey, signingKey, oauth.SignatureMethod.RSA_PSS_SHA256);
        request.req.setHeader('Authorization', authHeader);
        _end.call(request);
    }
    return request;
};
const serviceApi = new service.ServiceApi();
const opts = {}
const callback = function(error, data, response) {
    // …
};
serviceApi.call(opts, callback);
// …