Product
Introducing License Enforcement in Socket
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
Lightweight support for fetching JWKs.
Fetches JSON native JWKs and exposes them as PEMs that can be consumed by the jsonwebtoken
package
(and node's native RSA and ECDSA crypto APIs).
Works great for
jsonwebtoken
(Auth0)Crypto Support
npm install --save keyfetch
Retrieve a key list of keys:
var keyfetch = require("keyfetch");
keyfetch.oidcJwks("https://example.com/").then(function (results) {
results.forEach(function (result) {
console.log(result.jwk);
console.log(result.thumprint);
console.log(result.pem);
});
});
Quick JWT verification (for authentication):
var keyfetch = require("keyfetch");
var jwt = "...";
keyfetch.jwt.verify(jwt).then(function (decoded) {
console.log(decoded);
});
JWT verification (for authorization):
var options = { issuers: ["https://example.com/"], claims: { role: "admin" } };
keyfetch.jwt.verify(jwt, options).then(function (decoded) {
console.log(decoded);
});
Verify a JWT with jsonwebtoken
:
var keyfetch = require("keyfetch");
var jwt = require("jsonwebtoken");
var auth = "..."; // some JWT
var token = jwt.decode(auth, { json: true, complete: true });
if (!isTrustedIssuer(token.payload.iss)) {
throw new Error("untrusted issuer");
}
keyfetch.oidcJwk(token.header.kid, token.payload.iss).then(function (result) {
console.log(result.jwk);
console.log(result.thumprint);
console.log(result.pem);
jwt.jwt.verify(jwt, { jwk: result.jwk });
});
Note: You might implement isTrustedIssuer
one of these:
function isTrustedIssuer(iss) {
return -1 !== ["https://partner.com/", "https://auth0.com/"].indexOf(iss);
}
function isTrustedIssuer(iss) {
return (
/^https:/.test(iss) && /(\.|^)example\.com$/.test(iss) // must be a secure domain
); // can be example.com or any subdomain
}
All API calls will return the RFC standard JWK SHA256 thumbprint as well as a PEM version of the key.
Note: When specifying id
, it may be either kid
(as in token.header.kid
)
or thumbprint
(as in result.thumbprint
).
Retrieves keys from a URL such as https://example.com/jwks/
with the format { keys: [ { kid, kty, exp, ... } ] }
and returns the array of keys (as well as thumbprint and jwk-to-pem).
keyfetch.jwks(jwksUrl);
// Promises [ { jwk, thumbprint, pem } ] or fails
keyfetch.jwk(id, jwksUrl);
// Promises { jwk, thumbprint, pem } or fails
If https://example.com/
is used as issuerUrl
it will resolve to
https://example.com/.well-known/jwks.json
and return the keys.
keyfetch.wellKnownJwks(issuerUrl);
// Promises [ { jwk, thumbprint, pem } ] or fails
keyfetch.wellKnownJwk(id, issuerUrl);
// Promises { jwk, thumbprint, pem } or fails
If https://example.com/
is used as issuerUrl
then it will first resolve to
https://example.com/.well-known/openid-configuration
and then follow jwks_uri
to return the keys.
keyfetch.oidcJwks(issuerUrl);
// Promises [ { jwk, thumbprint, pem } ] or fails
keyfetch.oidcJwk(id, issuerUrl);
// Promises { jwk, thumbprint, pem } or fails
This can accept a JWT string (compact JWS) or a decoded JWT object (JWS).
This can be used purely for verifying pure authentication tokens, as well as authorization tokens.
keyfetch.jwt.verify(jwt, { strategy: "oidc" }).then(function (verified) {
/*
{ protected: '...' // base64 header
, payload: '...' // base64 payload
, signature: '...' // base64 signature
, header: {...} // decoded header
, claims: {...} // decoded payload
}
*/
});
When used for authorization, it's important to specify a limited set of trusted issuers
.
When using for federated authentication you may set issuers = ["*"]
- but DO NOT trust claims such as email
and email_verified
.
If your authorization claims
can be expressed as exact string matches, you can specify those too.
keyfetch.jwt.verify(jwt, {
strategy: 'oidc',
issuers: [ 'https://example.com/' ],
//iss: 'https://example.com/',
claims: { role: 'admin', sub: 'abc', group: 'xyz' }
}).then(function (verified) {
strategy
may be oidc
(default) , auth0
, or a direct JWKs url.issuers
must be a list of https urls (though http is allowed for things like Docker swarm), or '*'iss
is like issuers
, but only oneclaims
is an object with arbitrary keys (i.e. everything except for the standard iat
, exp
, jti
, etc)exp
may be set to false
if you're validating on your own (i.e. allowing time drift leeway)jwks
can be used to specify a list of allowed public key rather than fetching them (i.e. for offline unit tests)jwk
same as above, but a single key rather than a listtry {
console.log( keyfetch.jwt.decode(jwt) );
} catch(e) {
console.error(e);
}
{ protected: '...' // base64 header
, payload: '...' // base64 payload
, signature: '...' // base64 signature
, header: {...} // decoded header
, claims: {...} // decoded payload
It's easier just to show the code than to explain the example.
keyfetch.jwt.decode = function (jwt) {
// Unpack JWS from "compact" form
var parts = jwt.split(".");
var obj = {
protected: parts[0],
payload: parts[1],
signature: parts[2]
};
// Decode JWT properties from JWS as unordered objects
obj.header = JSON.parse(Buffer.from(obj.protected, "base64"));
obj.claims = JSON.parse(Buffer.from(obj.payload, "base64"));
return obj;
};
keyfetch.init({
// set all keys at least 1 hour (regardless of jwk.exp)
mincache: 1 * 60 * 60,
// expire each key after 3 days (regardless of jwk.exp)
maxcache: 3 * 24 * 60 * 60,
// re-fetch a key up to 15 minutes before it expires (only if used)
staletime: 15 * 60
});
There is no background task to cleanup expired keys as of yet. For now you can limit the number of keys fetched by having a simple whitelist.
JSON.stringify()
d errors look like this:
{
code: "INVALID_JWT",
status: 401,
details: [ "jwt.claims.exp = 1634804500", "DEBUG: helpful message" ]
message: "token's 'exp' has passed or could not parsed: 1634804500"
}
SemVer Compatibility:
code
& status
will remain the same.message
is NOT included in the semver compatibility guarantee (we intend to make them more client-friendly), neither is detail
at this time (but it will be once we decide on what it should be).details
may be added to, but not subtracted fromHint | Code | Status | Message (truncated) |
---|---|---|---|
bad gateway | BAD_GATEWAY | 502 | The auth token could not be verified because our se... |
insecure issuer | MALFORMED_JWT | 400 | The auth token could not be verified because our se... |
parse error | MALFORMED_JWT | 400 | The auth token could not be verified because it is ... |
no issuer | MALFORMED_JWT | 400 | The auth token could not be verified because it doe... |
malformed exp | MALFORMED_JWT | 400 | The auth token could not be verified because it's e... |
expired | INVALID_JWT | 401 | The auth token is expired. To try again, go to the ... |
inactive | INVALID_JWT | 401 | The auth token isn't valid yet. It's activation dat... |
bad signature | INVALID_JWT | 401 | The auth token did not pass verification because it... |
jwk not found old | INVALID_JWT | 401 | The auth token did not pass verification because ou... |
jwk not found | INVALID_JWT | 401 | The auth token did not pass verification because ou... |
no jwkws uri | INVALID_JWT | 401 | The auth token did not pass verification because it... |
unknown issuer | INVALID_JWT | 401 | The auth token did not pass verification because it... |
failed claims | INVALID_JWT | 401 | The auth token did not pass verification because it... |
Minor Breaking changes (with a major version bump):
client_message
)let
and template strings (drops really old node compat)issuers = ["*"]
to requiring that an issuer (or public jwk for verification) is specifiedSee other changes in CHANGELOG.md.
FAQs
Lightweight support for fetching JWKs.
The npm package keyfetch receives a total of 1,084 weekly downloads. As such, keyfetch popularity was classified as popular.
We found that keyfetch demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
Product
We're launching a new set of license analysis and compliance features for analyzing, managing, and complying with licenses across a range of supported languages and ecosystems.
Product
We're excited to introduce Socket Optimize, a powerful CLI command to secure open source dependencies with tested, optimized package overrides.