dart_jwt 0.6.0

  • README.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 71

JSON Web Token (JWT) for Dart

Introduction

Provides an implementation of JSON Web Token standard.

Using

Basic Usage

####Decoding####

To decode a JWT string

JsonWebToken jwt = new JsonWebToken.decode(jwtStr);

Validating

To validate the decoded jwt

Set<ConstraintViolation> violations = jwt.validate(new JwtClaimSetValidationContext());

If the jwt is valid this will return an empty set. Otherwise the set will contain all the things that were invalid.

This validates the signature and the claim set.

Note you can also validate as you decode

JsonWebToken jwt = new JsonWebToken.decode(jwtStr, validationContext: new JwtClaimSetValidationContext());

This will throw a ConstraintViolations object if the validation fails.

Claim Set The jwt object contains the set of claims being made. You can access them like so

JwtClaimSet claimSet = jwt.claimSet;
print('${claimSet.issuer}');

JwtClaimSet contains all the standard Jwt claims and validation also covers things like checking the expiry etc.

####Encoding#### Claim Set

First create a new claim set

final issuedAt = DateTime.now();
final expiry = issuedAt.add(const Duration(minutes: 3));

final claimSet = new JwtClaimSet('the issuer', 'fred user', expiry, issuedAt));

or if you need a more complex building process you can use MutableJwtClaimSet in a builder style

final claimSet = (new MutableJwtClaimSet()
  ..issuer=issuer
  ..subject=subject
  ..expiry=expiry
  ..issuedAt=issuedAt)
  .toImmutable();

Create the Jwt

To create a JWT encoded inside a Json Web Signature (JWS)

final signatureContext = new JwaSignatureContext(sharedSecret);
final jwt = new JsonWebToken.jws(claimSet, signatureContext);

Note: JWE encoded JWT is not yet implemented

Encoding

Encoding is simply a matter of calling the encode method

String jwtString = jwt.encode();

Extending

Custom Claims

The main way to extend the Jwt library is to add custom claims to the claimset. The following is an example of such a case. Basically you need to extend JwtClaimSet, add your fields, the to / from json and validation.

class ProductHostClaimSet extends JwtClaimSet {
  final String queryStringHash;
  
  ProductHostClaimSet(String issuer, String subject, DateTime expiry, DateTime issuedAt,
      this.queryStringHash) 
    : super(issuer, subject, expiry, issuedAt);
  
  ProductHostClaimSet.fromJson(Map json)
      : queryStringHash = json['qsh'],
        super.fromJson(json);

  @override
  Map toJson() {
    return super.toJson()
        ..['qsh']=queryStringHash;
  }
  
  @override
  Set<ConstraintViolation> validate(ProductHostClaimSetValidationContext validationContext) {
    return super.validate(validationContext)
    	..addAll(_validateQsh(validationContext));
  }
  
  Set<ConstraintViolation> _validateQsh(ProductHostClaimSetValidationContext validationContext) {
    final String expectedQsh = validationContext.qshFactory();
    return queryStringHash == expectedQsh ? new Set.identity() 
        : (new Set()..add(new ConstraintViolation(
            "Query String Hash mismatch. Expected '$expectedQsh'. Got '$queryStringHash'")));
  }
  
}

You can then just create the Jwt in the normal manner

final jwt = new JsonWebToken.jws(claimSet, signatureContext);

Of course if you are not a fan of structure you can always add a single field which is a map containing all the extra claims.

Limitations

Currently this supports enough of the JWT spec that was needed for a project. Specifically it only implements:

  • JWS (no JWE support).
  • HS256 for the JWS signature.

Whilst it is interoperating with a Java based implemention, a rigorous review of conformance to the spec has not been undertaken. Please file issues or PR's if you spot any issues with conformance or find bugs in general or need new features.

PR's with good tests will be looked apon favourably ;-)

Issues

  • Validation needs work. The intention is to piggy back off a constraint validation library (similar to Java Bean Validation) but I haven't written that yet.

0.6.0

  • JwtInJws class made public.
  • Made header available in JsonWebToken.
  • JwsType support for arbitrary values for 'typ' in headers.

0.5.2

  • increase upper bound on crypto

0.5.1

  • increase upper bound on crypto

0.5.0

  • use new urlSafe base64 codec in core dart:convert package
  • Breaking change: Now requires SDK >=1.16.0-dev.5.4

