JWT Tokens Algorithm¶
The JWT (JSON Web Tokens) authentication mechanism supports different algorithms for signing tokens. This section outlines the default algorithm used and the steps required to use an alternative algorithm.
Default Algorithm¶
By default, the service uses the HS256 algorithm for signing JWT tokens. HS256, or HMAC (Hash-based Message Authentication Code) with SHA-256.
Using ES256 Algorithm¶
If you want to use asymmetric key cryptography, you can use the ES256 algorithm. ES256, or ECDSA (Elliptic Curve Digital Signature Algorithm) with SHA-256.
To use the ES256 algorithm, follow these steps:
First, you need to generate a private ECDSA key using the prime256v1 curve. This can be done using command-line tools such as OpenSSL.
Example command:
openssl ecparam -genkey -name prime256v1 -out ec_private.pem
You can also generate a key which is protected by password.
openssl ecparam -genkey -name prime256v1 | openssl ec -aes256 -out ec_private_enc.pem
After generating the private key, encode it in Base64 format. This can be achieved with tools available in most operating systems.
Example command:
base64 -w0 ecdsa_private.pem > ecdsa_private_base64
The encoded private key must be specified in the environment variable
ACCOUNTS_JWT_ECDSA_KEY
. This allows the service to use the key for signing JWT tokens with the ES256 algorithm.Additionally, if your private key is protected with a password, you can specify the password in the environment variable
ACCOUNTS_JWT_ECDSA_KEY_PASSWORD
.
By following these steps, the service will be able to sign JWT tokens using the ES256 algorithm, providing enhanced security through asymmetric cryptography.
Impact of changing the Algorithm Type¶
Switching the signing algorithm from HS256 to ES256 (or vice versa) has a significant impact on token validation. All existing tokens signed with the previous algorithm will become invalid once the change is done. This happens because the mechanism for verifying the token’s signature will expect the structure and cryptographic base of the token to match the newly specified algorithm.