# 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`
```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`
```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`
```json
{
  "signer": {
    "type": "rsa",
    "algorithm": "rs256",
    "key": "yourkeyhere"
  }
}
```