### Example: Install Traefik Gateway Demo with Observability

Source: https://github.com/dadrus/heimdall/blob/main/examples/kubernetes/README.md

This is an example command to set up a cluster with Traefik using the Gateway API and enabling the observability stack.

```bash
> just OBS=true install-traefik-gw-demo
```

--------------------------------

### Install with Separate Value Files

Source: https://github.com/dadrus/heimdall/blob/main/charts/heimdall/README.adoc

This example demonstrates how to install the Helm chart using separate configuration files for chart values and Heimdall configuration.

```bash
helm install -f /path/to/chart-values.yaml -f /path/to/heimdall-config.yaml ...
```

--------------------------------

### Install Demo with Options

Source: https://github.com/dadrus/heimdall/blob/main/examples/kubernetes/README.md

Use this command to install and set up a demo environment. Options include enabling the observability stack (`OBS=true`) and specifying the setup type for different ingress controllers or gateway APIs.

```bash
just <options> install-<setup-type>-demo
```

--------------------------------

### Example CLI Command

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/operations/cli.adoc

An example of using the `validate` command with a configuration file.

```bash
heimdall validate config -c config.yaml
```

--------------------------------

### Start Envoy HTTP Integration

Source: https://github.com/dadrus/heimdall/blob/main/examples/docker-compose/README.md

Use this command to start the environment for testing Heimdall integration with Envoy over HTTP.

```bash
docker compose -f docker-compose.yaml -f docker-compose-envoy-http.yaml up
```

--------------------------------

### Start Docker Compose Environment

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/getting_started/protect_an_app.adoc

This command starts all the services defined in the docker-compose.yaml file. Ensure you are in the directory containing the file.

```bash
docker compose up
```

--------------------------------

### CORS Configuration Example

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/configuration/types.adoc

Example of how to configure CORS options, including allowed origins, methods, credentials, and max age.

```yaml
allowed_origins:
  - example.org
allowed_methods:
  - HEAD
  - PATCH
allow_credentials: true
max_age: 10s
```

--------------------------------

### Kubernetes RuleSet Status Output

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/rules/rule_sets.adoc

Example output from 'kubectl get' command showing the status of deployed RuleSet resources, indicating active and matching instances.

```bash
NAME             ACTIVE IN       AGE
test-rules       2/2             32m
```

--------------------------------

### Example Method Matching (All)

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/rules/regular_rule.adoc

Allows all HTTP methods. This is the default behavior if the `methods` property is not specified.

```yaml
methods:
  - ALL
```

--------------------------------

### Start Traefik Integration with Docker Compose

Source: https://github.com/dadrus/heimdall/blob/main/examples/docker-compose/README.md

Execute this command to start the Heimdall environment integrated with Traefik. This setup routes all requests through Traefik, which acts as an external authorization middleware for Heimdall.

```bash
docker compose -f docker-compose.yaml -f docker-compose-traefik.yaml up
```

--------------------------------

### Kubernetes Rule Set Example

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/rules/rule_sets.adoc

A simple example of a Kubernetes RuleSet custom resource, including apiVersion, kind, metadata, and spec with rule definitions.

```yaml
apiVersion: heimdall.dadrus.github.com/v1beta1
kind: RuleSet
metadata:
  name: "<some name>"
spec:
  authClassName: "<optional auth_class reference (see above)> "
  rules:
    - id: "<identifier of a rule 1>"
      match:
        routes:
          - path: /foo/**
        scheme: https
        hosts:
          - 127.0.0.1:9090
      execute:
        - authenticator: foo
        - authorizer: bar
```

--------------------------------

### Heimdall Service Startup Log

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/guides/authn/dpop_bound_access_tokens.adoc

This is an example log message indicating that the Heimdall service has started successfully. It is used to confirm that Heimdall is operational before proceeding with further steps.

```text
heimdall  | ... level=INFO msg="Started" ...
```

--------------------------------

### Default Rule Configuration Example

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/rules/default_rule.adoc

