Skip to content

Commit 0c7f4e0

Browse files
jimmyjamesjimmyjames
authored
[SDK-3695] Update README based on new design (#158)
1 parent 49dcb15 commit 0c7f4e0

File tree

2 files changed

+157
-128
lines changed

2 files changed

+157
-128
lines changed

‎EXAMPLES.md

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Examples using jwks-rsa-java
2+
3+
- [Provider configuration](#provider-configuration)
4+
- [Error handling](#error-handling)
5+
6+
## Provider configuration
7+
8+
This library contains several `JwkProvider` implementations, which is used to obtain a JWK.
9+
10+
The `JwkProviderBuilder` is the preferred way to create a `JwkProvider`. Configurations can be combined to suit your needs.
11+
12+
### Cache retrieved JWK
13+
14+
To create a provider for domain `https://samples.auth0.com` that will cache a JWK using an LRU in-memory cache:
15+
16+
```java
17+
JwkProvider provider = new JwkProviderBuilder("https://samples.auth0.com/")
18+
// cache up to 10 JWKs for up to 24 hours
19+
.cached(10, 24, TimeUnit.HOURS)
20+
.build();
21+
```
22+
23+
### Configure rate limits
24+
25+
`RateLimitJwkProvider` will limit the amounts of different signing keys to get in a given time frame.
26+
27+
> By default the rate is limited to 10 different keys per minute but these values can be changed.
28+
29+
```java
30+
JwkProvider provider = new JwkProviderBuilder("https://samples.auth0.com/")
31+
// up to 10 JWKs can be retrieved within one minute
32+
.rateLimited(10, 1, TimeUnit.MINUTES)
33+
.build();
34+
```
35+
36+
### Configure network timeout settings
37+
38+
The connect and read network timeouts can be configured using the builder:
39+
40+
```java
41+
JwkProvider provider = new JwkProviderBuilder("https://samples.auth0.com/")
42+
// Connect timeout of 1 second, read timeout of 2 seconds (values are in milliseconds)
43+
.timeouts(1000, 2000)
44+
.build();
45+
```
46+
47+
See the [JwkProviderBuilder JavaDocs](https://javadoc.io/doc/com.auth0/jwks-rsa/latest/com/auth0/jwk/JwkProviderBuilder.html) for all available configurations.
48+
49+
## Error handling
50+
51+
There are certain scenarios in which this library can fail. Read below to understand what to expect and how to handle the errors.
52+
53+
### Missing JSON Web Key
54+
This error may arise when the hosted JSON Web Key set (JWKS) file doesn't represent a valid set of keys, or is empty.
55+
They are raised as a `SigningKeyNotFoundException`. The cause should to be inspected in order to understand the specific failure reason.
56+
57+
#### Network error
58+
There's a special case for Network errors. These errors represent timeouts, invalid URLs, or a faulty internet connection.
59+
They may occur when fetching the keys from the given URL. They are raised as a `NetworkException` instance.
60+
61+
If you need to detect this scenario, make sure to check it before the catch of `SigningKeyNotFoundException`.
62+
63+
```java
64+
try {
65+
// ...
66+
} catch (NetworkException e) {
67+
// Network error
68+
} catch (SigningKeyNotFoundException e) {
69+
// Key is invalid or not found
70+
}
71+
```
72+
73+
### Unsupported JSON Web Key
74+
When the received key is not of a supported type, or the attribute values representing it are wrong, an `InvalidPublicKeyException` will be raised.
75+
The following key types are supported:
76+
- RSA
77+
- Elliptic Curve
78+
- P-256
79+
- P-384
80+
- P-521
81+
82+
### Rate limits
83+
When using a rate-limited provider, a `RateLimitReachedException` error will be raised when the limit is breached.
84+
The exception can help determine how long to wait until the next call is available.
85+
86+
```java
87+
try {
88+
// ...
89+
} catch (RateLimitReachedException e) {
90+
long waitTime = e.getAvailableIn()
91+
// wait until available
92+
}
93+
```

‎README.md

Lines changed: 64 additions & 128 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,52 @@
1-
# jwks-rsa
1+
![A Java library for obtaining JSON Web Keys from a JWKS (JSON Web Key Set) endpoint.](https://cdn.auth0.com/website/sdks/banners/jwks-rsa-java-banner.png)
22

3-
[![CircleCI](https://circleci.com/gh/auth0/jwks-rsa-java.svg?style=svg)](https://circleci.com/gh/auth0/jwks-rsa-java)
4-
[![Maven Central](https://img.shields.io/maven-central/v/com.auth0/jwks-rsa.svg)](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%20com.auth0%20a%3Ajwks-rsa)
5-
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fauth0%2Fjwks-rsa-java.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fauth0%2Fjwks-rsa-java?ref=badge_shield)
3+
[![CircleCI](https://img.shields.io/circleci/project/github/auth0/jwks-rsa-java.svg?style=flat-square)](https://circleci.com/gh/auth0/jwks-rsa-java/tree/master)
4+
[![Coverage Status](https://codecov.io/gh/auth0/jwks-rsa-java/branch/master/graph/badge.svg?style=flat-square)](https://codecov.io/github/auth0/jwks-rsa-java)
5+
[![License](http://img.shields.io/:license-mit-blue.svg?style=flat)](https://doge.mit-license.org/)
6+
[![Maven Central](https://img.shields.io/maven-central/v/com.auth0/jwks-rsa.svg?style=flat-square)](https://search.maven.org/#search%7Cga%7C1%7Cg%3A%20com.auth0%20a%3Ajwks-rsa)
7+
[![javadoc](https://javadoc.io/badge2/com.auth0/jwks-rsa-java/javadoc.svg)](https://javadoc.io/doc/com.auth0/jwks-rsa)
68

7-
## Install
9+
:books: [Documentation](#documentation) - :rocket: [Getting Started](#getting-started) - :computer: [API Reference](#api-reference) :speech_balloon: [Feedback](#feedback)
810

9-
### Maven
11+
## Documentation
12+
- [Examples](./EXAMPLES.md) - code samples for common jwks-rsa-java scenarios.
13+
- [Docs site](https://www.auth0.com/docs) - explore our docs site and learn more about Auth0.
14+
15+
## Getting Started
16+
17+
### Requirements
18+
19+
Java 8 or above.
20+
21+
### Installation
22+
23+
Add the dependency via Maven:
1024

1125
```xml
1226
<dependency>
13-
<groupId>com.auth0</groupId>
14-
<artifactId>jwks-rsa</artifactId>
15-
<version>0.21.2</version>
27+
<groupId>com.auth0</groupId>
28+
<artifactId>jwks-rsa</artifactId>
29+
<version>0.21.2</version>
1630
</dependency>
1731
```
1832

19-
### Gradle
33+
or Gradle:
2034

2135
```gradle
2236
implementation 'com.auth0:jwks-rsa:0.21.2'
2337
```
2438

25-
## Usage
39+
### Usage
2640

27-
The JSON Web Tokens you get from the Authorization Server include a [key id](https://tools.ietf.org/html/rfc7515#section-4.1.4) header parameter ("kid"), used to uniquely identify the Key used to sign the token.
41+
The JSON Web Tokens you obtain from an authorization server include a [key id](https://tools.ietf.org/html/rfc7515#section-4.1.4) header parameter ("kid"), used to uniquely identify the Key used to sign the token.
2842

29-
i.e.: Given the following JWT:
43+
Given the following JWT:
3044

3145
```
3246
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlJrSTVNakk1T1VZNU9EYzFOMFE0UXpNME9VWXpOa1ZHTVRKRE9VRXpRa0ZDT1RVM05qRTJSZyJ9.eyJpc3MiOiJodHRwczovL3NhbmRyaW5vLmF1dGgwLmNvbS8iLCJzdWIiOiJhdXRoMHw1NjMyNTAxZjQ2OGYwZjE3NTZmNGNhYjAiLCJhdWQiOiJQN2JhQnRTc3JmQlhPY3A5bHlsMUZEZVh0ZmFKUzRyViIsImV4cCI6MTQ2ODk2NDkyNiwiaWF0IjoxNDY4OTI4OTI2fQ.NaNeRSDCNu522u4hcVhV65plQOiGPStgSzVW4vR0liZYQBlZ_3OKqCmHXsu28NwVHW7_KfVgOz4m3BK6eMDZk50dAKf9LQzHhiG8acZLzm5bNMU3iobSAJdRhweRht544ZJkzJ-scS1fyI4gaPS5aD3SaLRYWR0Xsb6N1HU86trnbn-XSYSspNqzIUeJjduEpPwC53V8E2r1WZXbqEHwM9_BGEeNTQ8X9NqCUvbQtnylgYR3mfJRL14JsCWNFmmamgNNHAI0uAJo84mu_03I25eVuCK0VYStLPd0XFEyMVFpk48Bg9KNWLMZ7OUGTB_uv_1u19wKYtqeTbt9m1YcPMQ
3347
```
3448

35-
Decode it using any JWT library or tool like [jwt.io](https://jwt.io/?value=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlJrSTVNakk1T1VZNU9EYzFOMFE0UXpNME9VWXpOa1ZHTVRKRE9VRXpRa0ZDT1RVM05qRTJSZyJ9.eyJpc3MiOiJodHRwczovL3NhbmRyaW5vLmF1dGgwLmNvbS8iLCJzdWIiOiJhdXRoMHw1NjMyNTAxZjQ2OGYwZjE3NTZmNGNhYjAiLCJhdWQiOiJQN2JhQnRTc3JmQlhPY3A5bHlsMUZEZVh0ZmFKUzRyViIsImV4cCI6MTQ2ODk2NDkyNiwiaWF0IjoxNDY4OTI4OTI2fQ.NaNeRSDCNu522u4hcVhV65plQOiGPStgSzVW4vR0liZYQBlZ_3OKqCmHXsu28NwVHW7_KfVgOz4m3BK6eMDZk50dAKf9LQzHhiG8acZLzm5bNMU3iobSAJdRhweRht544ZJkzJ-scS1fyI4gaPS5aD3SaLRYWR0Xsb6N1HU86trnbn-XSYSspNqzIUeJjduEpPwC53V8E2r1WZXbqEHwM9_BGEeNTQ8X9NqCUvbQtnylgYR3mfJRL14JsCWNFmmamgNNHAI0uAJo84mu_03I25eVuCK0VYStLPd0XFEyMVFpk48Bg9KNWLMZ7OUGTB_uv_1u19wKYtqeTbt9m1YcPMQ) and extract the `kid` parameter from the Header claims.
49+
Decode it using a JWT library or tool like [jwt.io](https://jwt.io/?value=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlJrSTVNakk1T1VZNU9EYzFOMFE0UXpNME9VWXpOa1ZHTVRKRE9VRXpRa0ZDT1RVM05qRTJSZyJ9.eyJpc3MiOiJodHRwczovL3NhbmRyaW5vLmF1dGgwLmNvbS8iLCJzdWIiOiJhdXRoMHw1NjMyNTAxZjQ2OGYwZjE3NTZmNGNhYjAiLCJhdWQiOiJQN2JhQnRTc3JmQlhPY3A5bHlsMUZEZVh0ZmFKUzRyViIsImV4cCI6MTQ2ODk2NDkyNiwiaWF0IjoxNDY4OTI4OTI2fQ.NaNeRSDCNu522u4hcVhV65plQOiGPStgSzVW4vR0liZYQBlZ_3OKqCmHXsu28NwVHW7_KfVgOz4m3BK6eMDZk50dAKf9LQzHhiG8acZLzm5bNMU3iobSAJdRhweRht544ZJkzJ-scS1fyI4gaPS5aD3SaLRYWR0Xsb6N1HU86trnbn-XSYSspNqzIUeJjduEpPwC53V8E2r1WZXbqEHwM9_BGEeNTQ8X9NqCUvbQtnylgYR3mfJRL14JsCWNFmmamgNNHAI0uAJo84mu_03I25eVuCK0VYStLPd0XFEyMVFpk48Bg9KNWLMZ7OUGTB_uv_1u19wKYtqeTbt9m1YcPMQ) and extract the `kid` parameter from the Header claims.
3650

3751
```json
3852
{
@@ -42,140 +56,62 @@ Decode it using any JWT library or tool like [jwt.io](https://jwt.io/?value=eyJ0
4256
}
4357
```
4458

45-
Use this `kid` on any of the `JwkProviders` enumerated below to obtain the signing key provided by the JWKS endpoint you've configured.
46-
47-
48-
### UrlJwkProvider
49-
50-
`UrlJwkProvider` fetches the jwk from `/.well-known/jwks.json` of the supplied domain issuer and returns a `Jwk` if the `kid` matches one of the registered keys.
51-
52-
```java
53-
JwkProvider provider = new UrlJwkProvider("https://samples.auth0.com/");
54-
Jwk jwk = provider.get("{kid of the signing key}"); //throws Exception when not found or can't get one
55-
```
56-
59+
The `kid` value can then be used to obtain the JWK using a `JwkProvider`.
5760

58-
Also it can load `jwks.json` file from any given Url (even to a local file in your filesystem).
59-
60-
```java
61-
JwkProvider provider = new UrlJwkProvider(new URL("https://samples.auth0.com/"));
62-
Jwk jwk = provider.get("{kid of the signing key}"); //throws Exception when not found or can't get one
63-
```
64-
65-
### GuavaCachedJwkProvider
66-
67-
`GuavaCachedJwkProvider` cache the jwk in a LRU in memory cache, if the jwk is not found in the cache it will ask another provider for it and store it's result in the cache.
68-
69-
> By default it stores 5 keys for 10 minutes, but these values can be changed.
70-
71-
```java
72-
JwkProvider http = new UrlJwkProvider("https://samples.auth0.com/");
73-
JwkProvider provider = new GuavaCachedJwkProvider(http);
74-
Jwk jwk = provider.get("{kid of the signing key}"); //throws Exception when not found or can't get one
75-
```
76-
77-
### RateLimitJwkProvider
78-
79-
`RateLimitJwkProvider` will limit the amounts of different signing keys to get in a given time frame.
80-
81-
> By default the rate is limited to 10 different keys per minute but these values can be changed.
82-
83-
```java
84-
JwkProvider url = new UrlJwkProvider("https://samples.auth0.com/");
85-
Bucket bucket = new Bucket(10, 1, TimeUnit.MINUTES);
86-
JwkProvider provider = new RateLimitJwkProvider(url, bucket);
87-
Jwk jwk = provider.get("{kid of the signing key}"); //throws Exception when not found or can't get one
88-
```
89-
90-
### JwkProviderBuilder
91-
92-
To create a provider for domain `https://samples.auth0.com` with cache and rate limit:
93-
94-
```java
95-
JwkProvider provider = new JwkProviderBuilder("https://samples.auth0.com/")
96-
.build();
97-
Jwk jwk = provider.get("{kid of the signing key}"); //throws Exception when not found or can't get one
98-
```
99-
100-
and specifying cache and rate limit attributes:
61+
Create a `JWKProvider` using the domain from which to fetch the JWK. The provider will use the domain to build the URL `https:{your-domain}/.well-known/jwks.json`:
10162

10263
```java
10364
JwkProvider provider = new JwkProviderBuilder("https://samples.auth0.com/")
104-
.cached(10, 24, TimeUnit.HOURS)
105-
.rateLimited(10, 1, TimeUnit.MINUTES)
10665
.build();
107-
Jwk jwk = provider.get("{kid of the signing key}"); //throws Exception when not found or can't get one
10866
```
10967

110-
## Error handling
111-
There are certain scenarios in which this library can fail. Read below to understand what to expect and how to handle the errors.
112-
113-
### Missing JSON Web Key
114-
This error may arise when the hosted JSON Web Key set (JWKS) file doesn't represent a valid set of keys, or is empty. They are raised as a `SigningKeyNotFoundException`. The cause would need to be inspected in order to understand the specific failure reason.
68+
A `Jwk` can be obtained using the `get(String keyId)` method:
11569

116-
#### Network error
117-
There's a special case for Network errors. These errors represent timeouts, invalid URLs, or a faulty internet connection. They may occur when fetching the keys from the given URL. They are raised as a `NetworkException` instance.
70+
``java
71+
Jwk jwk = provider.get("{kid of the signing key}"); // throws Exception when not found or can't get one
72+
``
11873

119-
If you need to detect this scenario, make sure to check it before the catch of `SigningKeyNotFoundException`.
74+
The provider can be configured to cache JWKs to avoid unnecessary network requests, as well as only fetch the JWKs within a defined rate limit:
12075

12176
```java
122-
try {
123-
// ...
124-
} catch (NetworkException e) {
125-
// Network error
126-
} catch (SigningKeyNotFoundException e) {
127-
// Key is invalid or not found
128-
}
77+
JwkProvider provider = new JwkProviderBuilder("https://samples.auth0.com/")
78+
// up to 10 JWKs will be cached for up to 24 hours
79+
.cached(10, 24, TimeUnit.HOURS)
80+
// up to 10 JWKs can be retrieved within one minute
81+
.rateLimited(10, 1, TimeUnit.MINUTES)
82+
.build();
12983
```
13084

131-
### Unsupported JSON Web Key
132-
When the received key is not of a supported type, or the attribute values representing it are wrong, an `InvalidPublicKeyException` will be raised.
133-
The following key types are supported:
134-
- RSA
135-
- Elliptic Curve
136-
- P-256
137-
- P-384
138-
- P-521
139-
140-
### Rate limits
141-
When using a rate-limited provider, a `RateLimitReachedException` error might be raised when the limit is breached. The instance can help determine how long to wait until the next call would be available.
142-
143-
```java
144-
try {
145-
// ...
146-
} catch (RateLimitReachedException e) {
147-
long waitTime = e.getAvailableIn()
148-
// wait until available
149-
}
150-
```
151-
152-
## What is Auth0?
153-
154-
Auth0 helps you to:
155-
156-
* Add authentication with [multiple authentication sources](https://docs.auth0.com/identityproviders), either social like **Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce, amont others**, or enterprise identity systems like **Windows Azure AD, Google Apps, Active Directory, ADFS or any SAML Identity Provider**.
157-
* Add authentication through more traditional **[username/password databases](https://docs.auth0.com/mysql-connection-tutorial)**.
158-
* Add support for **[linking different user accounts](https://docs.auth0.com/link-accounts)** with the same user.
159-
* Support for generating signed [Json Web Tokens](https://docs.auth0.com/jwt) to call your APIs and **flow the user identity** securely.
160-
* Analytics of how, when and where users are logging in.
161-
* Pull data from other sources and add it to the user profile, through [JavaScript rules](https://docs.auth0.com/rules).
85+
See the [examples](./EXAMPLES.md) for additional configurations.
16286

163-
## Create a free Auth0 Account
87+
## API Reference
16488

165-
1. Go to [Auth0](https://auth0.com) and click Sign Up.
166-
2. Use Google, GitHub or Microsoft Account to login.
89+
- [jwks-rsa-java JavaDocs](https://javadoc.io/doc/com.auth0/jwks-rsa/latest/)
16790

168-
## Issue Reporting
91+
## Feedback
16992

170-
If you have found a bug or if you have a feature request, please report them at this repository issues section. 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.
93+
### Contributing
17194

172-
## Author
95+
We appreciate feedback and contribution to this repo! Before you get started, please see the following:
17396

174-
[Auth0](https://auth0.com)
97+
- [Auth0's general contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
98+
- [Auth0's code of conduct guidelines]((https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md))
17599

176-
## License
100+
### Raise an issue
101+
To provide feedback or report a bug, [please raise an issue on our issue tracker](https://github.com/auth0/jwks-rsa-java/issues).
177102

178-
This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.
103+
### Vulnerability Reporting
104+
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.
179105

106+
---
180107

181-
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fauth0%2Fjwks-rsa-java.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fauth0%2Fjwks-rsa-java?ref=badge_large)
108+
<p align="center">
109+
<picture>
110+
<source media="(prefers-color-scheme: light)" srcset="https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png" width="150">
111+
<source media="(prefers-color-scheme: dark)" srcset="https://cdn.auth0.com/website/sdks/logos/auth0_dark_mode.png" width="150">
112+
<img alt="Auth0 Logo" src="./auth0_light_mode.png" width="150">
113+
</picture>
114+
</p>
115+
<p align="center">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></p>
116+
<p align="center">
117+
This project is licensed under the MIT license. See the <a href="./LICENSE"> LICENSE</a> file for more info.</p>

0 commit comments

Comments
 (0)