dart_jwt 0.6.0

  • README.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 81

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

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or packages 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.
More details: scoring.

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

  • tool failures on Feb 16, 2018
  • Dart: 2.0.0-dev.20.0
  • pana: 0.10.1

Scores

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

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:dart_jwt/dart_jwt.dart.

Suggestions

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

  • 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 issues reported by dartanalyzer.

    dartanalyzer reported 2 error(s) and 0 warning(s).

  • Package is pre-v1 release.

    While there is nothing inherently wrong with versions of 0.*.*, it usually means that the author is still experimenting with the general direction API.

  • Maintain an example.

    Create a short demo in the example/ directory to show how to use this package. Common file name patterns include: main.dart, example.dart or you could also use dart_jwt.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.16.0 <2.0.0
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.5
convert 2.0.1
fixnum 0.9.1+2 0.10.7
typed_data 1.1.5
Dev dependencies
asn1lib >=0.4.1 <0.5.0
test ^0.12.0