This example demonstrates a complete default rule configuration, including authentication, authorization, and error handling pipelines. The 'execute' block defines the primary pipeline, while 'on_error' specifies how to handle errors during execution. The 'deny_all_requests_authz' authorizer ensures secure defaults, and the 'authenticate_with_kratos_eh' error handler is conditionally applied.

```yaml
default_rule:
  execute:
    - authenticator: session_cookie_from_kratos_authn
    - authenticator: oauth2_introspect_token_from_keycloak_authn
    - authorizer: deny_all_requests_authz
    - finalizer: create_jwt
  on_error:
    - error_handler: authenticate_with_kratos_eh
      if: |
        type(Error) == authentication_error && Error.Source == "session_cookie_from_kratos_authn"
```

--------------------------------

### Start Proxy Mode Environment with Docker Compose

Source: https://github.com/dadrus/heimdall/blob/main/examples/docker-compose/README.md

Use this command to start the Heimdall environment in standalone proxy mode. This setup does not integrate Heimdall with any other reverse proxy.

```bash
docker compose -f docker-compose.yaml -f docker-compose-proxy.yaml up
```

--------------------------------

### Install Heimdall Helm Chart

Source: https://github.com/dadrus/heimdall/blob/main/charts/heimdall/README.adoc

Install a Heimdall release using a chart reference, specifying namespace and configuration files.

```bash
helm install my-release <chart-reference> \
  -n <namespace-to-install-heimdall-into> \
  -f <path/to/your/values.yaml> \
  -f <path/to/your/heimdall/config.yaml>
```

--------------------------------

### Cosign Verification Output Example

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/operations/security.adoc

This is an example of the JSON output from a successful Cosign verification of a container image signature.

```json
[
  {
    "critical": {
      "identity": {
        "docker-reference": "index.docker.io/dadrus/heimdall"
      },
      "image": {
        "docker-manifest-digest": "sha256:289b1a3eeeceeef08362a6fbcf4b95e726686d17998798e149c30b6974728eaf"
      },
      "type": "cosign container image signature"
    },
    "optional": {
      "1.3.6.1.4.1.57264.1.1": "https://token.actions.githubusercontent.com",
      "1.3.6.1.4.1.57264.1.2": "push",
      "1.3.6.1.4.1.57264.1.3": "04379639dc5f3fbfc260e883ee4938a35076d63e",
      "1.3.6.1.4.1.57264.1.4": "release",
      "1.3.6.1.4.1.57264.1.5": "dadrus/heimdall",
      "1.3.6.1.4.1.57264.1.6": "refs/tags/v0.17.17",
      "Bundle": {
        "SignedEntryTimestamp": "MEUCIFIvxs30zysroG6...tQ3U/2yx8Jqu8H75g6sihIcpg=",
        "Payload": {
          "body": "eyJhcGlWZXJzaW9uIjoi...xTMHRMUW89In19fX0=",
          "integratedTime": 1692727396,
          "logIndex": 32332529,
          "logID": "c0d23d6ad406973f9559...d8ffc5b8445c224f98b9591801d"
        }
      },
      "Issuer": "https://token.actions.githubusercontent.com",
      "Subject": "https://github.com/dadrus/heimdall/.github/workflows/release.yaml@refs/tags/v0.17.17",
      "githubWorkflowName": "release",
      "githubWorkflowRef": "refs/tags/v0.17.17",
      "githubWorkflowRepository": "dadrus/heimdall",
      "githubWorkflowSha": "04379639dc5f3fbfc260e883ee4938a35076d63e",
      "githubWorkflowTrigger": "push"
    }
  }
]
```

--------------------------------

### PEM File Content Example

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/operations/secret_management.adoc

This is an example of a PEM file containing an EC private key with an 'X-Key-ID' header, followed by its associated certificate. This format is used when referencing a key by its ID.

```txt
-----BEGIN EC PRIVATE KEY-----
X-Key-ID: foo

MIGkAgEBBDBRLr783dIM5NHJnDDMRVBiFSF56xqHle5lZk1ZCyyow9wKZGuF4EWK
...
-----END EC PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
```

--------------------------------

### Rule Set with Specificity and Backtracking Examples

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/rules/regular_rule.adoc

