Jwks RSA

JSON Web Key Set parser.

Programming language: Java

License: MIT License

Tags: Security     Projects    

Latest version: v0.21.2

README

:books: Documentation - :rocket: Getting Started - :computer: API Reference :speech_balloon: Feedback

Documentation

• [Examples](./EXAMPLES.md) - code samples for common jwks-rsa-java scenarios.
• Docs site - explore our docs site and learn more about Auth0.

Getting Started

Requirements

Java 8 or above.

Installation

Add the dependency via Maven:

<dependency>
  <groupId>com.auth0</groupId>
  <artifactId>jwks-rsa</artifactId>
  <version>0.21.2</version>
</dependency>

or Gradle:

implementation 'com.auth0:jwks-rsa:0.21.2'

Usage

The JSON Web Tokens you obtain from an authorization server include a key id header parameter ("kid"), used to uniquely identify the Key used to sign the token.

Given the following JWT:

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlJrSTVNakk1T1VZNU9EYzFOMFE0UXpNME9VWXpOa1ZHTVRKRE9VRXpRa0ZDT1RVM05qRTJSZyJ9.eyJpc3MiOiJodHRwczovL3NhbmRyaW5vLmF1dGgwLmNvbS8iLCJzdWIiOiJhdXRoMHw1NjMyNTAxZjQ2OGYwZjE3NTZmNGNhYjAiLCJhdWQiOiJQN2JhQnRTc3JmQlhPY3A5bHlsMUZEZVh0ZmFKUzRyViIsImV4cCI6MTQ2ODk2NDkyNiwiaWF0IjoxNDY4OTI4OTI2fQ.NaNeRSDCNu522u4hcVhV65plQOiGPStgSzVW4vR0liZYQBlZ_3OKqCmHXsu28NwVHW7_KfVgOz4m3BK6eMDZk50dAKf9LQzHhiG8acZLzm5bNMU3iobSAJdRhweRht544ZJkzJ-scS1fyI4gaPS5aD3SaLRYWR0Xsb6N1HU86trnbn-XSYSspNqzIUeJjduEpPwC53V8E2r1WZXbqEHwM9_BGEeNTQ8X9NqCUvbQtnylgYR3mfJRL14JsCWNFmmamgNNHAI0uAJo84mu_03I25eVuCK0VYStLPd0XFEyMVFpk48Bg9KNWLMZ7OUGTB_uv_1u19wKYtqeTbt9m1YcPMQ

Decode it using a JWT library or tool like jwt.io and extract the kid parameter from the Header claims.

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "RkI5MjI5OUY5ODc1N0Q4QzM0OUYzNkVGMTJDOUEzQkFCOTU3NjE2Rg"
}

The kid value can then be used to obtain the JWK using a JwkProvider.

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:

JwkProvider provider = new JwkProviderBuilder("https://samples.auth0.com/")
    .build();

A Jwk can be obtained using the get(String keyId) method:

java Jwk jwk = provider.get("{kid of the signing key}"); // throws Exception when not found or can't get one

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:

JwkProvider provider = new JwkProviderBuilder("https://samples.auth0.com/")
        // up to 10 JWKs will be cached for up to 24 hours
        .cached(10, 24, TimeUnit.HOURS)
        // up to 10 JWKs can be retrieved within one minute
        .rateLimited(10, 1, TimeUnit.MINUTES)
        .build();

See the [examples](./EXAMPLES.md) for additional configurations.

API Reference

• jwks-rsa-java JavaDocs

Feedback

Contributing

We appreciate feedback and contribution to this repo! Before you get started, please see the following:

• Auth0's general contribution guidelines
• [Auth0's code of conduct guidelines]((https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md))

Raise an issue

To provide feedback or report a bug, please raise an issue on our issue tracker.

Vulnerability Reporting

Please do not report security vulnerabilities on the public Github issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

---

Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout Why Auth0? This project is licensed under the MIT license. See the LICENSE file for more info.