Skip to content

Commit f5bf2cc

Browse files
lbalmacedalbalmaceda
committed
add readme
1 parent a9a3488 commit f5bf2cc

1 file changed

Lines changed: 210 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
2+
3+
# Java JWT [v3]
4+
5+
[![Build Status](https://travis-ci.org/auth0/java-jwt.svg?branch=v3)](https://travis-ci.org/auth0/java-jwt)
6+
[![Coverage Status](https://img.shields.io/codecov/c/github/auth0/java-jwt/v3.svg?style=flat-square)](https://codecov.io/github/auth0/java-jwt)
7+
[![License](http://img.shields.io/:license-mit-blue.svg?style=flat)](http://doge.mit-license.org)
8+
9+
An implementation of [JSON Web Tokens](http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html) developed against `draft-ietf-oauth-json-web-token-08`.
10+
11+
## Installation
12+
13+
### Gradle
14+
15+
```gradle
16+
compile 'com.auth0:java-jwt:3.0.+'
17+
```
18+
19+
## Usage
20+
21+
### Decode a Token
22+
23+
```java
24+
String token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJpc3MiOiJhdXRoMCJ9.AbIJTDMFc7yUa5MhvcP03nJPyCPzZtQcGEp-zWfOkEE";
25+
try {
26+
JWT jwt = JWT.decode(token);
27+
} catch (JWTDecodeException exception){
28+
//Invalid token
29+
}
30+
```
31+
32+
If the token has an invalid syntax or the header or payload are not JSONs, a `JWTDecodeException` will raise.
33+
34+
### Verify a Token
35+
36+
37+
The library implements JWT Verification using the following algorithms:
38+
39+
| JWS | Algorithm | Description |
40+
| :-------------: | :-------------: | :----- |
41+
| HS256 | HMAC256 | HMAC with SHA-256 |
42+
| HS384 | HMAC384 | HMAC with SHA-384 |
43+
| HS512 | HMAC512 | HMAC with SHA-512 |
44+
| RS256 | RSA256 | RSASSA-PKCS1-v1_5 with SHA-256 |
45+
| RS384 | RSA384 | RSASSA-PKCS1-v1_5 with SHA-384 |
46+
| RS512 | RSA512 | RSASSA-PKCS1-v1_5 with SHA-512 |
47+
| ES256 | ECDSA256 | ECDSA with curve P-256 and SHA-256 |
48+
| ES384 | ECDSA384 | ECDSA with curve P-384 and SHA-384 |
49+
| ES512 | ECDSA512 | ECDSA with curve P-521 and SHA-512 |
50+
51+
You'll first need to create a `JWTVerifier` instance by calling `JWT.require()` and passing the Algorithm instance. If you require the token to have specific Claim values, use the builder to define them. The instance returned by the method `build()` is reusable, so you can define it once and use it to verify different tokens. Finally call `verifier.verify()` passing the token.
52+
53+
* Example using `HS256`
54+
55+
```java
56+
String token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJpc3MiOiJhdXRoMCJ9.AbIJTDMFc7yUa5MhvcP03nJPyCPzZtQcGEp-zWfOkEE";
57+
try {
58+
JWTVerifier verifier = JWT.require(Algorithm.HMAC256("secret"))
59+
.withIssuer("auth0")
60+
.build(); //Reusable verifier instance
61+
JWT jwt = verifier.verify(token);
62+
} catch (JWTDecodeException exception){
63+
//Invalid token
64+
} catch (JWTVerificationException exception){
65+
//Invalid signature/claims
66+
}
67+
```
68+
69+
* Example using `RS256`
70+
71+
```java
72+
String token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJpc3MiOiJhdXRoMCJ9.AbIJTDMFc7yUa5MhvcP03nJPyCPzZtQcGEp-zWfOkEE";
73+
PublicKey key = //Get the key instance
74+
try {
75+
JWTVerifier verifier = JWT.require(Algorithm.RSA256(key))
76+
.withIssuer("auth0")
77+
.build(); //Reusable verifier instance
78+
JWT jwt = verifier.verify(token);
79+
} catch (JWTDecodeException exception){
80+
//Invalid token
81+
} catch (JWTVerificationException exception){
82+
//Invalid signature/claims
83+
}
84+
```
85+
86+
If the token has an invalid syntax or the header or payload are not JSONs, a `JWTDecodeException` will raise.
87+
If the token has an invalid signature or the Claim requirement is not met, a `JWTVerificationException` will raise.
88+
89+
90+
### Registered Claims
91+
92+
#### Issuer ("iss")
93+
94+
Returns the Issuer value or null if it's not defined.
95+
96+
```java
97+
String issuer = jwt.getIssuer();
98+
```
99+
100+
#### Subject ("sub")
101+
102+
Returns the Subject value or null if it's not defined.
103+
104+
```java
105+
String subject = jwt.getSubject();
106+
```
107+
108+
#### Audience ("aud")
109+
110+
Returns the Audience value in or null if it's not defined.
111+
112+
```java
113+
String[] audience = jwt.getAudience();
114+
```
115+
116+
#### Expiration Time ("exp")
117+
118+
Returns the Expiration Time value or null if it's not defined.
119+
120+
```java
121+
Date expiresAt = jwt.getExpiresAt();
122+
```
123+
124+
#### Not Before ("nbf")
125+
126+
Returns the Not Before value or null if it's not defined.
127+
128+
```java
129+
Date notBefore = jwt.getNotBefore();
130+
```
131+
132+
#### Issued At ("iat")
133+
134+
Returns the Issued At value or null if it's not defined.
135+
136+
```java
137+
Date issuedAt = jwt.getIssuedAt();
138+
```
139+
140+
#### JWT ID ("jti")
141+
142+
Returns the JWT ID value or null if it's not defined.
143+
144+
```java
145+
String id = jwt.getId();
146+
```
147+
148+
#### Time Validation
149+
150+
The JWT token may include DateNumber fields that can be used to validate that the token was issued in a past date `"iat" < TODAY` and that the expiration date is in the future `"exp" > TODAY`. This library includes a method that checks both of this fields and returns the validity of the token. If any of the fields is missing they won't be considered.
151+
152+
```java
153+
boolean isExpired = jwt.isExpired();
154+
```
155+
156+
### Private Claims
157+
158+
Additional Claims defined in the token can be obtained by calling `getClaim()` and passing the Claim name. A Claim will always be returned, even if it can't be found.
159+
160+
```java
161+
Claim claim = jwt.getClaim("isAdmin");
162+
```
163+
164+
### Claim Class
165+
The Claim class is a wrapper for the Claim values. It allows you to get the Claim as different class types. The available helpers are:
166+
167+
#### Primitives
168+
* **asBoolean()**: Returns the Boolean value or null if it can't be converted.
169+
* **asInt()**: Returns the Integer value or null if it can't be converted.
170+
* **asDouble()**: Returns the Double value or null if it can't be converted.
171+
* **asString()**: Returns the String value or null if it can't be converted.
172+
* **asDate()**: Returns the Date value or null if it can't be converted. Note that the [JWT Standard](https://tools.ietf.org/html/rfc7519#section-2) specified that all the *NumericDate* values must be in seconds.
173+
174+
#### Collections
175+
To obtain a Claim as a Collection you'll need to provide the **Class Type** of the contents to convert from.
176+
177+
* **asArray(class)**: Returns the value parsed as an Array of elements of type **Class Type**, or null if the value isn't a JSON Array.
178+
* **asList(class)**: Returns the value parsed as a List of elements of type **Class Type**, or null if the value isn't a JSON Array.
179+
180+
If the values inside the JSON Array can't be converted to the given **Class Type**, a `JWTDecodeException` will raise.
181+
182+
183+
184+
## What is Auth0?
185+
186+
Auth0 helps you to:
187+
188+
* Add authentication with [multiple authentication sources](https://docs.auth0.com/identityproviders), either social like **Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce, among others**, or enterprise identity systems like **Windows Azure AD, Google Apps, Active Directory, ADFS or any SAML Identity Provider**.
189+
* Add authentication through more traditional **[username/password databases](https://docs.auth0.com/mysql-connection-tutorial)**.
190+
* Add support for **[linking different user accounts](https://docs.auth0.com/link-accounts)** with the same user.
191+
* Support for generating signed [Json Web Tokens](https://docs.auth0.com/jwt) to call your APIs and **flow the user identity** securely.
192+
* Analytics of how, when and where users are logging in.
193+
* Pull data from other sources and add it to the user profile, through [JavaScript rules](https://docs.auth0.com/rules).
194+
195+
## Create a free account in Auth0
196+
197+
1. Go to [Auth0](https://auth0.com) and click Sign Up.
198+
2. Use Google, GitHub or Microsoft Account to login.
199+
200+
## Issue Reporting
201+
202+
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.
203+
204+
## Author
205+
206+
[Auth0](auth0.com)
207+
208+
## License
209+
210+
This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.

0 commit comments

Comments
 (0)