Illustrates a rule set demonstrating specificity and backtracking. It includes rules with general path matching (`/files/**`), specific path parameters using regex, and a more specific path (`/files/team3/:name`). This example highlights how the system prioritizes more specific matches and may backtrack to less specific ones if conditions aren't met.

```yaml
- id: rule1
  match:
    routes:
      - path: /files/**
  execute:
    - <pipeline definition>

- id: rule2
  match:
    routes:
      - path: /files/:team/:name
        path_params:
          - name: team
            type: regex
            value: "(team1|team2)"
    methods:
      - GET
  execute:
    - <pipeline definition>

- id: rule3
  match:
    routes:
      - path: /files/:team/:name
        path_params:
          - name: team
            type: regex
            value: "(team1|team2)"
  execute:
    - <pipeline definition>

- id: rule4
  match:
    routes:
      - path: /files/team3/:name
  execute:
    - <pipeline definition>
```

--------------------------------

### Complex Pipeline Example

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/rules/regular_rule.adoc

Demonstrates a complex pipeline configuration with authorization, finalization, and conditional execution of mechanisms.

```yaml
pipeline:
  - contextualizer: my_contextualizer
    id: ctx1
    if: subject.claims.user_id == "user-123"
  - authorizer: my_authorizer
    id: auth1
    config:
      some_setting: true
  - finalizers:
    - my_finalizer
    config:
      another_setting: false
```

--------------------------------

### Start Envoy gRPC Integration

Source: https://github.com/dadrus/heimdall/blob/main/examples/docker-compose/README.md

Use this command to start the environment for testing Heimdall integration with Envoy using gRPC extauthz. This requires Heimdall version v0.7.0-alpha or later.

```bash
docker compose -f docker-compose.yaml -f docker-compose-envoy-grpc.yaml up
```

--------------------------------

### Example of Text Log Output

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/operations/observability.adoc

This is an example of log output when the 'text' format is configured. This format is not recommended for production due to performance implications.

```log
2022-08-03T12:51:48+02:00 INF Opentelemetry tracing initialized.
2022-08-03T12:51:48+02:00 INF Instantiating in memory cache
2022-08-03T12:51:48+02:00 DBG Creating rule set event queue.
2022-08-03T12:51:48+02:00 INF Loading pipeline definitions
2022-08-03T12:51:48+02:00 DBG Loading definitions for authenticators
2022-08-03T12:51:48+02:00 DBG Loading pipeline definition id=anonymous_authenticator type=anonymous
...
2022-08-03T12:51:52+02:00 DBG Decision endpoint called
2022-08-03T12:51:52+02:00 DBG Executing default rule
2022-08-03T12:51:52+02:00 DBG Authenticating using anonymous authenticator
2022-08-03T12:51:52+02:00 DBG Finalizing using JWT finalizer
2022-08-03T12:51:52+02:00 DBG Generating new JWT
2022-08-03T12:51:52+02:00 DBG Finalizing request
```

--------------------------------

### Decision Service Example Request

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/concepts/operating_modes.adoc

This example shows a typical request sent to Heimdall by an API gateway in Decision Mode.

```bash
GET /my-service/api HTTP/1.1
Host: heimdall:4456
X-Forwarded-Host: my-backend-service

Some payload
```

--------------------------------

### Example Method Matching (Specific Exclusions)

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/rules/regular_rule.adoc

Allows all HTTP methods except for specific ones, indicated by prefixing with '!'.

```yaml
methods:
  - ALL
  - "!POST"
  - "!PUT"
```

--------------------------------

### Example Mechanism Catalogue Definition

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/mechanisms/catalogue.adoc

This comprehensive YAML example defines a complete mechanism catalogue, including authenticators, authorizers, contextualizers, finalizers, and error handlers. It showcases various configuration options for each mechanism type.

