jwt-bearer-client-auth v2.0.3
jwt-bearer-client-auth
Create and verify RS256 based JWT oauth-jwt-bearer client authentications.
Installation
npm install jwt-bearer-client-auth
Require Usage
var clientAuth = require('jwt-bearer-client-auth');
API
generate(key, issuer, clientId, tokenEndpoint, expiresIn, options)
Generate a valid jwt-bearer client assertion from client details and the client's private RSA256 key.
Parameters
key
{PEM JWK} The key used to sign the assertion. Currentlt the only
supported key type is "PEM JWK". If the JWK has a kid
property it will be
included in the client assertion header.
issuer
{String} An "unique identifier for the entity that issued the JWT." A
good choice for a client generating assertions on-the-fly might be the client's
OAuth 2.0 client ID.
clientId
{String} The client's OAuth 2.0 client ID. It is the required value
for the JWT's sub
claim.
tokenEndpoint
{String} The OAuth 2.0 authorization server's token endpoint.
It is the required value for the JWT's aud
claim.
expiresIn
{Number} The number of seconds from now in which the client
assertion expires.
options
{Object} The options
parameter is passed directly to
node-jsonwebtoken. This module will not allow the
caller to override the properties required by the jwt-bearer RFC.
You can add properties to the header and claim set with the following
sub-objects:
header
{Object} The properties of this object will be included in the JWT's header.payload
{Object} The properties of this object will be included in the JWT's claim body.
Usage Example
// Generate a jwt-bearer client assertion
var fs = require('fs');
var key = {
kid: 'abc123',
kty: 'PEM',
pem: fs.readFileSync('abc123.private.pem'),
};
var issuer = 'aksdfj2w3';
var clientId = 'ocjvS38kjxfa3JFXal342';
var tokenEndpoint = 'https://api.example.org/token';
var expiresIn = 60;
var options = {
payload: {
jti: 'zkjfa3i13',
},
};
var assertion = clientAuth.generate(
key,
issuer,
clientId,
tokenEndpoint,
expiresIn,
options
);
verify(token, hint, issuer, clientId, tokenEndpoint, options, cb)
Verify the given assertion
is a valid jwt-bearer client
assertion.
Returned Value
A payload promise is returned, but a traditional function(err, valid)
callback
is also supported.
Parameters
token
{JWT} The token which is being verified as a valid jwt-bearer client
assertion.
hint
{JWK/JWKS/JWK URI/false} This is passed directly to the
jwks-utils jwkForSignature
method. It can be:
- The JWK for the token
- A JWKS which the tokens JWK is stored in (by key id,
kid
) - A URI for a JWKS which the tokens JWK is stored in (by key id,
kid
) - Or,
false
, indicating that the key is stored within the token's header under either thejwk
orjku
property (note this can be easily be spoofed and the key should be verfied by other means before trusting it).
issuer
{String} An "unique identifier for the entity that issued the JWT." A
good choice for a client generating assertions on-the-fly might be the client's
OAuth 2.0 client ID.
clientId
{String} The client's OAuth 2.0 client ID. It is the required value
for the JWT's sub
claim.
tokenEndpoint
{String} The OAuth 2.0 authorization server's token endpoint.
It is the required value for the JWT's aud
claim.
options
{Object} The options
parameter is used to customize the
verification of the client assertion. The properties of this object are:
payload
{Object} Extra payload claims (and acceptable values) the caller is requiring to be included in the token in order to verify the assertion.
cb
{Function} The cb(err, payload)
function can be used instead of the
returned promise in the typical node fashion.
Usage Example
// Verify a jwt-bearer-client-auth client assertion
var assertion = getClientAssertion();
var key = getPublicKey();
var issuer = getIssuer();
var clientId = getClientId();
var tokenEndpoint = getTokenEndpoint();
var options = {
jti: 'xjkaf3xz'
};
clientAuth
.verify(assertion, key, issuer, clientId, tokenEndpoint, options)
.then(function(payload) {
console.log('Client assertion validated');
})
.catch(function(err) {
console.log('Client assertion was not validated, because: ' + err);
});
})