An implementation of JSON Web Tokens developed against draft-ietf-oauth-json-web-token-08.

compile 'com.auth0:java-jwt:3.0.+'

String token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJpc3MiOiJhdXRoMCJ9.AbIJTDMFc7yUa5MhvcP03nJPyCPzZtQcGEp-zWfOkEE";
try {
    JWT jwt = JWT.decode(token);
} catch (JWTDecodeException exception){
    //Invalid token
}

If the token has an invalid syntax or the header or payload are not JSONs, a JWTDecodeException will raise.

The library implements JWT Verification using the following algorithms:

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.

• Example using HS256

String token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJpc3MiOiJhdXRoMCJ9.AbIJTDMFc7yUa5MhvcP03nJPyCPzZtQcGEp-zWfOkEE";
try {
    JWTVerifier verifier = JWT.require(Algorithm.HMAC256("secret"))
        .withIssuer("auth0")
        .build(); //Reusable verifier instance
    JWT jwt = verifier.verify(token);
} catch (JWTDecodeException exception){
    //Invalid token
} catch (JWTVerificationException exception){
    //Invalid signature/claims
}

• Example using RS256

String token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJpc3MiOiJhdXRoMCJ9.AbIJTDMFc7yUa5MhvcP03nJPyCPzZtQcGEp-zWfOkEE";
PublicKey key = //Get the key instance
try {
    JWTVerifier verifier = JWT.require(Algorithm.RSA256(key))
        .withIssuer("auth0")
        .build(); //Reusable verifier instance
    JWT jwt = verifier.verify(token);
} catch (JWTDecodeException exception){
    //Invalid token
} catch (JWTVerificationException exception){
    //Invalid signature/claims
}

If the token has an invalid syntax or the header or payload are not JSONs, a JWTDecodeException will raise. If the token has an invalid signature or the Claim requirement is not met, a JWTVerificationException will raise.

The JWT token may include DateNumber fields that can be used to validate that:

• The token was issued in a past date "iat" < TODAY
• The token hasn't expired yet "exp" > TODAY and
• The token can already be used. "nbf" > TODAY

When verifying a token the time validation occurs automatically, resulting in a JWTVerificationException being throw when the values are invalid. If any of the previous fields are missing they won't be considered in this validation.

To specify a delta window or leeway in which the Token should still be considered valid, use the acceptTimeDelta() method in the JWTVerifier builder and pass a positive milliseconds value. This applies to every item listed above.

JWTVerifier verifier = JWT.require(Algorithm.RSA256(key))
    .acceptTimeDelta(100) //nbf, iat and exp
    .build();

You can also specify a custom value for a given Date claim and override the default one for only that claim.

JWTVerifier verifier = JWT.require(Algorithm.RSA256(key))
    .acceptTimeDelta(100)   //nbf and iat
    .acceptExpiresAt(500)   //exp
    .build();

Returns the Issuer value or null if it's not defined.

String issuer = jwt.getIssuer();

Returns the Subject value or null if it's not defined.

String subject = jwt.getSubject();

Returns the Audience value in or null if it's not defined.

String[] audience = jwt.getAudience();

Returns the Expiration Time value or null if it's not defined.

Date expiresAt = jwt.getExpiresAt();

Returns the Not Before value or null if it's not defined.

Date notBefore = jwt.getNotBefore();

Returns the Issued At value or null if it's not defined.

Date issuedAt = jwt.getIssuedAt();

Returns the JWT ID value or null if it's not defined.

String id = jwt.getId();

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.

Claim claim = jwt.getClaim("isAdmin");

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:

• asBoolean(): Returns the Boolean value or null if it can't be converted.
• asInt(): Returns the Integer value or null if it can't be converted.
• asDouble(): Returns the Double value or null if it can't be converted.
• asString(): Returns the String value or null if it can't be converted.
• asDate(): Returns the Date value or null if it can't be converted. Note that the JWT Standard specified that all the NumericDate values must be in seconds.

To obtain a Claim as a Collection you'll need to provide the Class Type of the contents to convert from.

• 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.
• 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.

If the values inside the JSON Array can't be converted to the given Class Type, a JWTDecodeException will raise.

Auth0 helps you to:

• Add authentication with multiple authentication sources, 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.
• Add authentication through more traditional username/password databases.
• Add support for linking different user accounts with the same user.
• Support for generating signed Json Web Tokens to call your APIs and flow the user identity securely.
• Analytics of how, when and where users are logging in.
• Pull data from other sources and add it to the user profile, through JavaScript rules.

1. Go to Auth0 and click Sign Up.
2. Use Google, GitHub or Microsoft Account to login.

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 details the procedure for disclosing security issues.

Auth0

This project is licensed under the MIT license. See the LICENSE file for more info.