```yaml
mechanisms:
  authenticators:
  - id: anon_authn
    type: anonymous
  - id: opaque_auth_token_authn
    type: oauth2_introspection
    config:
      introspection_endpoint:
        url: http://hydra:4445/oauth2/introspect
  authorizers:
  - id: deny_all_authz
    type: deny
  - id: local_authz
    type: cel
    config:
      expressions:
        - expression:
            "manager" in Subject.Attributes.groups
          message: user is not in the expected group
  contextualizers:
  - id: group_manager
    type: generic
    config:
      endpoint:
        url: https://group-manager.local/groups
        method: GET
      forward_headers:
        - Authorization
      cache_ttl: 1m
  finalizers:
  - id: jwt_finalizer
    type: jwt
    config:
      signer:
        secret:
          source: key_store
          selector: signer_key
      ttl: 5m
      claims: |
          {
            {{ $user_name := .Subject.Attributes.identity.user_name -}}
            "email": {{ quote .Subject.Attributes.identity.email }},
            "email_verified": {{ .Subject.Attributes.identity.email_verified }},
            {{ if $user_name -}}
            "name": {{ quote $user_name }}
            {{ else -}}
            "name": {{ quote $email }}
            {{ end -}}
          }
  error_handlers:
  - id: default
    type: default
  - id: authenticate_with_kratos
    type: redirect
    config:
      to: https://127.0.0.1:4433/self-service/login/browser?return_to={{ .Request.URL | urlenc }}
  - id: protocol_error
    type: generic
    config:
      code: 400
      headers:
        - Content-Type: application/json
      body: '{"error":"bad request"}'
```

--------------------------------

### Configure File Secret Provider

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/operations/secret_management.adoc

Example configuration for the File provider, specifying the path to the secrets file and enabling file watching.

```yaml
secret_management:
  my_file_source:
    type: file
    config:
      path: /etc/heimdall/secrets.yaml
      watch: true
```

--------------------------------

### OpenFGA Store Creation Response

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/guides/authz/openfga.adoc

This is an example response after successfully creating an OpenFGA store. The 'id' field is crucial for configuring authorization models and rules.

```json
{
  "id":"01HSXG2XSZJMQG99EVXB4QQX8P",
  "name":"FGA Demo Store",
  "created_at":"2024-03-26T13:44:37.439559338Z",
  "updated_at":"2024-03-26T13:44:37.439559338Z"
}
```

--------------------------------

### Body Forward Strategy Output (JSON)

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/configuration/types.adoc

Example of how authentication data might be formatted in the request body when the Content-Type is JSON.

```json
{ "idToken": "<whatever the token value is>" }
```

--------------------------------

### Install Conversion Controller Helm Chart

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/operations/migration.adoc

Use this command to install a new heimdall deployment as a conversion controller in Kubernetes. Configure it to listen for a random `auth_class` to avoid loading RuleSets, focusing solely on conversion. Ensure `crds.updateEnabled` is true and `crds.storageVersion` is set to the old CRD schema. The `--take-ownership` flag is crucial if Helm did not previously manage the CRD.

```bash
helm upgrade --install ruleset-upgrade <chart-reference>  \
    --set crds.updateEnabled=true \
    --set crds.storageVersion=<old-crd-schema> \
    -n <namespace-controller-heimdall-should-be-installed-into> \
    -f <path/to/your/values.yaml> \
    -f <path/to/your/heimdall/config.yaml> \
    --take-ownership
```

--------------------------------

### OpenFGA Authorization Model Creation Response

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/guides/authz/openfga.adoc

This is an example response after successfully configuring an OpenFGA authorization model. The 'authorization_model_id' is required for setting up rules.

```json
{
  "authorization_model_id":"01HSXG7TBQEJ7GBPKQR2VYH24G"
}
```

--------------------------------

### Example Host Matching with Wildcard

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/rules/regular_rule.adoc

Specifies a set of hosts to match against the HTTP Host header, including wildcard support. Matches are case-insensitive.

```yaml
hosts:
  - "*.example.com"
  - "example.org"
```

--------------------------------

### Deployment Resource Configuration

Source: https://github.com/dadrus/heimdall/blob/main/charts/heimdall/README.adoc

Example of specifying resource requests and limits for the Heimdall deployment. Adjust memory based on cache backend configuration.

```yaml
deployment:
  resources:
    limits:
      cpu: 125m
      memory: 256Mi
    requests:
      cpu: 125m
      memory: 256Mi
```

