mirror of
https://git.haproxy.org/git/haproxy.git/
synced 2025-09-20 13:21:29 +02:00
DOC: configuration: rework the jwt_verify keyword documentation
Split the documentation in multiple sections: - Explanation about what it does and how - <alg> parameter with array of parameters - <key> parameter with details about certificates and public keys - Return value Others changes: - certificates does not need to be known during configuration parsing - differences between public key and certificate
This commit is contained in:
William Lallemand
parent
36d28bfca3
commit
ce57f11991
@ -20591,52 +20591,78 @@ jwt_payload_query([<json_path>[,<output_type>]])
|
||||
compiled with USE_OPENSSL.
|
||||
|
||||
jwt_verify(<alg>,<key>)
|
||||
|
||||
Performs a signature verification for the JSON Web Token (JWT) given in input
|
||||
by using the <alg> algorithm and the <key> parameter, which should either
|
||||
hold a secret, a path to a public key or a path to a public certificate. When
|
||||
using a public key, it should either be in the PKCS#1 format (for RSA keys,
|
||||
starting with BEGIN RSA PUBLIC KEY) or SPKI format (Subject Public Key Info,
|
||||
starting with BEGIN PUBLIC KEY). Certificates should be a regular PEM
|
||||
certificate (starting with BEGIN CERTIFICATE). If a full-on certificate is
|
||||
used, it can either be used directly in the converter or passed via a
|
||||
variable if it was already known by haproxy (previously loaded in a crt-store
|
||||
for instance).
|
||||
Returns 1 in case of verification success, 0 in case of verification failure
|
||||
and a strictly negative value for any other error. Because of all those
|
||||
non-null error return values, the result of this converter should never be
|
||||
converted to a boolean. See below for a full list of the possible return
|
||||
values.
|
||||
|
||||
by using the <alg> algorithm and the <key> parameter.
|
||||
For now, only JWS tokens using the Compact Serialization format can be
|
||||
processed (three dot-separated base64-url encoded strings). All the
|
||||
algorithms mentioned in section 3.1 of RFC7518 are managed (HS, ES, RS and PS
|
||||
with the 256, 384 or 512 key sizes, as well as the special "none" case).
|
||||
|
||||
If the used algorithm is of the HMAC family, <key> should be the secret used
|
||||
in the HMAC signature calculation. Otherwise, <key> should be the path to the
|
||||
public key or certificate that can be used to validate the token's signature.
|
||||
All the public keys and certificates that might be used to verify JWTs must
|
||||
be known during init in order to be added into a dedicated cache so that no
|
||||
disk access is required during runtime. For this reason, any used public key
|
||||
must be mentioned explicitly at least once in a jwt_verify call and every
|
||||
certificate used must be loaded by haproxy (in a crt-store or mentioned
|
||||
explicitly in a 'jwt_verify' call). Passing a variable as second parameter is
|
||||
then not advised unless you only use certificates that fill one of those
|
||||
prerequisites.
|
||||
|
||||
processed (three dot-separated base64-url encoded strings).
|
||||
This converter only verifies the signature of the token and does not perform
|
||||
a full JWT validation as specified in section 7.2 of RFC7519. We do not
|
||||
ensure that the header and payload contents are fully valid JSONs once
|
||||
decoded for instance, and no checks are performed regarding their respective
|
||||
contents.
|
||||
|
||||
- <alg> can be either a string or a variable name (See also "set-var") that
|
||||
holds the name of the algorithm used to verify.
|
||||
|
||||
Algorithms mentioned in section 3.1 of RFC7518 are managed:
|
||||
|
||||
+--------------+---------------------------------------------------------+
|
||||
| "alg" Param | Digital Signature or MAC Algorithm |
|
||||
| Value | |
|
||||
+--------------+---------------------------------------------------------+
|
||||
| HS256 | HMAC using SHA-256 |
|
||||
| HS384 | HMAC using SHA-384 |
|
||||
| HS512 | HMAC using SHA-512 |
|
||||
| RS256 | RSASSA-PKCS1-v1_5 using SHA-256 |
|
||||
| RS384 | RSASSA-PKCS1-v1_5 using SHA-384 |
|
||||
| RS512 | RSASSA-PKCS1-v1_5 using SHA-512 |
|
||||
| ES256 | ECDSA using P-256 and SHA-256 |
|
||||
| ES384 | ECDSA using P-384 and SHA-384 |
|
||||
| ES512 | ECDSA using P-521 and SHA-512 |
|
||||
| PS256 | RSASSA-PSS using SHA-256 and MGF1 with SHA-256 |
|
||||
| PS384 | RSASSA-PSS using SHA-384 and MGF1 with SHA-384 |
|
||||
| PS512 | RSASSA-PSS using SHA-512 and MGF1 with SHA-512 |
|
||||
| none | No digital signature or MAC performed |
|
||||
+--------------+---------------------------------------------------------+
|
||||
|
||||
- <key> can be either a string or a variable name (See also "set-var") that
|
||||
holds a secret, a public key path or a certificate path.
|
||||
|
||||
Secrets are only applicable when using HMAC algorithms.
|
||||
|
||||
Public keys must be in either the PKCS#1 format (for RSA keys, starting
|
||||
with BEGIN RSA PUBLIC KEY) or SPKI format (Subject Public Key Info,
|
||||
starting with BEGIN PUBLIC KEY). Public keys must be available during the
|
||||
configuration parsing and cannot be updated or loaded at runtime unlike
|
||||
certificates.
|
||||
|
||||
Certificates must be standard PEM certificates (starting with BEGIN
|
||||
CERTIFICATE). When using a certificate its path can be passed directly to
|
||||
the converter or referenced via a variable. Certificates can be either
|
||||
declared in a crt-store, or dynamically loaded via the stats socket.
|
||||
|
||||
All the public keys and certificates that might be used to verify JWTs must
|
||||
be known during init in order to be added into a dedicated cache so that no
|
||||
disk access is required during runtime.
|
||||
|
||||
It is possible to update certificates dynamically and add new certificates
|
||||
using the stats socket. See also "set ssl cert" and "new ssl cert" in the
|
||||
management guide.
|
||||
|
||||
Returns 1 in case of verification success, 0 in case of verification failure
|
||||
and a strictly negative value for any other error. Because of all those
|
||||
non-null error return values, the result of this converter should never be
|
||||
converted to a boolean. See below for a full list of the possible return
|
||||
values.
|
||||
|
||||
The possible return values are the following :
|
||||
|
||||
+----+----------------------------------------------------------------------+
|
||||
| ID | message |
|
||||
+----+----------------------------------------------------------------------+
|
||||
| 0 | "Verification failure" |
|
||||
| 1 | "Verification success" |
|
||||
| 0 | "Verification failure" |
|
||||
| -1 | "Unknown algorithm (not mentioned in RFC7518)" |
|
||||
| -2 | "Unmanaged algorithm" |
|
||||
| -3 | "Invalid token" |
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user