Reference

Below you can find possible contents (not exhaustive) for Heimdall’s config.yaml file. Head over to configuration documentation to get detailed explanation.

serve:
  decision:
    host: 127.0.0.1
    port: 4468
    respond:
      verbose: true
      with:
        accepted:
          code: 201
        authorization_error:
          code: 404
        authentication_error:
          code: 404
    timeout:
      read: 2s
      write: 5s
      idle: 2m
    buffer_limit:
      read: 10KB
      write: 10KB
    tls:
      key_store:
        path: /path/to/key/store.pem
        password: VerySecure!
    trusted_proxies:
      - 192.168.1.0/24

  proxy:
    host: 127.0.0.1
    port: 4469
    respond:
      verbose: true
      with:
        authorization_error:
          code: 404
        authentication_error:
          code: 404
    timeout:
      read: 2s
      write: 5s
      idle: 2m
    connections_limit:
      max_per_host: 10
      max_idle: 100
      max_idle_per_host: 50
    buffer_limit:
      read: 10KB
      write: 10KB
    cors:
      allowed_origins:
        - example.org
      allowed_methods:
        - GET
        - POST
      allowed_headers:
        - Authorization
      exposed_headers:
        - X-My-Header
      allow_credentials: true
      max_age: 1m
    tls:
      key_store:
        path: /path/to/key/store.pem
        password: VerySecure!
      key_id: first_entry
      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
    trusted_proxies:
      - 192.168.1.0/24

  management:
    host: 127.0.0.1
    port: 4457
    verbose_errors: false
    timeout:
      read: 2s
      write: 5s
      idle: 2m
    cors:
      allowed_origins:
        - example.org
      allowed_methods:
        - GET
        - POST
      allowed_headers:
        - Authorization
      exposed_headers:
        - X-My-Header
      allow_credentials: true
      max_age: 1m
    tls:
      key_store:
        path: /path/to/key/store.pem
      min_version: TLS1.2

cache:
  type: redis-sentinel
  config:
    db: 2
    master: whatever
    nodes:
    - foo:1234
    - bar:1234
    credentials:
      path: /path/to/credentials.yaml
    tls:
      key_store:
        path: /path/to/redis_client_keystore.pem
      key_id: bf5d129a7fec8b1fde11eab459784cc2f14e6c1d
      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

secrets_reload_enabled: true

log:
  level: debug
  format: text

tracing:
  enabled: true
  span_processor: batch

metrics:
  enabled: true

profiling:
  enabled: false
  host: 0.0.0.0
  port: 9000

