Kong Authorizer configuration reference

Learn how to configure Kong Authorizer to adjust authorizer's settings to your needs.

Configuring Kong Authorizer

The Kong Authorizer can be configured with a file in YAML format, or via environment variables. To generate a template configuration file that is populated with default settings, you can use a Docker image and pipe the output to a configuration file:

docker run --rm docker.cloudentity.io/kong-authorizer reference > reference_config.yaml

You can use the reference configuration as a basis for your customization. You can omit settings for which the default configuration is satisfactory, specifying only the required values, which are the client ID, client secret, issuer URL, and Kong admin URL parameters.

ACP_CLIENT_ID: {your_client_id}
ACP_CLIENT_SECRET: {your_client_secret}
ACP_ISSUER_URL: https://{tid}.us.authz.stage.cloudentity.io/{tid}/system
KONG_ADMIN_URL: http://kong-acp:8001

Environment variables can also be used to set these configuration values. The environment variable’s name are the uppercase version of the YAML name. For example, in the docker-compose.yml that you downloaded, you can set the ACP_CLIENT_ID via the environment variable ACP_CLIENT_ID:

    environment:
      - ACP_CLIENT_ID=${CLIENT_ID}
      - ACP_CLIENT_SECRET=${CLIENT_SECRET}
      - ACP_ISSUER_URL=${ISSUER_URL}
      - ACP_HTTP_CLIENT_INSECURE_SKIP_VERIFY=TRUE
      - KONG_ADMIN_URL=${KONG_ADMIN_URL}
      - KONG_HTTP_CLIENT_INSECURE_SKIP_VERIFY=TRUE
      - SERVER_LISTENER_PORT=9003

Tip

Note that nested YAML settings can be accessed by joining uppercased names with underscores, as shown in the example above, where the SERVER_LISTENER_PORT=9003 parameter is set.

To run the kong authorizer with a configuration file, use the --config option to specify the YAML file with your configuration. For example, assuming that you have created a kong_config.yaml file in your current directory your docker run command would look like the following:

docker run --rm --volume `pwd`:/config:ro docker.cloudentity.io/kong-authorizer --config /config/kong_config.yaml

Authenticating to the Kong Admin API

The Kong Authorizer can authenticate to the Kong Admin API in one of three ways:

RBAC User Token
HTTP Basic Authentication
OAUTH2 Authentication

RBAC Authentication

To authenticate when the Kong Admin API is secured by RBAC, supply the RBAC user token via the environment variable KONG_ADMIN_TOKEN, or the YAML field kong.admin_token:

Licensed Enterprise users only

RBAC is only available for licensed Kong Gateway users. It’s not possible to enable RBAC on a free Kong Enterprise version or the Open Source version.

kong:
  admin_url: https://kong:8444
  admin_token: vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8

Basic Authentication

To authenticate when the Kong Admin API is secured by the Kong basic-auth plugin, specify the environment variables KONG_ADMIN_USERNAME and KONG_ADMIN_PASSSWORD, or specify them via the YAML configuration:

kong:
  admin_url: https://kong:8443/admin-api
  admin_username: kong-admin
  admin_password: sesame

As a result, when the authorizer tries to access the Kong API without credentials, the request fails.

{
    "message": "Unauthorized"
}

OAuth2 Authentication

To authenticate when the Kong Admin API is secured by the Kong oauth2 plugin, specify the environment variables KONG_ADMIN_CLIENT_ID, KONG_ADMIN_CLIENT_SECRET, and KONG_ADMIN_ISSUER_URL, or specify them via the YAML configuration:

kong:
  admin_url: https://kong:8443/admin-api
  admin_client_id: kong-authorizer-id
  admin_client_secret: kong-authorizer-secret
  admin_issuer_url: https://kong:8443/admin-api

As a result, when the authorizer tries to access the Kong API without the access token, the request fails.

{"error":"invalid_request","error_description":"The access token is missing"}

Configuration reference

 # acp
