From 3f82e3fa3677c6b12bc268297296d6e6a51aafd4 Mon Sep 17 00:00:00 2001 From: Aliaksandr Valialkin Date: Tue, 6 Dec 2022 21:02:50 -0800 Subject: [PATCH] docs: follow-up after e1bf2a85d0559d112908ce81597f3261d3a085c0 - Document the change at docs/CHANGELOG.md - Run `make docs-sync` for copying app/vmgateway/README.md to docs/vmgateway.md in order to propagate docs' changes to https://docs.victoriametrics.com/vmgateway.html --- app/vmgateway/README.md | 43 ++++++++++++++++++++++++++++++++++++++++- docs/CHANGELOG.md | 1 + docs/vmgateway.md | 43 ++++++++++++++++++++++++++++++++++++++++- 3 files changed, 85 insertions(+), 2 deletions(-) diff --git a/app/vmgateway/README.md b/app/vmgateway/README.md index ce0d8c48c..291402adc 100644 --- a/app/vmgateway/README.md +++ b/app/vmgateway/README.md @@ -171,6 +171,41 @@ curl 'http://localhost:8431/api/v1/labels' -H 'Authorization: Bearer eyJhbGciOiJ # check rate limit ``` +## JWT signature verification + +`vmgateway` supports JWT signature verification. + +Supported algorithms are `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `ES512`, `PS256`, `PS384`, `PS512`. +Tokens with unsupported algorithms will be rejected. + +In order to enable JWT signature verification, you need to specify keys for signature verification. +The following flags are used to specify keys: +- `-auth.publicKeyFiles` - allows to pass file path to file with public key. +- `-auth.publicKeys` - allows to pass public key directly. + +Note that both flags support passing multiple keys and also can be used together. + +Example usage: +```console +./bin/vmgateway -eula \ + -enable.auth \ + -write.url=http://localhost:8480 \ + -read.url=http://localhost:8481 \ + -auth.publicKeyFiles=public_key.pem \ + -auth.publicKeyFiles=public_key2.pem \ + -auth.publicKeys=`-----BEGIN PUBLIC KEY----- +MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu1SU1LfVLPHCozMxH2Mo +4lgOEePzNm0tRgeLezV6ffAt0gunVTLw7onLRnrq0/IzW7yWR7QkrmBL7jTKEn5u ++qKhbwKfBstIs+bMY2Zkp18gnTxKLxoS2tFczGkPLPgizskuemMghRniWaoLcyeh +kd3qqGElvW/VDL5AaWTg0nLVkjRo9z+40RQzuVaE8AkAFmxZzow3x+VJYKdjykkJ +0iT9wCS0DRTXu269V264Vf/3jvredZiKRkgwlL9xNAwxXFg0x/XFw005UWVRIkdg +cKWTjpBP2dPwVZ4WWC+9aGVd+Gyn1o0CLelf4rEjGoXbAAEgAqeGUxrcIlbjXfbc +mwIDAQAB +-----END PUBLIC KEY----- +` +``` +This command will result in 3 keys loaded: 2 keys from files and 1 from command line. + ## Configuration The shortlist of configuration flags include the following: @@ -178,6 +213,12 @@ The shortlist of configuration flags include the following: ```console -auth.httpHeader string HTTP header name to look for JWT authorization token (default "Authorization") + -auth.publicKeyFiles array + Path file with public key to verify JWT token signature + Supports an array of values separated by comma or specified via multiple flags. + -auth.publicKeys array + Public keys to verify JWT token signature + Supports an array of values separated by comma or specified via multiple flags. -clusterMode enable this for the cluster version -datasource.appendTypePrefix @@ -336,7 +377,7 @@ The shortlist of configuration flags include the following: ## Limitations * Access Control: - * `jwt` token must be validated by external system, currently `vmgateway` can't validate the signature. + * `jwt` token signature verification for `HMAC` algorithms is not supported. * RateLimiting: * limits applied based on queries to `datasource.url` * only cluster version can be rate-limited. diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index bdea5234d..3387d86d9 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -56,6 +56,7 @@ The following tip changes can be tested by building VictoriaMetrics components f * FEATURE: [vmui](https://docs.victoriametrics.com/#vmui): allow changing timezones for the requested data. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/3075). * FEATURE: [vmui](https://docs.victoriametrics.com/#vmui): provide fast path for hiding results for all the queries except the given one by clicking `eye` icon with `ctrl` key pressed. See [this feature request](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/3446). * FEATURE: [MetricsQL](https://docs.victoriametrics.com/MetricsQL.html): add `range_trim_spikes(phi, q)` function for trimming `phi` percent of the largest spikes per each time series returned by `q`. See [these docs](https://docs.victoriametrics.com/MetricsQL.html#range_trim_spikes). +* FEATURE: [vmgateway](https://docs.victoriametrics.com/vmgateway.html): add support for JWT token signature verification. See [these docs](https://docs.victoriametrics.com/vmgateway.html#jwt-signature-verification) for details. * BUGFIX: [vmalert](https://docs.victoriametrics.com/vmalert.html): properly pass HTTP headers during the alert state restore procedure. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/3418). * BUGFIX: [vmalert](https://docs.victoriametrics.com/vmalert.html): properly specify rule evaluation step during the [replay mode](https://docs.victoriametrics.com/vmalert.html#rules-backfilling). The `step` value was previously overriden by `-datasource.queryStep` command-line flag. diff --git a/docs/vmgateway.md b/docs/vmgateway.md index 03b876488..c32fdec5f 100644 --- a/docs/vmgateway.md +++ b/docs/vmgateway.md @@ -175,6 +175,41 @@ curl 'http://localhost:8431/api/v1/labels' -H 'Authorization: Bearer eyJhbGciOiJ # check rate limit ``` +## JWT signature verification + +`vmgateway` supports JWT signature verification. + +Supported algorithms are `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `ES512`, `PS256`, `PS384`, `PS512`. +Tokens with unsupported algorithms will be rejected. + +In order to enable JWT signature verification, you need to specify keys for signature verification. +The following flags are used to specify keys: +- `-auth.publicKeyFiles` - allows to pass file path to file with public key. +- `-auth.publicKeys` - allows to pass public key directly. + +Note that both flags support passing multiple keys and also can be used together. + +Example usage: +```console +./bin/vmgateway -eula \ + -enable.auth \ + -write.url=http://localhost:8480 \ + -read.url=http://localhost:8481 \ + -auth.publicKeyFiles=public_key.pem \ + -auth.publicKeyFiles=public_key2.pem \ + -auth.publicKeys=`-----BEGIN PUBLIC KEY----- +MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu1SU1LfVLPHCozMxH2Mo +4lgOEePzNm0tRgeLezV6ffAt0gunVTLw7onLRnrq0/IzW7yWR7QkrmBL7jTKEn5u ++qKhbwKfBstIs+bMY2Zkp18gnTxKLxoS2tFczGkPLPgizskuemMghRniWaoLcyeh +kd3qqGElvW/VDL5AaWTg0nLVkjRo9z+40RQzuVaE8AkAFmxZzow3x+VJYKdjykkJ +0iT9wCS0DRTXu269V264Vf/3jvredZiKRkgwlL9xNAwxXFg0x/XFw005UWVRIkdg +cKWTjpBP2dPwVZ4WWC+9aGVd+Gyn1o0CLelf4rEjGoXbAAEgAqeGUxrcIlbjXfbc +mwIDAQAB +-----END PUBLIC KEY----- +` +``` +This command will result in 3 keys loaded: 2 keys from files and 1 from command line. + ## Configuration The shortlist of configuration flags include the following: @@ -182,6 +217,12 @@ The shortlist of configuration flags include the following: ```console -auth.httpHeader string HTTP header name to look for JWT authorization token (default "Authorization") + -auth.publicKeyFiles array + Path file with public key to verify JWT token signature + Supports an array of values separated by comma or specified via multiple flags. + -auth.publicKeys array + Public keys to verify JWT token signature + Supports an array of values separated by comma or specified via multiple flags. -clusterMode enable this for the cluster version -datasource.appendTypePrefix @@ -340,7 +381,7 @@ The shortlist of configuration flags include the following: ## Limitations * Access Control: - * `jwt` token must be validated by external system, currently `vmgateway` can't validate the signature. + * `jwt` token signature verification for `HMAC` algorithms is not supported. * RateLimiting: * limits applied based on queries to `datasource.url` * only cluster version can be rate-limited.