mechanisms:
  authenticators:
  - id: anonymous_authenticator
    type: anonymous
  - id: unauthorized_authenticator
    type: unauthorized
  - id: foo
    type: basic_auth
    config:
      user_id: bar
      password: baz
      allow_fallback_on_error: true
  - id: kratos_session_authenticator
    type: generic
    config:
      identity_info_endpoint:
        url: http://127.0.0.1:4433/sessions/whoami
        auth:
          auth:
            type: basic_auth
            config:
              user: foo
              password: bar
        retry:
          max_delay: 300ms
          give_up_after: 2s
      authentication_data_source:
        - cookie: ory_kratos_session
      forward_cookies:
        - ory_kratos_session
      subject:
        attributes: "@this"
        id: "identity.id"
      allow_fallback_on_error: true
  - id: hydra_authenticator
    type: oauth2_introspection
    config:
      introspection_endpoint:
        url: http://hydra:4445/oauth2/introspect
        retry:
          max_delay: 300ms
          give_up_after: 2s
        auth:
          type: api_key
          config:
            in: header
            name: X-Api-Key
            value: VerySecret!
      token_source:
        - header: Authorization
          scheme: Bearer
        - query_parameter: access_token
        - body_parameter: access_token
      assertions:
        issuers:
          - http://127.0.0.1:4444/
        scopes:
          - foo
          - bar
        audience:
          - bla
      subject:
        attributes: "@this"
        id: "sub"
      allow_fallback_on_error: true
  - id: jwt_authenticator
    type: jwt
    config:
      metadata_endpoint:
        url: http://auth-server/.well-known/oauth-authorization-server
        disable_issuer_identifier_verification: true
        http_cache:
          enabled: true
          cache_ttl: 1h
      jwt_source:
        - header: Authorization
          scheme: Bearer
        - query_parameter: access_token
        - body_parameter: access_token
      assertions:
        audience:
          - bla
        scopes:
          - foo
        allowed_algorithms:
          - RS256
      subject:
        attributes: "@this"
        id: "identity.id"
      cache_ttl: 5m
      allow_fallback_on_error: true

  authorizers:
  - id: allow_all_authorizer
    type: allow
  - id: deny_all_authorizer
    type: deny
  - id: remote_authorizer
    type: remote
    config:
      endpoint:
        url: http://my-authz-system/{{ .Values.some-key }}
        method: POST
        headers:
          foo-bar: "{{ .Subject.ID }}"
        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: |
            Payload.response == true
      forward_response_headers_to_upstream:
        - bla-bar
  - id: user_is_admin_authz
    type: cel
    config:
      expressions:
        - expression: "'admin' in Subject.Attributes.groups"

  contextualizers:
  - id: subscription_contextualizer
    type: generic
    config:
      endpoint:
        url: http://foo.bar
        method: GET
        headers:
          bla: bla
        auth:
          type: oauth2_client_credentials
          config:
            auth_method: request_body
            token_url: http://bar.foo
            client_id: foo
            client_secret: bar
            cache_ttl: 20s
            header:
              name: X-Foo
              scheme: Bar
      payload: http://foo
  - id: profile_data_contextualizer
    type: generic
    config:
      endpoint:
        url: http://profile
        headers:
          foo: bar
      continue_pipeline_on_error: true

  finalizers:
  - id: jwt
    type: jwt
    config:
      signer:
        name: foobar
        key_store:
          path: /opt/heimdall/keystore.pem
          password: VeryInsecure!
        key_id: foo
      ttl: 5m
      header:
        name: Foo
        scheme: Bar
      claims: "{'user': {{ quote .Subject.ID }} }"
  - id: bla
    type: header
    config:
      headers:
        foo-bar: bla
  - id: blabla
    type: cookie
    config:
      cookies:
        foo-bar: '{{ .Subject.ID }}'
  - id: get_token
    type: oauth2_client_credentials
    config:
      header:
        name: X-Token
      token_url: https://my-oauth-provider.com/token
      client_id: my_client
      client_secret: VerySecret!
      auth_method: basic_auth
      cache_ttl: 5m
      scopes:
        - foo
        - bar

  error_handlers:
  - id: default
    type: default
  - id: authenticate_with_kratos
    type: redirect
    config:
      to: http://127.0.0.1:4433/self-service/login/browser?return_to={{ .Request.URL | urlenc }}

default_rule:
  backtracking_enabled: false
  execute:
  - authenticator: anonymous_authenticator
  - finalizer: jwt
  on_error:
  - error_handler: authenticate_with_kratos
    if: |
      ((type(Error) == authentication_error && Error.Source == "kratos_session_authenticator") ||
        type(Error) == authorization_error) &&
        Request.Header("Accept").contains("*/*")

providers:
  file_system:
    src: test_rules.yaml
    watch: true

  http_endpoint:
    watch_interval: 5m
    endpoints:
      - url: http://foo.bar/ruleset1
        http_cache:
          enabled: false
      - url: http://foo.bar/ruleset2
        retry:
          give_up_after: 5s
          max_delay: 250ms
        auth:
          type: api_key
          config:
            name: api_key
            value: super-secret
            in: cookie
        header:
          X-Customer-Header: Some Value

  cloud_blob:
    watch_interval: 1m
    buckets:
      - url: gs://my-bucket
        prefix: service1
      - url: azblob://my-bucket
        prefix: service2
      - url: s3://my-bucket/my-rule-set

  kubernetes:
    auth_class: foo
    tls:
      key_id: foo
      key_store:
        path: /path/to/pem.file
        password: VerySecret!
      min_version: TLS1.3

Last updated on Sep 13, 2024