jjwt/README.md

89 lines
2.9 KiB
Markdown
Raw Normal View History

[![Build Status](https://travis-ci.org/jwtk/jjwt.svg?branch=master)](https://travis-ci.org/jwtk/jjwt)
2014-09-12 21:06:24 -04:00
2014-09-23 17:13:50 -04:00
# Java JWT: JSON Web Token for Java
2014-09-18 22:14:22 -04:00
2014-09-25 16:52:02 -04:00
JJWT aims to be the easiest to use and understand library for creating and verifying JSON Web Tokens (JWTs) on the JVM.
2014-09-25 16:51:08 -04:00
JJWT is a 'clean room' implementation based solely on the [JWT](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-25), [JWS](https://tools.ietf.org/html/draft-ietf-jose-json-web-signature-31), [JWE](https://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-31) and [JWA](https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-31) RFC draft specifications.
2014-09-25 16:49:59 -04:00
## Installation
Use your favorite Maven-compatible build tool to pull the dependency (and its transitive dependencies) from Maven Central:
```xml
<dependency>
<groupId>io.jsonwebtoken</groupId>
<artifactId>jjwt</artifactId>
<version>0.1</version>
</dependency>
```
## Usage
Most complexity is hidden behind convenient and readable Builder chaining calls. Here's an example:
2014-09-18 22:14:22 -04:00
2014-09-19 17:47:01 -04:00
```java
import io.jsonwebtoken.Jwts;
import static io.jsonwebtoken.SignatureAlgorithm.*;
2014-09-19 17:47:01 -04:00
//Let's create a random signing key for testing:
Random random = new SecureRandom();
byte[] key = new byte[64];
random.nextBytes(key);
2014-09-18 22:14:22 -04:00
Claims claims = Jwts.claims().setIssuer("Me").setSubject("Joe");
2014-09-18 22:14:22 -04:00
String jwt = Jwts.builder().setClaims(claims).signWith(HS256, key).compact();
2014-09-19 17:47:01 -04:00
```
2014-09-18 22:14:22 -04:00
How easy was that!?
Now let's verify the JWT (you should always discard JWTs that don't match an expected signature):
2014-09-19 17:47:01 -04:00
```java
Token token = Jwts.parser().setSigningKey(key).parse(jwt);
2014-09-18 22:14:22 -04:00
2014-09-19 17:47:01 -04:00
assert token.getClaims().getSubject().equals("Joe");
```
2014-09-18 22:14:22 -04:00
You have to love one-line code snippets in Java!
But what if signature validation failed? You can catch `SignatureException` and react accordingly:
2014-09-19 17:47:01 -04:00
```java
try {
2014-09-18 22:14:22 -04:00
Jwts.parser().setSigningKey(key).parse(jwt);
2014-09-18 22:14:22 -04:00
2014-09-19 17:47:01 -04:00
//OK, we can trust this JWT
2014-09-18 22:14:22 -04:00
2014-09-19 17:47:01 -04:00
} catch (SignatureException e) {
2014-09-18 22:14:22 -04:00
2014-09-19 17:47:01 -04:00
//don't trust the JWT!
}
```
2014-09-18 22:14:22 -04:00
## Supported Features
2014-09-19 17:30:47 -04:00
* Creating and parsing plaintext compact JWTs
2014-09-18 22:14:22 -04:00
2014-09-25 16:42:16 -04:00
* Creating, parsing and verifying digitally signed compact JWTs (aka JWSs) with the following algorithms:
2014-09-18 22:14:22 -04:00
* HS256: HMAC using SHA-384
* HS384: HMAC using SHA-384
* HS512: HMAC using SHA-512
* RS256: RSASSA-PKCS-v1_5 using SHA-256
* RS384: RSASSA-PKCS-v1_5 using SHA-384
* RS512: RSASSA-PKCS-v1_5 using SHA-512
* PS256: RSASSA-PSS using SHA-256 and MGF1 with SHA-256
* PS384: RSASSA-PSS using SHA-384 and MGF1 with SHA-384
* PS512: RSASSA-PSS using SHA-512 and MGF1 with SHA-512
## Currently Unsupported Features
2014-09-25 16:43:41 -04:00
* [Non-compact](https://tools.ietf.org/html/draft-ietf-jose-json-web-signature-31#section-7.2) serialization and parsing.
* Elliptic Curve signature algorithms `ES256`, `ES384` and `ES512`.
* JWE (Encryption for JWT)
2014-09-18 22:14:22 -04:00
2014-09-19 17:30:47 -04:00
These feature sets will be implemented in a future release when possible. Community contributions are welcome!