mastercard-oauth1-signer
Version:
Zero dependency library for generating a Mastercard API compliant OAuth signature.
154 lines (122 loc) • 8.06 kB
Markdown
# oauth1-signer-nodejs
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://developer.mastercard.com/_/_/src/global/assets/svg/mcdev-logo-light.svg">
<img src="https://developer.mastercard.com/_/_/src/global/assets/svg/mcdev-logo-dark.svg" alt="mastercard developers logo">
</picture>
[](https://github.com/Mastercard/oauth1-signer-nodejs/actions?query=workflow%3A%22Build+%26+Test%22)
[](https://sonarcloud.io/dashboard?id=Mastercard_oauth1-signer-nodejs)
[](https://sonarcloud.io/dashboard?id=Mastercard_oauth1-signer-nodejs)
[](https://github.com/Mastercard/oauth1-signer-nodejs/actions?query=workflow%3A%22broken+links%3F%22)
[](http://www.npmjs.com/package/mastercard-oauth1-signer)
[](https://github.com/Mastercard/oauth1-signer-nodejs/blob/master/LICENSE)
## Table of Contents
- [Overview](#overview)
* [Compatibility](#compatibility)
* [Supported Signature Methods](#supported-signature-methods)
* [References](#references)
* [Versioning and Deprecation Policy](#versioning)
- [Usage](#usage)
* [Prerequisites](#prerequisites)
* [Adding the Library to Your Project](#adding-the-library-to-your-project)
* [Loading the Signing Key](#loading-the-signing-key)
* [Creating the OAuth Authorization Header](#creating-the-oauth-authorization-header)
* [Integrating with OpenAPI Generator API Client Libraries](#integrating-with-openapi-generator-api-client-libraries)
## Overview <a name="overview"></a>
Zero dependency library for generating a Mastercard API compliant OAuth signature.
### Compatibility <a name="compatibility"></a>
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](https://github.com/nodejs/Release).
A Node version manager such as [nvm](https://github.com/creationix/nvm) (Mac and Linux) or [nvm-windows](https://github.com/coreybutler/nvm-windows)
is a good way to stay on top of this.
### Supported Signature Methods <a name="supported-signature-methods"></a>
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](https://tools.ietf.org/html/rfc8017#section-8.2) |
| `SignatureMethod.RSA_PSS_SHA256` | RSASSA-PSS (Digest: SHA-256, MGF: MGF1 with SHA-256, Salt length: 32 bytes) | [RFC 8017 §8.1](https://tools.ietf.org/html/rfc8017#section-8.1) |
[OAuth.getAuthorizationHeader](#creating-the-oauth-authorization-header ) accepts an optional `signatureMethod` parameter. When omitted, `SignatureMethod.RSA_SHA256` is used by default.
### References <a name="references"></a>
* [OAuth 1.0a specification](https://tools.ietf.org/html/rfc5849)
* [Body hash extension for non application/x-www-form-urlencoded payloads](https://tools.ietf.org/id/draft-eaton-oauth-bodyhash-00.html)
### Versioning and Deprecation Policy <a name="versioning"></a>
* [Mastercard Versioning and Deprecation Policy](https://github.com/Mastercard/.github/blob/main/CLIENT_LIBRARY_DEPRECATION_POLICY.md)
## Usage <a name="usage"></a>
### Prerequisites <a name="prerequisites"></a>
Before using this library, you will need to set up a project in the [Mastercard Developers Portal](https://developer.mastercard.com).
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 <a name="adding-the-library-to-your-project"></a>
```shell
npm i mastercard-oauth1-signer
```
### Loading the Signing Key <a name="loading-the-signing-key"></a>
The following code shows how to load the private key using `node-forge`:
```javascript
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 <a name="creating-the-oauth-authorization-header"></a>
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.
```javascript
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:
```javascript
const authHeader = oauth.getAuthorizationHeader(uri, method, payload, consumerKey, signingKey, oauth.SignatureMethod.RSA_PSS_SHA256);
```
### Integrating with OpenAPI Generator API Client Libraries <a name="integrating-with-openapi-generator-api-client-libraries"></a>
[OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) generates API client libraries from [OpenAPI Specs](https://github.com/OAI/OpenAPI-Specification).
It provides generators and library templates for supporting multiple languages and frameworks.
Generators currently supported:
+ [javascript](#javascript)
#### javascript <a name="javascript"></a>
##### OpenAPI Generator
Client libraries can be generated using the following command:
```shell
openapi-generator-cli generate -i openapi-spec.yaml -g javascript -o out
```
See also:
* [OpenAPI Generator CLI Installation](https://openapi-generator.tech/docs/installation/)
* [CONFIG OPTIONS for javascript](https://github.com/OpenAPITools/openapi-generator/blob/master/docs/generators/javascript.md)
##### Overriding `applyAuthToRequest`
The Authorization header can be added before sending the requests by overriding the `applyAuthToRequest` function:
```javascript
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);
// …
```