0.4.6

  • updated crypto dependency with required code changes

0.4.5

  • Fails parsing JWT headers without optional "typ" header parameter (2)

0.4.4

  • restored optionality of typ

0.4.2

  • changed to test package

0.4.1

  • widen dependency ranges

0.4.0

  • Abstracted out a base JwtClaimSet. Old JwtClaimSet is now renamed OpenIdJwtClaimSet (breaking)
  • Removed MutableJwtClaimSet (breaking)
  • Added MapJwtClaimSet

0.3.0

  • Audience is now a List (breaking)
  • MutableJwtClaimSet now deprecated

0.2.0

  • Improvements for RSA. Thanks to Jonas Kello for the contribution

0.1.3

  • Add RSA signatures. Thanks to Tais Plougmann Hansen for the contribution

0.1.2

  • make typ header optional and default to JWT

0.1.1

  • Add audience claim

0.1.0+2

  • Bug fix. Had dependency on sdk 1.3 without realising it. Changed sdk version in pubspec.yaml

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  dart_jwt: "^0.6.0"

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:dart_jwt/dart_jwt.dart';
        
Version Uploaded Documentation Archive
0.6.0 Oct 29, 2016 Go to the documentation of dart_jwt 0.6.0 Download dart_jwt 0.6.0 archive
0.5.2 Oct 21, 2016 Go to the documentation of dart_jwt 0.5.2 Download dart_jwt 0.5.2 archive
0.5.1 Apr 21, 2016 Go to the documentation of dart_jwt 0.5.1 Download dart_jwt 0.5.1 archive
0.5.0 Apr 21, 2016 Go to the documentation of dart_jwt 0.5.0 Download dart_jwt 0.5.0 archive
0.4.6 Apr 10, 2016 Go to the documentation of dart_jwt 0.4.6 Download dart_jwt 0.4.6 archive
0.4.5 Jan 6, 2016 Go to the documentation of dart_jwt 0.4.5 Download dart_jwt 0.4.5 archive
0.4.4 Aug 18, 2015 Go to the documentation of dart_jwt 0.4.4 Download dart_jwt 0.4.4 archive
0.4.3 Aug 12, 2015 Go to the documentation of dart_jwt 0.4.3 Download dart_jwt 0.4.3 archive
0.4.2 Jul 14, 2015 Go to the documentation of dart_jwt 0.4.2 Download dart_jwt 0.4.2 archive
0.4.1 Jun 2, 2015 Go to the documentation of dart_jwt 0.4.1 Download dart_jwt 0.4.1 archive

All 18 versions...

Analysis

This feature is new.
We welcome feedback.

We analyzed this package, and provided a score, details, and suggestions below.

  • tool failures on Dec 6, 2017
  • Dart: 2.0.0-dev.8.0
  • pana: 0.7.3+1

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
81
Health:
Code health derived from static analysis. [more]
64
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
57
Overall score:
Weighted score of the above. [more]
71

Platforms

Detected platforms:

Error(s) prevent platform classification.

Suggestions

  • Fix lib/src/codec.dart.

    Strong-mode analysis of lib/src/codec.dart failed with the following error:

    line: 21 col: 11
    The argument type '(Map<dynamic, dynamic>, {validationContext: JwsValidationContext}) → dynamic' can't be assigned to the parameter type '(Map<dynamic, dynamic>) → JwtClaimSet'.

  • Fix lib/src/jwt.dart.

    Strong-mode analysis of lib/src/jwt.dart failed with the following error:

    line: 26 col: 14
    The return type 'JwtInJws<JwtClaimSet>' isn't a 'JsonWebToken<H, T>', as defined by the method 'decode'.

Dependencies

Package Constraint Resolved Available
Direct dependencies
cipher >=0.7.1 <0.8.0 0.7.1
crypto >=0.9.2+1 <3.0.0 2.0.2+1
logging >=0.9.1+1 <0.12.0 0.11.3+1
Transitive dependencies
bignum 0.0.7 0.1.0
charcode 1.1.1
collection 1.14.3
convert 2.0.1
fixnum 0.9.1+2 0.10.6
typed_data 1.1.5
Dev dependencies
asn1lib >=0.4.1 <0.5.0
test ^0.12.0