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:
  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
  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
  - id: kratos_session_authenticator
    type: generic
    config:
      identity_info_endpoint:
        url: https://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"
  - id: hydra_authenticator
    type: oauth2_introspection
    config:
      introspection_endpoint:
        url: https://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:
          - https://127.0.0.1:4444/
        scopes:
          - foo
          - bar
        audience:
          - bla
      subject:
        attributes: "@this"
        id: "sub"
  - id: jwt_authenticator
    type: jwt
    config:
      metadata_endpoint:
        url: https://auth-server/.well-known/oauth-authorization-server
        disable_issuer_identifier_verification: true
        http_cache:
          enabled: true
          cache_ttl: 1h
        resolved_endpoints:
          jwks_uri:
            auth:
              type: oauth2_client_credentials
              config:
                token_url: https://auth-server/token
                client_id: foo
                client_secret: bar
            retry:
              give_up_after: 1m
              max_delay: 5s
            http_cache:
              enabled: true
              default_ttl: 10m
      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

  authorizers:
  - id: allow_all_authorizer
    type: allow
  - id: deny_all_authorizer
    type: deny
  - id: remote_authorizer
    type: remote
    config:
      endpoint:
        url: https://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: https://foo.bar
        method: GET
        headers:
          bla: bla
        auth:
          type: oauth2_client_credentials
          config:
            auth_method: request_body
            token_url: https://bar.foo
            client_id: foo
            client_secret: bar
            cache_ttl: 20s
            header:
              name: X-Foo
              scheme: Bar
      payload: foo
  - id: profile_data_contextualizer
    type: generic
    config:
      endpoint:
        url: https://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: https://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: https://foo.bar/ruleset1
        http_cache:
          enabled: false
      - url: https://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 Apr 8, 2025