--------------------------------

### Reverse Proxy Request Example

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/concepts/operating_modes.adoc

Demonstrates an incoming request to Heimdall and its subsequent transformation when forwarded to an upstream service based on a defined rule.

```bash
GET /my-service/api HTTP/1.1
Host: heimdall:4456

Some payload
```

```yaml
id: rule:my-service:anonymous-api-access
match:
  routes:
    - path: /my-service/api
  methods:
    - GET
forward_to:
  host: my-backend-service:8888
execute:
  - authenticator: anonymous-authn
  - finalizer: id-header
```

```bash
GET /my-service/api HTTP/1.1
Host: my-backend-service:8888
X-User-ID: anonymous

Some payload
```

--------------------------------

### Example JWKS File with Asymmetric Key

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/operations/secret_management.adoc

A sample JWKS file containing an asymmetric Ed25519 private key. Ensure the 'kid' is unique and non-empty.

```json
{
  "keys": [
    {
      "kty": "OKP",
      "kid": "ed25519-2026-01",
      "crv": "Ed25519",
      "x": "...",
      "d": "..."
    }
  ]
}
```

--------------------------------

### Run Documentation Server

Source: https://github.com/dadrus/heimdall/blob/main/CONTRIBUTING.md

Start the documentation server using Just to preview your changes locally. Access the documentation via the URL provided in the server's output.

```bash
> just run-docs
```

--------------------------------

### Text Log Format Example

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/operations/observability.adoc

Example output when Heimdall is configured to log in text format. This includes transaction start and finish events with various metrics and identifiers.

```text
2022-08-03T12:40:16+02:00 INF TX started _client_ip=127.0.0.1 _http_host=127.0.0.1:4468 _http_method=GET
 _http_path=/foo _http_scheme=http _http_user_agent=curl/7.74.0 _parent_id=3449bda63ed70206
 _span_id=f57c007257fee0ed _trace_id=00000000000000000a5af97bffe6a8a2 _tx_start=1659523216

....

2022-08-03T12:40:16+02:00 INF TX finished _access_granted=true _body_bytes_sent=0 _client_ip=127.0.0.1
 _http_host=127.0.0.1:4468 _http_method=GET _http_path=/foo _http_scheme=http _http_status_code=202
 _http_user_agent=curl/7.74.0 _subject=anonymous _parent_id=3449bda63ed70206 _span_id=f57c007257fee0ed
 _trace_id=00000000000000000a5af97bffe6a8a2 _tx_duration_ms=0 _tx_start=1659523216
```

--------------------------------

### Create Configuration Directories

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/guides/authn/dpop_bound_access_tokens.adoc

Create a directory for configuration files and subdirectories for rules and client configurations.

```bash
mkdir heimdall-dpop
cd heimdall-dpop
mkdir rules client
```

--------------------------------

### GELF Log Format Example

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/operations/observability.adoc

Example output when Heimdall is configured to use the GELF format for logging. This includes structured JSON messages for transaction start and finish events.

```json
{"_level_name": "INFO", "version":"1.1", "host":"unknown", "_tx_start":1659523295,
 "_client_ip": "127.0.0.1", "_http_method": "GET", "_http_path":"/foo",
 "_http_user_agent": "curl/7.74.0", "_http_host": "127.0.0.1:4468", "_http_scheme": "http",
 "timestamp": 1659523295, "level": 6, "_parent_id": "3449bda63ed70206",
 "_span_id": "f57c007257fee0ed", "_trace_id": "00000000000000000a5af97bffe6a8a2",
 "short_message": "TX started"}

....

{"_level_name": "INFO", "version": "1.1", "host": "unknown", "_tx_start": 1659523295,
 "_client_ip": "127.0.0.1", "_http_method": "GET", "_http_path": "/foo",
 "_http_user_agent": "curl/7.74.0", "_http_host": "127.0.0.1:4468", "_http_scheme": "http",
 "_body_bytes_sent": 0, "_http_status_code":200, "_tx_duration_ms":0, "_subject": "anonymous",
 "_access_granted": true, "timestamp":1659523295, "level": 6, "_parent_id": "3449bda63ed70206",
 "_span_id": "f57c007257fee0ed", "_trace_id": "00000000000000000a5af97bffe6a8a2",
 "short_message": "TX finished"}
```