acp:
    reload_interval: 1m0s # reload interval
    reload_timeout: 30s # reload configuration timeout
    issuer_url: https://localhost:8443/sample/system # issuer url
    client_id: bqesdrc4m4co2s81mpu0 # client id
    client_secret: LH6mAb6PNljvjYMIF-A5RP2bElA5a5bnQah8sG0fsLA # client secret
    tenant_id: "" # tenant id
    server_id: "" # server id
# http client
http_client:
    timeout: 10s # http client timeout
    retry_wait_min: 0s # minimum time to wait between retries
    retry_wait_max: 0s # maximum time to wait between retries
    retry_max: 0 # maximum number of retries
    root_ca: "" # root ca that this client should trust (defaults to system root ca)
    insecure_skip_verify: false # disable cert verification
    disable_follow_redirects: false # disable follow redirects
    disable_retry: true # disable retry
# metrics
metrics:
    enabled: false # enable metrics endpoint
    port: 9000 # metrics endpoint port
# analytics
analytics:
    enabled: true # when enabled, events are sent to audit log
    # event format
    event_format:
        include_policy_output: false # when enabled, policy evaluation output is sent to audit log
    # sampling
    sampling:
        probability: 1 # Probability of an event to be published (0.0-1.0)
        batch_inverval: 1s # Max duration to wait for a batch to publish
        batch_limit: 100 # Max number of events in a batch
        limit: 5 # Max number of batches per second to be published
        timeout: 5s # Timeout for a single batch to send
        workers: 8 # Number of sending workers
# cache
cache:
    ttl: 10s # ttl
    max_size: 100 # max size
# logging config
logging:
    level: info # log level severity
# token echange config
token_exchange:
    enabled: false # enable token exchange
    # cache
    cache:
        ttl: 1m0s # ttl
        max_size: 1000 # max size
    # inject config (supported only for istio authorizer)
    inject:
        mode: "" # Defines what token should be sent to the target service when token is exchanged
        # headers config
        headers:
            exchanged_token: "" # Defines the name of the header that contains an exchanged token.
            original_token: "" # Defines the name of the header that contains an original token.
            strip_bearer: false # Allows to strip the bearer prefix in headers
# enforcement config
enforcement:
    allow_unknown: false # allow requests with no matching rule
# discovery config
discovery:
    enabled: true # when true, API discovery is enabled
    timeout: 10s # discovery process timeout
    interval: 30s # how often discovery is performed
# http server
http_server:
    port: 9003 # http port
    dangerous_disable_tls: false # diables TLS
    # certificate configuration
    certificate:
        password: "" # key passphrase
        cert_path: "" # path to the certificate PEM file
        key_path: "" # path to the key PEM file
        cert: "" # base64 encoded cert PEM
        key: "" # base64 encoded key PEM
        generated_key_type: ecdsa # type for generated key if cert and key are not provided (rsa or ecda)
    client_auth_type: 0 # client auth type
# kong
kong:
    admin_url: "" # kong admin url indicates the Kong Admin API
    admin_token: "" # kong admin token for RBAC authentication to Kong Admin API
    admin_username: "" # kong admin username for Basic Auth to Kong Admin API
    admin_password: "" # kong admin password for Basic Auth to Kong Admin API
    admin_client_id: "" # kong admin client ID for OAuth2 authentication to the Kong Admin API
    admin_client_secret: "" # kong admin client secret for OAuth2 authentication to the Kong Admin API
    admin_issuer_url: "" # kong admin issuer url for OAuth2 authentication to the Kong Admin API
    # http client used to access the Kong Admin API
    http_client:
        timeout: 0s # http client timeout
        retry_wait_min: 0s # minimum time to wait between retries
        retry_wait_max: 0s # maximum time to wait between retries
        retry_max: 0 # maximum number of retries
        root_ca: "" # root ca that this client should trust (defaults to system root ca)
        insecure_skip_verify: true # disable cert verification
        disable_follow_redirects: false # disable follow redirects
        disable_retry: false # disable retry