|
| 1 | + |
| 2 | + |
| 3 | +# Java JWT [v3] |
| 4 | + |
| 5 | +[](https://travis-ci.org/auth0/java-jwt) |
| 6 | +[](https://codecov.io/github/auth0/java-jwt) |
| 7 | +[](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