JSON Web Token (JWT)

An easy to use JSON Web Token implementation in Dart (all algorithms supported).

JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties.

dart_jsonwebtoken allows you to sign, decode and verify JWT.

Examples

Check out the Example File for a full example code of all the different algorithms.

You can also check out the jwt.io website for more information.

Usage

Import

import 'package:dart_jsonwebtoken/dart_jsonwebtoken.dart';

Creating & signing a JWT

// Generate a JSON Web Token
// You can provide the payload as a key-value map or a string
final jwt = JWT(
  // Payload
  {
    'id': 123,
    'server': {
      'id': '3e4fc296',
      'loc': 'euw-2',
    }
  },
  issuer: 'https://github.com/jonasroussel/dart_jsonwebtoken',
);

// Sign it (default with HS256 algorithm)
final token = jwt.sign(SecretKey('secret passphrase'));

print('Signed token: $token\n');

Verifying a JWT

try {
  // Verify a token (SecretKey for HMAC & PublicKey for all the others)
  final jwt = JWT.verify(token, SecretKey('secret passphrase'));

  print('Payload: ${jwt.payload}');
} on JWTExpiredException {
  print('jwt expired');
} on JWTException catch (ex) {
  print(ex.message); // ex: invalid signature
}

Decoding without verification

You can decode a token without checking its signature (e.g. for inspection). Do not use this for authorization—always verify with JWT.verify when trusting the token.

final jwt = JWT.decode(token);

print('Payload: ${jwt.payload}');

Key creation for all algorithms

The raw PEM content below is for learning only. In production, read private and public keys from files and pass their contents (as strings) to the constructors.

// HS256, HS384, HS512
final hmacKey = SecretKey('secret passphrase');


// RS256, RS384, RS512, PS256, PS384, PS512
final rsaPrivKey = RSAPrivateKey('''
-----BEGIN RSA PRIVATE KEY-----
MIIEogIBAAKCAQEAq5QLAv9kYTgelglIhC17KdfUoinkwvQ4F0TZAp7qgmu19dCx
...
-----END RSA PRIVATE KEY-----
''');

// You can also extract the public key from a certificate with RSAPublicKey.cert(...)
final rsaPubKey = RSAPublicKey('''
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAq5QLAv9kYTgelglIhC17
...
-----END PUBLIC KEY-----
'''
);


// ES256, ES256K, ES384, ES512
final ecPrivKey = ECPrivateKey('''
-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgevZzL1gdAFr88hb2
...
-----END PRIVATE KEY-----
''');

// You can also extract the public key from a certificate with ECPublicKey.cert(...)
final ecPubKey = ECPublicKey('''
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEVs/o5+uQbTjL3chynL4wXgUg2R9
...
-----END PUBLIC KEY-----
''');


// EdDSA
final edPrivKey = EdDSAPrivateKey.fromPEM('''-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEICXCjBHvjArjXquUI5jo3x5SHI4ofZA2azwJ39IC/Qct
-----END PRIVATE KEY-----
''');

final edPubKey = EdDSAPublicKey.fromPEM('''-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAEi7MNW0Q9T83UA3Rw+8DbspMgqeuxCqa2wXaWS+tHqY=
-----END PUBLIC KEY-----
''');

Supported Algorithms

JWT Algorithms	Digital Signature or MAC Algorithm
HS256	HMAC using SHA-256 hash algorithm
HS384	HMAC using SHA-384 hash algorithm
HS512	HMAC using SHA-512 hash algorithm
PS256	RSASSA-PSS using SHA-256 hash algorithm
PS384	RSASSA-PSS using SHA-384 hash algorithm
PS512	RSASSA-PSS using SHA-512 hash algorithm
RS256	RSASSA-PKCS1-v1_5 using SHA-256 hash algorithm
RS384	RSASSA-PKCS1-v1_5 using SHA-384 hash algorithm
RS512	RSASSA-PKCS1-v1_5 using SHA-512 hash algorithm
ES256	ECDSA using P-256 curve and SHA-256 hash algorithm
ES256K	ECDSA using secp256k curve and SHA-256 hash algorithm
ES384	ECDSA using P-384 curve and SHA-384 hash algorithm
ES512	ECDSA using P-521 curve and SHA-512 hash algorithm
EdDSA	EdDSA using ed25519 curve and SHA-512 hash algorithm