--------------------------------

### CEL Authorization Expression Example

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/configuration/types.adoc

An example of a CEL expression to validate subject attributes. It checks if attributes have keys starting with 'group' and if all values in those group attributes are strings ending with '@acme.co'.

```yaml
expression: |
  subject.attributes.exists(c, c.startsWith('group')) &&
  subject.attributes
      .filter(c, c.startsWith('group'))
      .all(c, subject.attributes[c]
      .all(g, g.endsWith('@acme.co')))
message: No groups ending with @acme.co present
```

--------------------------------

### Clone and Set Up Repository

Source: https://github.com/dadrus/heimdall/blob/main/CONTRIBUTING.md

Steps to fork, clone the Heimdall repository, and add the upstream remote for tracking changes.

```bash
git clone https://github.com/your_github_username/heimdall.git
cd heimdall
git remote add upstream https://github.com/dadrus/heimdall.git
git fetch upstream
```

--------------------------------

### Client Help Options

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/guides/authn/dpop_bound_access_tokens.adoc

Displays the available command-line options for the DPoP client. Use this to explore further use cases and configurations for the client.

```bash
docker compose run --rm dpop-client uv run client -h
```

--------------------------------

### Keycloak Database Initialization Script

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/guides/authn/oidc_first_party_auth.adoc

A bash script to initialize the Keycloak PostgreSQL database, creating the necessary user and database.

```bash
#!/bin/bash
set -e

psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" <<-"EOSQL"
  CREATE USER keycloak WITH PASSWORD 'keycloak';
  CREATE DATABASE keycloak OWNER keycloak;
EOSQL
```

--------------------------------

### Hierarchic Scope Matcher - Example JSON Scope Claim

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/configuration/types.adoc

An example of a JSON scope claim that would match the 'my-service' hierarchic scope configuration.

```json
{
  "scope": ["my-service.orders", "my-service.orders.customers"]
}
```

--------------------------------

### Create OpenFGA Store

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/guides/authz/openfga.adoc

This command creates a new store in OpenFGA. Replace 'FGA Demo Store' with your desired store name. The response will contain the store ID needed for subsequent operations.

```bash
curl -X POST http://127.0.0.1:8080/stores \
  -H "content-type: application/json" \
  -d '{"name": "FGA Demo Store"}'
```

--------------------------------

### Cosign Attestation Payload Example

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/operations/security.adoc

Example of the JSON payload returned by Cosign when verifying an attestation. This payload contains the base64 encoded attestation data.

```json
{
  "payloadType": "application/vnd.in-toto+json",
  "payload": "eyJfdHlwZSI6Imh...LCJ2ZXJzaW9uIjoxfX0=",
  "signatures": [
    {
      "keyid": "",
      "sig": "MEQCICGdo9hmIUrBRzVQ23VS...6ToNGa5YrommZNCQ=="
    }
  ]
}
```

--------------------------------

### Configure Inline Secret Provider with Environment Variables

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/operations/secret_management.adoc

Example configuration for the Inline provider, demonstrating the use of environment variables for sensitive values like tokens and secrets.

```yaml
secret_management:
  my_inline_source:
    type: inline
    config:
      github-token: "${GITHUB_TOKEN}"          # <1>
      oauth-github:                            # <2>
        client_id: heimdall
        client_secret: "${GITHUB_CLIENT_SECRET}"
```

--------------------------------

### Upgrade Heimdall Installation

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/operations/migration.adoc

Use this command to upgrade your Heimdall installation using Helm. Ensure you provide the correct paths to your values and configuration files.

```bash
$ helm upgrade --install <your-release-name> <chart-reference>  \
    -n <namespace-heimdall-is-installed-into> \
    -f <path/to/your/values.yaml> \
    -f <path/to/your/heimdall/config.yaml>
```

--------------------------------

### Decision Service Example Response

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/concepts/operating_modes.adoc

