Configure JSON Web Encryption (JWE)

By default, Auth0 issues access tokens that are formatted as a signed JSON Web Token (JWT), meaning that while they are integrity protected, clients and other intermediaries can still inspect them. This can lead to a loss of information privacy on data intended only to be exposed to a resource server.  

To prevent unauthorized inspection of access tokens, Auth0 supports the use of nested JWT access tokens, where access information is signed in a JWT, which is then encrypted and represented with JSON Web Encryption (JWE). Resource servers are expected to both decrypt these access tokens and verify the signature of the JWT payload while the information is opaque to any other parties.

Before configuring an API to use JWE, you must generate an RSA key pair.

The private key must be kept secret, and you must upload the public key to Auth0 encoded in PEM format as described in the following section. Only the resource server or API server can securely access the private key to decrypt the access token.

Use the Auth0 Management API to configure JWE for a resource server or API server. You must configure JWE for each API, so each API has its own public encryption key.

The following POST request configures a new API to receive encrypted access tokens:

curl -X POST --location "https://{domain}/api/v2/resource-servers" \
    -H "Authorization: Bearer {managementAccessToken}" \
    -H "Content-Type: application/json" \
    --data-raw '{
  "name": "{apiName}",
  "identifier": "{apiIdentifier}",
  "token_encryption": {
    "format": "compact-nested-jwe",
    "encryption_key":
    {
      "name": "{credentialName}",
      "pem": "{pem}",
      "alg": "{alg}",
      "kid": "{kid}"
    }
  }
}'

The following table explains what the different parameters mean:

The response contains the id property which uniquely identifies the resource server. The response also contains a generated thumbprint_sha256 field that can be used to identify the credential. Auth0 will not return key material after initial creation (in this case, your PEM).

There are many ways to generate the thumbprint_sha256. For more information, see the RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens.

To ensure that you generated the correct thumbprint_sha256, you can use the following Node.js code sample to extract the thumbprint:

const fs = require('fs');
const crypto = require('crypto')

const cert = new crypto.X509Certificate(fs.readFileSync('./my_cert.pem'))
const thumbprint = Buffer.from(cert.fingerprint256.replaceAll(':', ''), 'hex').toString('base64url')

console.log(thumbprint)

• JSON Web Encryption