Skip to content

Commit d578c53

Browse files
ewanharrisewanharris
authored
[SDK-3706] Update readme to match new design (#332)
1 parent 23a0350 commit d578c53

File tree

2 files changed

+176
-139
lines changed

2 files changed

+176
-139
lines changed

‎EXAMPLES.md

+125
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Examples
2+
3+
- [Integrations](#integrations)
4+
- [Configuration](#configuration)
5+
- [Caching](#caching)
6+
- [Rate Limiting](#rate-limiting)
7+
- [Using Request Agent for TLS/SSL Configuration](#using-request-agent-for-tlsssl-configuration)
8+
- [Proxy Configuration](#proxy-configuration)
9+
- [Loading keys from local file, environment variable, or other externals](#loading-keys-from-local-file-environment-variable-or-other-externals)
10+
- [Showing Trace Logs](#showing-trace-logs)
11+
12+
## Integrations
13+
14+
This repository holds a number of example integrations found in the [examples](./examples/) folder.
15+
16+
- [express/express-jwt](examples/express-demo)
17+
- [express/passport-jwt](examples/passport-demo)
18+
- [hapi/hapi-auth-jwt2](examples/hapi-demo)
19+
- [koa/koa-jwt](examples/koa-demo)
20+
21+
## Configuration
22+
23+
- `jwksUri`: a string that represents the JWKS URI
24+
- `timeout = 30000`: (_optional_) an integer in miliseconds that controls the request timeout
25+
- `cache = true`: (_optional_) enables a LRU Cache [(details)](#caching)
26+
- `rateLimit`: (_optional_) the default fetcher function [(details)](#rate-limiting)
27+
- `fetcher`: (_optional_) a Promise returning function to fetch data from the JWKS URI
28+
- `requestHeaders`: (_optional_) an object of headers to pass to the request
29+
- `requestAgent`: (_optional_) a Node `http.Agent` to be passed to the http(s) request
30+
- `getKeysInterceptor`: (_optional_) a promise returning function hook [(details)](#loading-keys-from-local-file-environment-variable-or-other-externals)
31+
- `cacheMaxAge`: (_optional_) the duration for which to store a cached JWKS in ms (default 600,000 or 10 minutes)
32+
- `jwksRequestsPerMinute`: (_optional_) max number of requests allowed to the JWKS URI per minute (defaults to 10)
33+
34+
## Caching
35+
36+
By default, signing key verification results are cached in order to prevent excessive HTTP requests to the JWKS endpoint. If a signing key matching the `kid` is found, this will be cached and the next time this `kid` is requested the signing key will be served from the cache. The caching behavior can be configured as seen below:
37+
38+
```js
39+
const jwksClient = require('jwks-rsa');
40+
41+
const client = jwksClient({
42+
cache: true, // Default Value
43+
cacheMaxEntries: 5, // Default value
44+
cacheMaxAge: 600000, // Defaults to 10m
45+
jwksUri: 'https://sandrino.auth0.com/.well-known/jwks.json'
46+
});
47+
48+
const kid = 'RkI5MjI5OUY5ODc1N0Q4QzM0OUYzNkVGMTJDOUEzQkFCOTU3NjE2Rg';
49+
const key = await client.getSigningKey(kid);
50+
const signingKey = key.getPublicKey();
51+
```
52+
53+
## Rate Limiting
54+
55+
Even if caching is enabled the library will call the JWKS endpoint if the `kid` is not available in the cache, because a key rotation could have taken place. To prevent attackers to send many random `kid`s you can also configure rate limiting. This will allow you to limit the number of calls that are made to the JWKS endpoint per minute (because it would be highly unlikely that signing keys are rotated multiple times per minute).
56+
57+
```js
58+
const jwksClient = require('jwks-rsa');
59+
60+
const client = jwksClient({
61+
rateLimit: true,
62+
jwksRequestsPerMinute: 10, // Default value
63+
jwksUri: 'https://sandrino.auth0.com/.well-known/jwks.json'
64+
});
65+
66+
const kid = 'RkI5MjI5OUY5ODc1N0Q4QzM0OUYzNkVGMTJDOUEzQkFCOTU3NjE2Rg';
67+
const key = await client.getSigningKey(kid);
68+
const signingKey = key.getPublicKey();
69+
```
70+
71+
## Using Request Agent for TLS/SSL Configuration
72+
73+
The `requestAgent` property can be used to configure SSL/TLS options. An
74+
example use case is providing a trusted private (i.e. enterprise/corporate) root
75+
certificate authority to establish TLS communication with the `jwks_uri`.
76+
77+
```js
78+
const jwksClient = require("jwks-rsa");
79+
const https = require('https');
80+
const client = jwksClient({
81+
jwksUri: 'https://my-enterprise-id-provider/.well-known/jwks.json',
82+
requestHeaders: {}, // Optional
83+
requestAgent: new https.Agent({
84+
ca: fs.readFileSync(caFile)
85+
})
86+
});
87+
```
88+
89+
## Proxy configuration
90+
91+
You can configure a proxy with using a [custom http(s) agent](https://github.com/TooTallNate/node-https-proxy-agent) in the `requestAgent` option.
92+
93+
## Loading keys from local file, environment variable, or other externals
94+
95+
The `getKeysInterceptor` property can be used to fetch keys before sending a request to the `jwksUri` endpoint. This can be helpful when wanting to load keys from a file, env variable, or an external cache. If a KID cannot be found in the keys returned from the interceptor, it will fallback to the `jwksUri` endpoint. This property will continue to work with the provided LRU cache, if the cache is enabled.
96+
97+
```js
98+
const client = new JwksClient({
99+
jwksUri: 'https://my-enterprise-id-provider/.well-known/jwks.json',
100+
getKeysInterceptor: () => {
101+
const file = fs.readFileSync(jwksFile);
102+
return file.keys;
103+
}
104+
});
105+
```
106+
107+
## Showing Trace Logs
108+
109+
To show trace logs you can set the following environment variable:
110+
111+
```
112+
DEBUG=jwks
113+
```
114+
115+
Output:
116+
117+
```
118+
jwks Retrieving keys from http://my-authz-server/.well-known/jwks.json +5ms
119+
jwks Keys: +8ms [ { alg: 'RS256',
120+
kty: 'RSA',
121+
use: 'sig',
122+
x5c: [ 'pk1' ],
123+
kid: 'ABC' },
124+
{ alg: 'RS256', kty: 'RSA', use: 'sig', x5c: [], kid: '123' } ]
125+
```

‎README.md

+51-139
Original file line numberDiff line numberDiff line change
@@ -1,171 +1,83 @@
1-
# jwks-rsa
1+
![A library to retrieve signing keys from a JWKS (JSON Web Key Set) endpoint.](https://cdn.auth0.com/website/sdks/banner/node-jwks-rsa-banner.png)
22

3-
[![CircleCI][circle-image]][circle-url]
4-
[![codecov][codecov-image]][codecov-url]
5-
[![NPM version][npm-image]][npm-url]
6-
[![License][license-image]][license-url]
7-
[![Downloads][downloads-image]][downloads-url]
8-
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fauth0%2Fnode-jwks-rsa.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fauth0%2Fnode-jwks-rsa?ref=badge_shield)
3+
![Release](https://img.shields.io/npm/v/jwks-rsa)
4+
[![Codecov](https://img.shields.io/codecov/c/github/auth0/node-jwks-rsa)](https://codecov.io/gh/auth0/node-jwks-rsa)
5+
![Downloads](https://img.shields.io/npm/dw/jwks-rsa)
6+
[![License](https://img.shields.io/:license-mit-blue.svg?style=flat)](https://opensource.org/licenses/MIT)
7+
![CircleCI](https://img.shields.io/circleci/build/github/auth0/node-jwks-rsa)
98

10-
A library to retrieve signing keys from a JWKS (JSON Web Key Set) endpoint.
9+
📚 [Documentation](#documentation) - 🚀 [Getting Started](#getting-started) - 💬 [Feedback](#feedback)
1110

12-
> npm install --save jwks-rsa
11+
## Documentation
1312

14-
Supports all currently registered JWK types and JWS Algorithms, see [panva/jose#262](https://github.com/panva/jose/issues/262) for more information.
13+
- [Examples](https://github.com/auth0/node-jwks-rsa/blob/master/EXAMPLES.md) - code samples for common scenarios.
14+
- [Docs Site](https://auth0.com/docs) - explore our Docs site and learn more about Auth0.
1515

16-
## Usage
16+
## Getting Started
1717

18-
You'll provide the client with the JWKS endpoint which exposes your signing keys. Using the `getSigningKey` you can then get the signing key that matches a specific `kid`.
18+
### Installation
1919

20-
```js
21-
const jwksClient = require('jwks-rsa');
20+
Using [npm](https://npmjs.org) in your project directory run the following command:
2221

23-
const client = jwksClient({
24-
jwksUri: 'https://sandrino.auth0.com/.well-known/jwks.json',
25-
requestHeaders: {}, // Optional
26-
timeout: 30000 // Defaults to 30s
27-
});
28-
29-
const kid = 'RkI5MjI5OUY5ODc1N0Q4QzM0OUYzNkVGMTJDOUEzQkFCOTU3NjE2Rg';
30-
const key = await client.getSigningKey(kid);
31-
const signingKey = key.getPublicKey();
32-
```
22+
````bash
23+
npm install --save jwks-rsa
24+
````
3325

34-
### Integrations
35-
36-
- [express/express-jwt](examples/express-demo)
37-
- [express/passport-jwt](examples/passport-demo)
38-
- [hapi/hapi-auth-jwt2](examples/hapi-demo)
39-
- [koa/koa-jwt](examples/koa-demo)
40-
41-
### API
42-
43-
#### JwksClient Options
44-
45-
- `jwksUri`: a string that represents the JWKS URI
46-
- `timeout = 30000`: (_optional_) an integer in miliseconds that controls the request timeout
47-
- `cache = true`: (_optional_) enables a LRU Cache [(details)](#caching)
48-
- `rateLimit`: (_optional_) the default fetcher function [(details)](#rate-limiting)
49-
- `fetcher`: (_optional_) a Promise returning function to fetch data from the JWKS URI
50-
- `requestHeaders`: (_optional_) an object of headers to pass to the request
51-
- `requestAgent`: (_optional_) a Node `http.Agent` to be passed to the http(s) request
52-
- `getKeysInterceptor`: (_optional_) a promise returning function hook [(details)](#loading-keys-from-local-file-environment-variable-or-other-externals)
53-
- `cacheMaxAge`: (_optional_) the duration for which to store a cached JWKS in ms (default 600,000 or 10 minutes)
54-
- `jwksRequestsPerMinute`: (_optional_) max number of requests allowed to the JWKS URI per minute (defaults to 10)
26+
Supports all currently registered JWK types and JWS Algorithms, see [panva/jose#262](https://github.com/panva/jose/issues/262) for more information.
5527

56-
### Caching
28+
### Configure the client
5729

58-
By default, signing key verification results are cached in order to prevent excessive HTTP requests to the JWKS endpoint. If a signing key matching the `kid` is found, this will be cached and the next time this `kid` is requested the signing key will be served from the cache. The caching behavior can be configured as seen below:
30+
Provide a JWKS endpoint which exposes your signing keys.
5931

60-
```js
32+
````js
6133
const jwksClient = require('jwks-rsa');
6234

6335
const client = jwksClient({
64-
cache: true, // Default Value
65-
cacheMaxEntries: 5, // Default value
66-
cacheMaxAge: 600000, // Defaults to 10m
67-
jwksUri: 'https://sandrino.auth0.com/.well-known/jwks.json'
36+
jwksUri: 'https://sandrino.auth0.com/.well-known/jwks.json',
37+
requestHeaders: {}, // Optional
38+
timeout: 30000 // Defaults to 30s
6839
});
40+
````
6941

70-
const kid = 'RkI5MjI5OUY5ODc1N0Q4QzM0OUYzNkVGMTJDOUEzQkFCOTU3NjE2Rg';
71-
const key = await client.getSigningKey(kid);
72-
const signingKey = key.getPublicKey();
73-
```
74-
75-
### Rate Limiting
76-
77-
Even if caching is enabled the library will call the JWKS endpoint if the `kid` is not available in the cache, because a key rotation could have taken place. To prevent attackers to send many random `kid`s you can also configure rate limiting. This will allow you to limit the number of calls that are made to the JWKS endpoint per minute (because it would be highly unlikely that signing keys are rotated multiple times per minute).
78-
79-
```js
80-
const jwksClient = require('jwks-rsa');
42+
### Retrieve a key
8143

82-
const client = jwksClient({
83-
rateLimit: true,
84-
jwksRequestsPerMinute: 10, // Default value
85-
jwksUri: 'https://sandrino.auth0.com/.well-known/jwks.json'
86-
});
44+
Then use `getSigningKey` to retrieve a signing key that matches a specific `kid`.
8745

46+
````js
8847
const kid = 'RkI5MjI5OUY5ODc1N0Q4QzM0OUYzNkVGMTJDOUEzQkFCOTU3NjE2Rg';
8948
const key = await client.getSigningKey(kid);
9049
const signingKey = key.getPublicKey();
91-
```
92-
93-
### Using Request Agent for TLS/SSL Configuration
94-
95-
The `requestAgent` property can be used to configure SSL/TLS options. An
96-
example use case is providing a trusted private (i.e. enterprise/corporate) root
97-
certificate authority to establish TLS communication with the `jwks_uri`.
98-
99-
```js
100-
const jwksClient = require("jwks-rsa");
101-
const https = require('https');
102-
const client = jwksClient({
103-
jwksUri: 'https://my-enterprise-id-provider/.well-known/jwks.json',
104-
requestHeaders: {}, // Optional
105-
requestAgent: new https.Agent({
106-
ca: fs.readFileSync(caFile)
107-
})
108-
});
109-
```
110-
111-
### Proxy configuration
112-
113-
You can configure a proxy with using a [custom http(s) agent](https://github.com/TooTallNate/node-https-proxy-agent) in the `requestAgent` option.
114-
115-
### Loading keys from local file, environment variable, or other externals
116-
117-
The `getKeysInterceptor` property can be used to fetch keys before sending a request to the `jwksUri` endpoint. This can be helpful when wanting to load keys from a file, env variable, or an external cache. If a KID cannot be found in the keys returned from the interceptor, it will fallback to the `jwksUri` endpoint. This property will continue to work with the provided LRU cache, if the cache is enabled.
118-
119-
```js
120-
const client = new JwksClient({
121-
jwksUri: 'https://my-enterprise-id-provider/.well-known/jwks.json',
122-
getKeysInterceptor: () => {
123-
const file = fs.readFileSync(jwksFile);
124-
return file.keys;
125-
}
126-
});
127-
```
128-
129-
## Running Tests
130-
131-
```
132-
npm run test
133-
```
50+
````
13451

135-
## Showing Trace Logs
52+
## Feedback
13653

137-
To show trace logs you can set the following environment variable:
54+
### Contributing
13855

139-
```
140-
DEBUG=jwks
141-
```
56+
We appreciate feedback and contribution to this repo! Before you get started, please see the following:
14257

143-
Output:
58+
- [Auth0's general contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
59+
- [Auth0's code of conduct guidelines](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
14460

145-
```
146-
jwks Retrieving keys from http://my-authz-server/.well-known/jwks.json +5ms
147-
jwks Keys: +8ms [ { alg: 'RS256',
148-
kty: 'RSA',
149-
use: 'sig',
150-
x5c: [ 'pk1' ],
151-
kid: 'ABC' },
152-
{ alg: 'RS256', kty: 'RSA', use: 'sig', x5c: [], kid: '123' } ]
153-
```
61+
### Raise an issue
15462

155-
## License
63+
To provide feedback or report a bug, please [raise an issue on our issue tracker](https://github.com/auth0/node-jwks-rsa/issues).
15664

157-
This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.
65+
### Vulnerability Reporting
15866

159-
[circle-image]: https://img.shields.io/circleci/build/github/auth0/node-jwks-rsa/master?style=flat-square
160-
[circle-url]: https://circleci.com/gh/auth0/node-jwks-rsa/tree/master
161-
[codecov-image]: https://img.shields.io/codecov/c/github/auth0/node-jwks-rsa?style=flat-square
162-
[codecov-url]: https://codecov.io/gh/auth0/node-jwks-rsa
163-
[npm-image]: https://img.shields.io/npm/v/jwks-rsa.svg?style=flat-square
164-
[npm-url]: https://npmjs.org/package/jwks-rsa
165-
[license-image]: http://img.shields.io/npm/l/jwks-rsa.svg?style=flat-square
166-
[license-url]: #license
167-
[downloads-image]: http://img.shields.io/npm/dm/jwks-rsa.svg?style=flat-square
168-
[downloads-url]: https://npmjs.org/package/jwks-rsa
67+
Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/whitehat) details the procedure for disclosing security issues.
16968

69+
## What is Auth0?
17070

171-
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fauth0%2Fnode-jwks-rsa.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fauth0%2Fnode-jwks-rsa?ref=badge_large)
71+
<p align="center">
72+
<picture>
73+
<source media="(prefers-color-scheme: dark)" srcset="https://cdn.auth0.com/website/sdks/logos/auth0_dark_mode.png" width="150">
74+
<source media="(prefers-color-scheme: light)" srcset="https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png" width="150">
75+
<img alt="Auth0 Logo" src="https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png" width="150">
76+
</picture>
77+
</p>
78+
<p align="center">
79+
Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout <a href="https://auth0.com/why-auth0">Why Auth0?</a>
80+
</p>
81+
<p align="center">
82+
This project is licensed under the MIT license. See the <a href="https://github.com/auth0/node-jwks-rsa/blob/master/LICENSE"> LICENSE</a> file for more info.
83+
</p>

0 commit comments

Comments
 (0)