Skip to content

JWT Overview

This guide gives an overview of using the JWT provider package.

Configuration

JWTProvider can be configured in 3 different ways:

  • Custom signers defined in jwt.json
    • Supports (private/public): hmac, rsa, esdca.
  • Legacy custom signer defined in jwt.json.
    • Supports (private/public): hmac, rsa, esdca.
  • Remote JSON Web Key Set (jwks.json) URL
    • Supports (private/public): rsa.

If your Vapor app is acting as an Authentication Provider, you may want to use either the Legacy custom signer setup, or the Custom signers setup, which is great if you want to perform certificates rotation.

The only difference is that with Custom signers the kid value in the JWT header is not ignored, and it must match an associated signer in order to verify the signature.

If your Vapor app is a Resource Provider that delegates Authentication to a 3rd party (auth0, stormpath, etc), you may want to use the Remote JSON Web Key Set setup. In this configuration the JWT token is generated by a 3rd party that provides the public key in JSON Web Key Set format. The Vapor app is only in charge to verify the JWT signature using the key set provided by the 3rd party.

Remote JSON Web Key Set

Config/jwt.json

{
  "jwks-url": "http://my-domain.com/well-known/jwks.json"
}

Custom Signers

This allows to specify an array of signers and is particularly useful for rotating certificates. Custom signers are not backward compatible and must specify an additional kid in the configuration.

  • type: unsigned, hmac, rsa, esdca
  • kid: an unique identifier
  • algorithm:
    • type[hmac]: hs256, hs384, hs512
    • type[rsa]: rs256, rs384, rs512
    • type[esdca]: es256, es384, es512

Config/jwt.json

{
  "signers": {
    "1234": {
      "type": "rsa",
      "algorithm": "rs256",
      "key": "yourkeyhere"
    }
  }
}

Legacy Custom Signer

This is backwards compatible with the previous implementation.

  • type: unsigned, hmac, rsa, esdca
  • algorithm:
    • type[hmac]: hs256, hs384, hs512
    • type[rsa]: rs256, rs384, rs512
    • type[esdca]: es256, es384, es512

Config/jwt.json

{
  "signer": {
    "type": "rsa",
    "algorithm": "rs256",
    "key": "yourkeyhere"
  }
}