jaguar_jwt 2.1.6

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • 93

Build Status

jaguar_jwt #

JWT utilities for Dart and Jaguar.dart

This library can be used to generate and process JSON Web Tokens (JWT). For more information about JSON Web Tokens, see RFC 7519.

Currently, only the HMAC SHA-256 algorithm is supported to generate/process a JSON Web Signature (JWS).

Usage #

Issuing a JWT #

  final key = 's3cr3t';
  final claimSet = new JwtClaim(
      subject: 'kleak',
      issuer: 'teja',
      audience: <String>['audience1.example.com', 'audience2.example.com'],
      otherClaims: <String,dynamic>{
        'typ': 'authnresponse',
        'pld': {'k': 'v'}},
      maxAge: const Duration(minutes: 5));

  String token = issueJwtHS256(claimSet, key);
  print(token);

Processing a JWT #

To process a JWT:

  1. Verify the signature and extract the claim set.
  2. Validate the claim set.
  3. Extract claims from the claim set.
  try {
    final JwtClaim decClaimSet = verifyJwtHS256Signature(token, key);
    // print(decClaimSet);

    decClaimSet.validate(issuer: 'teja', audience: 'audience1.example.com');

    if (claimSet.jwtId != null) {
       print(claimSet.jwtId);
    }
    if (claimSet.containsKey('typ')) {
      final v = claimSet['typ'];
      if (v is String) {
         print(v);
      } else {
        ...
      }
    }

    ...
  } on JwtException {
    ...
  }

Configuration #

JwtClaimSet #

JwtClaimSet is the model to holds JWT claim set information.

These are the registered claims:

  1. issuer
    Authority issuing the token. This will be used during authorization to verify that expected issuer has issued the token. Fills the iss field of the JWT.
  2. subject
    Subject of the token. Usually stores the user ID of the user to which the token is issued. Fills the sub field of the JWT.
  3. audience
    List of audience that accept this token. This will be used during authorization to verify that JWT has expected audience for the service. Fills aud field in JWT.
  4. expiry
    Time when the token becomes no longer acceptable for process. Fills exp field in JWT.
  5. notBefore
    Time when the token becomes acceptable for processing. Fills the nbf field in the JWT.
  6. issuedAt
    Time when the token was issued. Fills the iat field in the JWT.
  7. jwtId
    Unique identifier across services that identifies the token. Fills jti field in JWT.

Additional claims may also be included in the JWT.

Changelog #

2.1.6 #

  • Added support for optional Not Before (nbf) time claims.
  • Fixed validation to reject token when current time equals the Expiry time.
  • Added more validation unit tests.
  • Fixed generation of JWT to use correct Base64url Encoding.
  • Added general support for non-registered claims.
  • Tidy up for static analysis and Dart linter.
  • Implemented toString method for JwtClaim.
  • Allow for customized checking of the JWT header.
  • Fixed use of _splayify/_spaly in toJson and changed dynamic to Object.
  • Improved format of output produced by JwtClaim.toString().

2.1.2 #

  • Fixed when typ is not present

2.1.1 #

  • Dart 2 compatibility

example/example.dart

import 'dart:math';

import 'package:jaguar_jwt/jaguar_jwt.dart';

const String sharedSecret = 's3cr3t';

void main() {
  final jwt = senderCreatesJwt();
  receiverProcessesJwt(jwt);
}

String senderCreatesJwt() {
  // Create a claim set

  final claimSet = new JwtClaim(
      issuer: 'teja',
      subject: 'kleak',
      audience: <String>['client1.example.com', 'client2.example.com'],
      jwtId: _randomString(32),
      otherClaims: <String, dynamic>{
        'typ': 'authnresponse',
        'pld': {'k': 'v'}
      },
      maxAge: const Duration(minutes: 5));

  // Generate a JWT from the claim set

  final token = issueJwtHS256(claimSet, sharedSecret);

  print('JWT: "$token"\n');

  return token;
}

void receiverProcessesJwt(String token) {
  try {
    // Verify the signature in the JWT and extract its claim set
    final decClaimSet = verifyJwtHS256Signature(token, sharedSecret);
    print('JwtClaim: $decClaimSet\n');

    // Validate the claim set

    decClaimSet.validate(issuer: 'teja', audience: 'client2.example.com');

    // Use values from claim set

    if (decClaimSet.subject != null) {
      print('JWT ID: "${decClaimSet.jwtId}"');
    }
    if (decClaimSet.jwtId != null) {
      print('Subject: "${decClaimSet.subject}"');
    }
    if (decClaimSet.issuedAt != null) {
      print('Issued At: ${decClaimSet.issuedAt}');
    }
    if (decClaimSet.containsKey('typ')) {
      final dynamic v = decClaimSet['typ'];
      if (v is String) {
        print('typ: "$v"');
      } else {
        print('Error: unexpected type for "typ" claim');
      }
    }
  } on JwtException catch (e) {
    print('Error: bad JWT: $e');
  }
}

String _randomString(int length) {
  const chars =
      '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
  final rnd = new Random(new DateTime.now().millisecondsSinceEpoch);
  final buf = new StringBuffer();

  for (var x = 0; x < length; x++) {
    buf.write(chars[rnd.nextInt(chars.length)]);
  }
  return buf.toString();
}

Use this package as a library

1. Depend on it

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


dependencies:
  jaguar_jwt: ^2.1.6

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 flutter packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:jaguar_jwt/jaguar_jwt.dart';
  
Version Uploaded Documentation Archive
2.1.6 Jan 21, 2019 Go to the documentation of jaguar_jwt 2.1.6 Download jaguar_jwt 2.1.6 archive
2.1.5 Aug 24, 2018 Go to the documentation of jaguar_jwt 2.1.5 Download jaguar_jwt 2.1.5 archive
2.1.4 Aug 7, 2018 Go to the documentation of jaguar_jwt 2.1.4 Download jaguar_jwt 2.1.4 archive
2.1.2 Jul 31, 2018 Go to the documentation of jaguar_jwt 2.1.2 Download jaguar_jwt 2.1.2 archive
2.1.1 Jul 11, 2018 Go to the documentation of jaguar_jwt 2.1.1 Download jaguar_jwt 2.1.1 archive
1.1.5 Feb 2, 2018 Go to the documentation of jaguar_jwt 1.1.5 Download jaguar_jwt 1.1.5 archive
0.3.9 Feb 2, 2018 Go to the documentation of jaguar_jwt 0.3.9 Download jaguar_jwt 0.3.9 archive
0.3.8 Feb 2, 2018 Go to the documentation of jaguar_jwt 0.3.8 Download jaguar_jwt 0.3.8 archive
0.3.7 Feb 2, 2018 Go to the documentation of jaguar_jwt 0.3.7 Download jaguar_jwt 0.3.7 archive
0.3.6 Feb 2, 2018 Go to the documentation of jaguar_jwt 0.3.6 Download jaguar_jwt 0.3.6 archive

All 19 versions...

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

We analyzed this package on Apr 25, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.2.0
  • pana: 0.12.14

Platforms

Detected platforms: Flutter, web, other

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

Health suggestions

Fix lib/src/claim.dart. (-0.50 points)

Analysis of lib/src/claim.dart reported 1 hint:

line 76 col 20: Use = to separate a named parameter from its default value.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev.65 <3.0.0
auth_header ^2.1.1 2.1.2
crypto ^2.0.5 2.0.6
Transitive dependencies
charcode 1.1.2
collection 1.14.11
convert 2.1.1
typed_data 1.1.6
Dev dependencies
test ^1.3.0