Skip to content

Commit

Permalink
documentation updated
Browse files Browse the repository at this point in the history
  • Loading branch information
dadrus committed Jun 29, 2023
1 parent 38114b1 commit 7362123
Show file tree
Hide file tree
Showing 4 changed files with 17 additions and 18 deletions.
4 changes: 2 additions & 2 deletions docs/content/docs/configuration/reference/reference.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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: |
Expand Down
4 changes: 0 additions & 4 deletions docs/content/docs/configuration/reference/types.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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)
+
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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
----
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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)
+
Expand All @@ -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
====
Expand Down

0 comments on commit 7362123

Please sign in to comment.