---
url: https://maximemrf.github.io/adonisjs-jwt/guide/asymmetric.md
description: >-
  Sign AdonisJS JWT access tokens with RSA or ECDSA keys (RS256, ES256) so other
  services can verify them with the public key.
---

# Asymmetric signing

With asymmetric signing, the guard signs access tokens with a **private key** and verifies them with the matching **public key**. Other services can verify your tokens with the public key alone, without being able to issue tokens.

Supported algorithms: `RS256`, `RS384`, `RS512` (RSA) and `ES256`, `ES384`, `ES512` (ECDSA).

## Generate a key pair

```sh
# RSA
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private.pem
openssl pkey -in private.pem -pubout -out public.pem

# ECDSA (P-256, for ES256)
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out private.pem
openssl pkey -in private.pem -pubout -out public.pem
```

Never commit the private key. Store it in an environment variable or a secret manager.

## Configure the guard

Set `privateKey`, `publicKey` and `algorithm` together:

```ts
import env from '#start/env'

jwtGuard({
  provider: sessionUserProvider({
    model: () => import('#models/user'),
  }),
  privateKey: env.get('JWT_PRIVATE_KEY').replace(/\\n/g, '\n'),
  publicKey: env.get('JWT_PUBLIC_KEY').replace(/\\n/g, '\n'),
  algorithm: 'RS256',
})
```

The `.replace()` restores the line breaks of PEM keys stored on a single line in `.env`. Declare the variables in `start/env.ts`:

```ts
// start/env.ts
JWT_PRIVATE_KEY: Env.schema.string(),
JWT_PUBLIC_KEY: Env.schema.string(),
```

With `Env.schema.secret()`, `env.get()` returns a `Secret`: call `.release()` before `.replace()`, as in `env.get('JWT_PRIVATE_KEY').release().replace(/\\n/g, '\n')`.

The guard checks at startup that the keys are valid, match the algorithm (including the curve of ECDSA keys and RSA keys of at least 2048 bits), and belong to the same key pair. It throws if only some of the three options are set.

Notes:

* `secret` is ignored when the keys are set.
* Asymmetric signing can't be combined with `jwks`.
* Only tokens signed with the configured algorithm are accepted, so a token signed with HMAC using the public key as secret is rejected.

## Verify tokens in another service

Other services verify the tokens with the public key, with any JWT library. For example, with `jsonwebtoken`:

```ts
import jwt from 'jsonwebtoken'

const payload = jwt.verify(token, publicKey, {
  algorithms: ['RS256'],
  issuer: 'my-app',
  audience: 'my-api',
})

// jsonwebtoken checks `exp` only when it is present
if (typeof payload === 'string' || payload.exp === undefined) {
  throw new Error('Token without expiration')
}
```

Always pin `algorithms`, and require `exp`: the guard always sets it, so a token without it was not issued by the guard. With [`jose`](https://github.com/panva/jose), pass `requiredClaims: ['exp']` to `jwtVerify()`. If the other service is an AdonisJS application, you can also expose the public key as a JWKS and use the [JWKS mode](/guide/jwks).
