From 73621233345b768eb3f085e97596cbbf2b4a705e Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Thu, 29 Jun 2023 09:31:15 +0200 Subject: [PATCH] documentation updated --- .../configuration/reference/reference.adoc | 4 ++-- .../docs/configuration/reference/types.adoc | 4 ---- .../pipeline_mechanisms/authorizers.adoc | 19 ++++++++++--------- .../pipeline_mechanisms/contextualizers.adoc | 8 +++++--- 4 files changed, 17 insertions(+), 18 deletions(-) diff --git a/docs/content/docs/configuration/reference/reference.adoc b/docs/content/docs/configuration/reference/reference.adoc index 44fee2ad6..43aa9ce71 100644 --- a/docs/content/docs/configuration/reference/reference.adoc +++ b/docs/content/docs/configuration/reference/reference.adoc @@ -232,14 +232,14 @@ rules: method: POST headers: foo-bar: "{{ .Subject.ID }}" - values: - some-key: some-value auth: type: api_key config: in: header name: X-API-Key value: super duper secret + values: + some-key: some-value payload: "https://bla.bar" expressions: - expression: | diff --git a/docs/content/docs/configuration/reference/types.adoc b/docs/content/docs/configuration/reference/types.adoc index 4e6db3f4e..0d1082a1c 100644 --- a/docs/content/docs/configuration/reference/types.adoc +++ b/docs/content/docs/configuration/reference/types.adoc @@ -528,10 +528,6 @@ Whether HTTP caching according to https://www.rfc-editor.org/rfc/rfc7234[RFC 723 + NOTE: If the endpoint referenced by the URL does not provide any explicit expiration time, no heuristic freshness lifetime is calculated. Heimdall treats such responses as not cacheable. -* *`values`* _map of strings_ (optional) -+ -A key value map, which is made accessible to the template rendering engine as link:{{< relref "../rules/pipeline_mechanisms/overview.adoc#_values" >}}[`Values`] object, e.g. to render parts of the URL. - .Endpoint configuration as string ==== [source, text] diff --git a/docs/content/docs/configuration/rules/pipeline_mechanisms/authorizers.adoc b/docs/content/docs/configuration/rules/pipeline_mechanisms/authorizers.adoc index 39f65bf73..3cc119fea 100644 --- a/docs/content/docs/configuration/rules/pipeline_mechanisms/authorizers.adoc +++ b/docs/content/docs/configuration/rules/pipeline_mechanisms/authorizers.adoc @@ -110,11 +110,9 @@ To enable the usage of this authorizer, you have to set the `type` property to ` Configuration using the `config` property is mandatory. Following properties are available: -* *`endpoint`*: _link:{{< relref "/docs/configuration/reference/types.adoc#_endpoint">}}[Endpoint]_ (mandatory, partially overridable) +* *`endpoint`*: _link:{{< relref "/docs/configuration/reference/types.adoc#_endpoint">}}[Endpoint]_ (mandatory, not overridable) + The API endpoint of your authorization system. At least the `url` must be configured. This mechanism allows templating of the url and makes the link:{{< relref "overview.adoc#_subject" >}}[`Subject`] object, as well as the link:{{< relref "overview.adoc#_values" >}}[`Values`] (see also below) objects available to it. By default, this authorizer will use HTTP `POST` to send the rendered payload to this endpoint. You can override this behavior by configuring `method` as well. Depending on the API requirements of your authorization system, you might need to configure further properties, like headers, etc. -+ -The only overridable property on the rule level is the `values` property, which allows rule specific configuration of the URL. * *`payload`*: _string_ (optional, overridable) + @@ -134,6 +132,10 @@ Enables forwarding of any headers from the authorization endpoint response to th + Allows caching of the authorization endpoint responses. Defaults to 0s, which means no caching. The cache key is calculated from the entire configuration of the authorizer instance and the available information about the current subject. +* *`values`* _map of strings_ (optional, overridable) ++ +A key value map, which is made accessible to the template rendering engine as link:{{< relref "overview.adoc#_values" >}}[`Values`] object, e.g. to render parts of the URL. + .Configuration of Remote authorizer to communicate with https://www.openpolicyagent.org/[Open Policy Agent] (OPA) ==== Here the remote authorizer is configured to communicate with OPA. Since OPA expects the query to be formatted as JSON, the corresponding `Content-Type` header is set. Since the responses are JSON objects as well, the `Accept` header is also provided. In addition, this examples uses the `basic_auth` auth type to authenticate against the endpoint. @@ -153,11 +155,11 @@ config: config: user: ${OPA_USER} password: ${OPA_PASSWORD} - values: - namespace: myapi/policy - policy: allow_write payload: | { "input": { "user": {{ quote .Subject.ID }} } } + values: + namespace: myapi/policy + policy: allow_write expressions: - expression: | Payload.result == true @@ -183,9 +185,8 @@ A specific rule could then use this authorizer in the following ways: - # other mechanisms - authorizer: opa config: # overriding with rule specifics - endpoint: - values: - policy: allow_read + values: + policy: allow_read - # other mechanisms ---- diff --git a/docs/content/docs/configuration/rules/pipeline_mechanisms/contextualizers.adoc b/docs/content/docs/configuration/rules/pipeline_mechanisms/contextualizers.adoc index 661709133..d019ff81f 100644 --- a/docs/content/docs/configuration/rules/pipeline_mechanisms/contextualizers.adoc +++ b/docs/content/docs/configuration/rules/pipeline_mechanisms/contextualizers.adoc @@ -23,11 +23,9 @@ To enable the usage of this contextualizer, you have to set the `type` property Configuration using the `config` property is mandatory. Following properties are available: -* *`endpoint`*: _link:{{< relref "/docs/configuration/reference/types.adoc#_endpoint">}}[Endpoint]_ (mandatory, partially overridable) +* *`endpoint`*: _link:{{< relref "/docs/configuration/reference/types.adoc#_endpoint">}}[Endpoint]_ (mandatory, not overridable) + The API of the service providing additional attributes about the authenticated user. At least the `url` must be configured. This mechanism allows templating of the url and makes the link:{{< relref "overview.adoc#_subject" >}}[`Subject`] object, as well as the link:{{< relref "overview.adoc#_values" >}}[`Values`] (see also below) objects available to it. By default, this contextualizer will use HTTP `POST` to send the rendered payload to this endpoint. You can override this behavior by configuring `method` as well. Depending on the API requirements of the system, this contextualizer should communicate to, you might need to configure further properties, like headers, etc. -+ -The only overridable property on the rule level is the `values` property, which allows rule specific configuration of the URL. * *`forward_headers`*: _string array_ (optional, overridable) + @@ -49,6 +47,10 @@ Allows caching of the API responses. Defaults to 10 seconds. The cache key is ca + If set to `true`, allows the pipeline to continue with the execution of the next mechanisms. So the error, if thrown, is ignored. Defaults to `false`, which means the execution of the regular pipeline is stopped and the execution of the error pipeline is started. +* *`values`* _map of strings_ (optional, overridable) ++ +A key value map, which is made accessible to the template rendering engine as link:{{< relref "overview.adoc#_values" >}}[`Values`] object, e.g. to render parts of the URL. + .Contextualizer configuration ====