This example illustrates the expected response from Heimdall in Decision Mode after a successful rule match, including status code and headers.

```bash
HTTP/1.1 200 OK
Content-Type: application/json
X-User-ID: anonymous

{"message": "Access granted"}
```

--------------------------------

### Install Helm Chart in Decision Mode

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/getting_started/installation.adoc

Installs the heimdall chart with the release name 'my-release' and configures it for decision mode. A heimdall.yaml configuration file is required.

```bash
$ helm install my-release -f heimdall.yaml dadrus/heimdall
```

--------------------------------

### Basic CLI Usage

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/operations/cli.adoc

This is the general syntax for using the heimdall CLI. Use `heimdall help` for an overview of commands.

```bash
heimdall [command] [flags] [arguments]
```

--------------------------------

### Generic Contextualizer with GET and Forwarded Cookies

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/mechanisms/contextualizers.adoc

Configure a generic contextualizer to make an HTTP GET request. Use `forward_cookies` to pass specific cookies to the endpoint.

```yaml
id: foo
type: generic
config:
  endpoint:
    url: https://some-other.service/users/{{.Subject.ID}}
    method: GET
  forward_cookies:
    - X-My-Session-Cookie
```

--------------------------------

### Convert RuleSet Files for New Providers

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/operations/migration.adoc

This script demonstrates how to automate the conversion of existing RuleSet files to the new schema version for use with 'cloudblob', 'http_endpoint', or 'file_system' providers.

```bash
#!/usr/bin/env bash

```

--------------------------------

### Form URL Encoded Body Parsing Example

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/mechanisms/evaluation_objects.adoc

Illustrates parsing of an application/x-www-form-urlencoded request body into a map where values are string arrays. The example shows a simple key-value pair.

```yaml
context=heimdall
```

--------------------------------

### Basic Auth Strategy Configuration

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/configuration/types.adoc

Configure the basic authentication strategy using a credentials source and selector.

```yaml
type: basic_auth
config:
  credentials:
    source: my_secrets
    selector: creds
```

--------------------------------

### Assertions Configuration Example

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/configuration/types.adoc

Example of how to configure token and claim assertions for JWT or introspection responses. This includes issuers, audience, scopes, allowed algorithms, validity leeway, and proof-of-possession settings.

```yaml
issuers:
 - foo
 - bar
audience:
 - zap
scopes:
 - baz
allowed_algorithms:
 - ES512
validity_leeway: 5s
proof_of_possession:
  type: dpop
  config:
    max_age: 1m
    nonce_required: false
    replay_allowed: false
```

--------------------------------

### Complex Management Service Configuration Example

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/services/management.adoc

This YAML snippet demonstrates a complex configuration for the management service, specifying host, TLS settings, timeouts, and buffer limits.

```yaml
management:
  host: 127.0.0.1
  tls:
    secret:
      source: key_store
      password: tls_key
  timeout:
    read: 1s
    write: 2s
    idle: 30s
  buffer_limit:
    read: 4KB
    write: 10KB
```

--------------------------------

### Redis Sentinel Cache Configuration Example

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/operations/cache.adoc

Example YAML configuration for a Redis Sentinel cache. Specify 'redis-sentinel' as the type and provide mandatory 'nodes' and 'master' details along with optional 'db' and 'credentials'.

```yaml
cache:
  type: redis-sentinel
  config:
    nodes:
    - foo:1234
    - bar:1234
    db: 0
    master: whatever
    credentials:
      source: some_source
      selector: redis_creds
```

--------------------------------

### Install Helm Chart in Proxy Mode

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/getting_started/installation.adoc

Installs the heimdall chart with the release name 'my-release' and configures it for proxy mode using the --set operationMode=proxy flag. A heimdall.yaml configuration file is required.

```bash
$ helm install my-release -f heimdall.yaml --set operationMode=proxy dadrus/heimdall
```

--------------------------------

### Authentication Data Source Fallback Strategies

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/configuration/types.adoc

Configures multiple strategies for retrieving authentication data from a request, with fallbacks. This example shows trying the Authorization header, then a query parameter, then a body parameter.

