@C8/Auth
JWT Authentication Strategy, JWT issuer and API Keys/Tokens generator.
Install
npm install @c8/auth
Usage
Check the /examples
folder.
API
new AuthStrategy(options)
Creates a new Authentication Strategy with a secret. It exposes a series of functions that depend upon that secret.
-
options
is an object literal containing options to control how the token is extracted from the request or verified.-
secretOrKey
(REQUIRED): string or buffer containing the secret (symmetric) or PEM-encoded public key (asymmetric) for verifying the token's signature; -
verify
(REQUIRED): is a function with the parametersverify(jwtPayload, done)
wherejwtPayload
is an object literal containing the decoded JWT payload anddone
is a passport error first callback accepting arguments done(error, user, info); -
jwtFromRequest
: Function that accepts a request as the only parameter and returns either the JWT as a string or null. See Extracting the JWT from the request for more details; -
issuer
: If defined the token issuer (iss) will be verified against this value; -
audience
: If defined, the token audience (aud) will be verified against this value. This should not be setup if you're using APIKeys; -
algorithms
: List of strings with the names of the allowed algorithms. For instance, ["HS256", "HS384"]; -
ignoreExpiration
: if true do not validate the expiration of the token; -
passReqToCallback
: If true the request will be passed to theverify
callback. i.e.verify(request, jwt_payload, done_callback)
;
-
auth.issueToken(payload, opts, callback)
Returns a new JWT string signed with the AuthStrategy
instance secret.
-
payload
(REQUIRED): the payload to be added to the token. Also ajti
property is set to a UUID to allow for token revoking; -
opts
: any option accepted by jsonwebtoken#sign; -
callback
: if callback is not passed, the function is run synchronously and return the JWT as string;
auth.generateApiKey()
Returns an object with apiId
(32 chars alphanumeric) and apiKey
(64 chars alphanumeric) pair.
auth.issueTokenForApiKey(credentials, payload, opts, callback)
Returns a new JWT string signed with the AuthStrategy
instance secret for the given credentials. The credentials.apiId
is added to the payload.
-
credentials
(REQUIRED): an object withapiId
andapiKey
properties; -
payload
(REQUIRED): the payload to be added to the token. Also ajti
property is set to a UUID to allow for token revoking; -
opts
: any option accepted by jsonwebtoken#sign; -
callback
: if callback is not passed, the function is run synchronously and return the JWT as string;
Tests
The following commands are available:
-
coverage
for running code coverage with Istanbul (it shows the report at the bottom) -
standard
for code style checks with Standardjs -
test
for running Mocha tests
Versioning
This module adheres to semver versioning. That means that given a version number MAJOR.MINOR.PATCH, we increment the:
- MAJOR version when we make incompatible API changes,
- MINOR version when we add functionality in a backwards-compatible manner, and
- PATCH version when we make backwards-compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
License
The MIT License
Copyright (c) 2016 C8 MANAGEMENT LIMITED