```yaml
- header: Authorization
  scheme: Bearer
- query_parameter: access_token
- body_parameter: access_token
```

--------------------------------

### JWT Finalizer Configuration

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/mechanisms/finalizers.adoc

Example of configuring a jwt_finalizer with custom values.

```yaml
execute:
- finalizer: jwt_finalizer
  config:
    values:
      foo: bar
      user_id: '{{ .Subject.ID }}'
```

--------------------------------

### Configure Basic Auth Strategy Credentials

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/configuration/types.adoc

Set up Basic Authentication by providing a secret reference for credentials. The referenced secret must contain `user_id` and `password` entries.

```yaml
type: basic_auth
config:
  credentials:
    source: my_secrets
    selector: my_basic_auth_credentials
```

--------------------------------

### Clone Heimdall Repository

Source: https://github.com/dadrus/heimdall/blob/main/charts/heimdall/README.adoc

Clone the Heimdall Git repository to install the chart from its sources.

```bash
git clone https://github.com/dadrus/heimdall
```

--------------------------------

### Disable Tracing Configuration

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/operations/observability.adoc

Example configuration to disable tracing in Heimdall. Tracing is enabled by default.

```yaml
tracing:
  enabled: false
```

--------------------------------

### Configuration with Environment Variable Substitution

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/operations/configuration.adoc

Demonstrates using environment variables for simple and complex values, such as specifying the introspection endpoint authentication and the signer secret source.

```yaml
mechanisms:
  authenticators:
  - id: hydra_authenticator
    type: oauth2_introspection
    config:
      introspection_endpoint:
        url: https://hydra:4445/oauth2/introspect
        auth: ${INTROSPECTION_EP_AUTH}
  finalizers:
  - id: create_jwt
    type: jwt
    config:
      signer:
        secret:
          source: ${SIGNER_STORE_SOURCE}
```

--------------------------------

### Configure Redis Cluster Cache

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/operations/cache.adoc

Example of configuring a Redis cluster with node addresses and credentials.

```yaml
cache:
  type: redis-cluster
  config:
    nodes:
    - foo:1234
    - bar:1234
    credentials:
      source: some_source
      selector: redis_creds
```

--------------------------------

### Configure Redis Single Instance Cache

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/operations/cache.adoc

Example of configuring a single Redis instance with various options including credentials, client cache, buffer limits, timeouts, and TLS.

```yaml
cache:
  type: redis
  config:
    address: foo:12345
    credentials:
      path: /path/to/credentials.yaml
    client_cache:
      ttl: 10m
      size_per_connection: 128MB
    buffer_limit:
      read: 1MB
      write: 1MB
    timeout:
      write: 150s
    max_flush_delay: 20us
    tls:
      # TLS client auth is used here
      secret:
        source: key_store
        selector: redis_key
      min_version: TLS1.2
```

--------------------------------

### Cache Configuration

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/configuration/reference.adoc

Sets up the cache type, configuration details including database, master, nodes, credentials, TLS settings, and client cache TTL.

```yaml
cache:
  type: redis-sentinel
  config:
    db: 2
    master: whatever
    nodes:
    - foo:1234
    - bar:1234
    credentials:
      path: /path/to/credentials.yaml
    tls:
      secret:
        source: redis_store
        selector: key1
      min_version: TLS1.2
      cipher_suites:
        - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
        - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
    client_cache:
      ttl: 10m
    max_flush_delay: 20us
```

--------------------------------

### Verify Release Binary Signature with Cosign

Source: https://github.com/dadrus/heimdall/blob/main/docs/content/docs/operations/security.adoc

Verify the signature of a downloaded release binary archive. This command requires the archive, its signature, and a certificate.

```bash
cosign verify-blob /path/to/the/downloaded/<archive> \
  --certificate-identity-regexp=https://github.com/dadrus/heimdall/.github/workflows/release.yaml* \
  --certificate-oidc-issuer=https://token.actions.githubusercontent.com \
  --signature /path/to/the/downloaded/<archive>.sig \
  --certificate /path/to/the/downloaded/<archive>.pem
```