This page defines the format of OPA configuration files. Fields marked as required must be specified if the parent is defined. For example, when the configuration contains a status key, the status.service field must be defined.

The configuration file path is specified with the -c or --config-file command line argument:

opa run -s -c config.yaml

The file can be either JSON or YAML format.

Example

services:
  acmecorp:
    url: https://example.com/control-plane-api/v1
    response_header_timeout_seconds: 5
    credentials:
      bearer:
        token: "bGFza2RqZmxha3NkamZsa2Fqc2Rsa2ZqYWtsc2RqZmtramRmYWxkc2tm"

labels:
  app: myapp
  region: west
  environment: production

bundles:
  authz:
    service: acmecorp
    resource: bundles/http/example/authz.tar.gz
    persist: true
    polling:
      min_delay_seconds: 60
      max_delay_seconds: 120
    signing:
      keyid: global_key
      scope: write

decision_logs:
  service: acmecorp
  reporting:
    min_delay_seconds: 300
    max_delay_seconds: 600

status:
  service: acmecorp

default_decision: /http/example/authz/allow

persistence_directory: /var/opa

keys:
  global_key:
    algorithm: RS256
    key: <PEM_encoded_public_key>
    scope: read

caching:
  inter_query_builtin_cache:
    max_size_bytes: 10000000

distributed_tracing:
  type: grpc
  address: localhost:4317
  service_name: opa
  sample_percentage: 50
  encryption: "off"

Environment Variable Substitution

Only supported with the OPA runtime (opa run).

Environment variables referenced with the ${...} notation within the configuration will be replaced with the value of the environment variable.

Example using BASE_URL and BEARER_TOKEN environment variables:

services:
  acmecorp:
    url: "${BASE_URL}"
    credentials:
      bearer:
        token: "${BEARER_TOKEN}"

discovery:
  resource: /configuration/example/discovery
  decision: example

The environment variables BASE_URL and BEARER_TOKEN will be substituted in when the config file is loaded by the OPA runtime.

If the variable is undefined then an empty string ("") is substituted. It will not raise an error.

CLI Runtime Overrides

Only supported with the OPA runtime (opa run).

Using opa run there are CLI options to explicitly set config values. These will override any values set in the config file.

There are two options to use: --set and --set-file

Both options take in a key=value format where the key is a selector for the yaml config structure, for example: decision_logs.reporting.min_delay_seconds=300 is equivalent to JSON {"decision_logs": {"reporting": {"min_delay_seconds": 300}}}. Multiple values can be specified with comma separators (key1=value,key2=value2,..). Or with additional --set parameters.

Example using several different options:

opa run \
  --set "default_decision=/http/example/authz/allow" \
  --set "services.acmecorp.url=https://test-env/control-plane-api/v1" \
  --set "services.acmecorp.credentials.bearer.token=\${TOKEN}"
  --set "labels.app=myapp,labels.region=west"

This is equivalent to a YAML config file that looks like:

services:
  acmecorp:
    url: https://test-env/control-plane-api/v1
    credentials:
      bearer:
        token: ${TOKEN}

labels:
  app: myapp
  region: west

default_decision: /http/example/authz/allow

The --set-file option is expecting a file path for the value. This allows keeping secrets in files and loading them into the config at run time. For Example:

With a file /var/run/secrets/bearer_token.txt that has contents:

bGFza2RqZmxha3NkamZsa2Fqc2Rsa2ZqYWtsc2RqZmtramRmYWxkc2tm

Then using the --set-file flag for OPA

opa run --set-file "services.acmecorp.credentials.bearer.token=/var/run/secrets/bearer_token.txt"

It will read the contents of the file and set the config value with the token.

Override Limitations

Lists

If using arrays/lists in the configuration the --set and --set-file overrides will not be able to patch sub-objects of the list. They will overwrite the entire index with the new object.

For example, a config.yaml file with contents:

services:
  - name: acmecorp
    url: https://test-env/control-plane-api/v1
    credentials:
      bearer:
        token: ""

Used with overrides:

opa run \
  --config-file config.yaml
  --set-file "services[0].credentials.bearer.token=/var/run/secrets/bearer_token.txt"

Will result in configuration like:

services:
  - credentials:
      bearer:
        token: bGFza2RqZmxha3NkamZsa2Fqc2Rsa2ZqYWtsc2RqZmtramRmYWxkc2tm

Because the entire 0 index was overwritten.

It is highly recommended to use objects/maps instead of lists for configuration for this reason.

Empty objects

If you need to set an empty object with the CLI overrides, for example with plugin configuration like:

decision_logs:
  plugin: my_plugin

plugins:
  my_plugin:
    # empty

You can do this by setting the value with null. For example:

opa run --set "decision_logs.plugin=my_plugin" --set "plugins.my_plugin=null"

Keys with Special Characters

If you have a key which contains a special character (=, [, ,, .), like opa.example.com, and want to use the --set or --set-file options you will need to escape the character with a backslash (\).

For example a config section like:

services:
  opa.example.com:
    url: https://opa.example.com

Could be specified with something like:

--set services.opa\.example\.com.url=https://opa.example.com

Note that when using it in a shell you may need to put it in quotes or escape the \ character too. For example:

--set services."opa\.example\.com".url=https://opa.example.com

or

--set services.opa\\.example\\.com.url=https://opa.example.com

Where the end result passed into OPA still has the \. preserved.

Services

Services represent endpoints that implement one or more control plane APIs such as the Bundle or Status APIs. OPA configuration files may contain multiple services.

Services can be defined as an array or object. When defined as an object, the object keys override the services[_].name fields. For example:

services:
  s1:
    url: https://s1/example/
  s2:
    url: https://s2/

Is equivalent to

services:
  - name: s1
    url: https://s1/example/
  - name: s2
    url: https://s2/

Each service may optionally specify a credential mechanism by which OPA will authenticate itself to the service.

Example

Using an OCI service type to download a bundle from an OCI repository.

services:
  ghcr-registry:
    url: https://ghcr.io
    type: oci

bundles:
  authz:
    service: ghcr-registry
    resource: ghcr.io/${ORGANIZATION}/${REPOSITORY}:${TAG}
    persist: true
    polling:
      min_delay_seconds: 60
      max_delay_seconds: 120

persistence_directory: ${PERSISTENCE_PATH}

When using an OCI service type the downloader uses the persistence path to store the layers of the downloaded repository. This storage path should be maintained by the user. If persistence is not configured the OCI downloader will store the layers in the system’s temporary directory to allow automatic cleanup on system restart.

Bearer Token

OPA will authenticate using the specified bearer token and schema; to enable bearer token authentication, either the token or the path to the token must be specified. If the latter is provided, on each request OPA will re-read the token from the file and use that token for authentication.

The scheme attribute is optional, and will default to Bearer if unspecified.

Client TLS Certificate

OPA will present the specified TLS certificate to authenticate. The paths to the client certificate and the private key are required; the passphrase for the private key is only required if the private key is encrypted.

OAuth2 Client Credentials

OPA will authenticate using a bearer token obtained through the OAuth2 client credentials flow. Following successful authentication at the token endpoint the returned token will be cached for subsequent requests for the duration of its lifetime. Note that as per the OAuth2 standard, only the HTTPS scheme is supported for the token endpoint URL.

OAuth2 Client Credentials JWT authentication

OPA will authenticate using a bearer token obtained through the OAuth2 client credentials flow. Rather than providing a client secret along with the request for an access token, the client asserts its identity in the form of a signed JWT. Following successful authentication at the token endpoint the returned token will be cached for subsequent requests for the duration of its lifetime. Note that as per the OAuth2 standard, only the HTTPS scheme is supported for the token endpoint URL.

Two claims will always be included in the issued JWT: iat and exp. Any other claims will be populated from the additional_claims map.

Example

Using the client credentials grant type with JWT client authentication replacing client secret as the credential used at the token endpoint.

services:
  remote:
    url: ${BUNDLE_SERVICE_URL}
    credentials:
      oauth2:
        token_url: ${TOKEN_URL}
        grant_type: client_credentials
        client_id: opa-client
        signing_key: jwt_signing_key # references the key in `keys` below
        include_jti_claim: true
        scopes:
        - read
        - write
        additional_claims:
          sub: opa-client
          iss: opa-${POD_NAME}

bundles:
  authz:
    service: remote
    resource: bundles/http/example/authz.tar.gz

keys:
  jwt_signing_key:
    algorithm: ES512
    private_key: ${BUNDLE_SERVICE_SIGNING_KEY}

OAuth2 JWT Bearer Grant Type

OPA will authenticate using a bearer token obtained through the OAuth2 JWT authorization grant flow. Rather than providing a client secret along with the request for an access token, the client asserts its identity in the form of a signed JWT. Following successful authentication at the token endpoint the returned token will be cached for subsequent requests for the duration of its lifetime. Note that as per the OAuth2 standard, only the HTTPS scheme is supported for the token endpoint URL.

Two claims will always be included in the issued JWT: iat and exp. Any other claims will be populated from the additional_claims map.

Example

Using a Google Cloud Storage bucket as a bundle service backend from outside the cloud account (for access from inside the account, see the GCP Metadata Token section).

services:
  gcp:
    url: https://storage.googleapis.com/storage/v1/b/${BUCKET_NAME}/o
    credentials:
      oauth2:
        token_url: https://oauth2.googleapis.com/token
        grant_type: jwt_bearer
        signing_key: jwt_signing_key # references the key in `keys` below
        scopes:
        - https://www.googleapis.com/auth/devstorage.read_only
        additional_claims:
          aud: https://oauth2.googleapis.com/token
          iss: opa-client@my-account.iam.gserviceaccount.com

bundles:
  authz:
    service: gcp
    resource: 'bundles/http/example/authz.tar.gz?alt=media'

keys:
  jwt_signing_key:
    algorithm: RS256
    private_key: ${BUNDLE_SERVICE_SIGNING_KEY}

AWS Signature

OPA will authenticate with an AWS4 HMAC signature. Several methods of obtaining the necessary credentials are available; exactly one must be specified to use the AWS signature authentication method.

The AWS service for which to sign the request can be specified in the service field. If omitted, the default is s3.

Using Static Environment Credentials

If specifying environment_credentials, OPA will expect to find environment variables for AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_REGION, in accordance with the convention used by the AWS CLI.

Please note that if you are using temporary IAM credentials (e.g. assumed IAM role credentials) you have to provide additional AWS_SESSION_TOKEN or AWS_SECURITY_TOKEN environment variable.

Using Named Profile Credentials

If specifying profile_credentials, OPA will expect to find the access key id, secret access key and session token from the named profiles stored in the credentials file on disk. On each request OPA will re-read the credentials from the file and use them for authentication.

Using EC2 Metadata Credentials

If specifying metadata_credentials, OPA will use the AWS metadata services for EC2 or ECS to obtain the necessary credentials when running within a supported virtual machine/container.

To use the EC2 metadata service, the IAM role to use and the AWS region for the resource must both be specified as iam_role and aws_region respectively.

To use the ECS metadata service, specify only the AWS region for the resource as aws_region. ECS containers have at most one associated IAM role.

Providing a value for iam_role will cause OPA to use the EC2 metadata service even if running inside an ECS container. This may result in unexpected problems if, for example, there is no route to the EC2 metadata service from inside the container or if the IAM role is only available within the container and not from the hosting EC2 instance.

Using EKS IAM Roles for Service Account (Web Identity) Credentials

If specifying web_identity_credentials, OPA will expect to find environment variables for AWS_ROLE_ARN and AWS_WEB_IDENTITY_TOKEN_FILE, in accordance with the convention used by the AWS EKS IAM Roles for Service Accounts.

GCP Metadata Token

OPA will authenticate with a GCP access token or identity token fetched from the Compute Metadata Server. When one or more scopes is provided an access token is fetched. When a non-empty audience is provided an identity token is fetched. An audience or scopes array is required.

When authenticating to native GCP services such as Google Cloud Storage an access token should be used with the appropriate set of scopes required by the target resource. When authenticating to a third party application such as an application hosted on Google Cloud Run an identity token should be used.

Example

Using a Cloud Run service as a bundle service backend.

services:
  cloudrun:
    url: ${BUNDLE_SERVICE_URL}
    response_header_timeout_seconds: 5
    credentials:
      gcp_metadata:
        audience: ${BUNDLE_SERVICE_URL}

bundles:
  authz:
    service: cloudrun
    resource: bundles/http/example/authz.tar.gz
    persist: true
    polling:
      min_delay_seconds: 60
      max_delay_seconds: 120

Using Google Cloud Storage as a bundle service backend.

services:
  gcs:
    url: https://storage.googleapis.com/storage/v1/b/${BUCKET_NAME}/o
    response_header_timeout_seconds: 5
    credentials:
      gcp_metadata:
        scopes:
          - "https://www.googleapis.com/auth/devstorage.read_only"

bundles:
  authz:
    service: gcs
    resource: 'bundle.tar.gz?alt=media'
    persist: true
    polling:
      min_delay_seconds: 60
      max_delay_seconds: 120

Azure Managed Identities Token

OPA will authenticate with an Azure managed identities token. The token request can be configured via the plugin to customize the base URL, API version, and resource. Specific managed identity IDs can be optionally provided as well.

Example

Use an Azure storage account as a bundle service backend. Note that the x-ms-version header must be specified for the storage account service, and a minimum version of 2017-11-09 must be provided as per Azure documentation.

services: 
  azure_storage_account: 
    url: ${STORAGE_ACCOUNT_URL}
    headers:
      x-ms-version: 2017-11-09
    response_header_timeout_seconds: 5
    credentials: 
      azure_managed_identity: {}

bundles: 
  authz: 
    service: azure_storage_account
    resource: bundles/http/example/authz.tar.gz
    persist: true
    polling: 
      min_delay_seconds: 60
      max_delay_seconds: 120

Custom Plugin

If none of the existing credential options work for a service, OPA can authenticate using a custom plugin, enabling support for any authentication scheme.

Example

Using a custom plugin for service credentials:

services:
  my_service:
    url: https://example.com/v1
    credentials:
      plugin: my_custom_auth
plugins:
  my_custom_auth:
    foo: bar

package plugins

import (
	"github.com/open-policy-agent/opa/plugins"
	"github.com/open-policy-agent/opa/plugins/rest"
	"github.com/open-policy-agent/opa/runtime"
	"github.com/open-policy-agent/opa/util"
)

type Config struct {
	Foo string `json:"foo"`
}

type PluginFactory struct{}

type Plugin struct {
	manager  *plugins.Manager
	config   Config
	stop     chan chan struct{}
	reconfig chan interface{}
}

func (p *PluginFactory) Validate(manager *plugins.Manager, config []byte) (interface{}, error) {
	var parsedConfig Config
	if err := util.Unmarshal(config, &parsedConfig); err != nil {
		return nil, err
	}
	return &parsedConfig, nil
}

func (p *PluginFactory) New(manager *plugins.Manager, config interface{}) plugins.Plugin {
	return &Plugin{
		config:   *config.(*Config),
		manager:  manager,
		stop:     make(chan chan struct{}),
		reconfig: make(chan interface{}),
	}
}

func (p *Plugin) Start(ctx context.Context) error {
	p.manager.UpdatePluginStatus(Name, &plugins.Status{State: plugins.StateOK})
	return nil
}

func (p *Plugin) Stop(ctx context.Context) {
	done := make(chan struct{})
	p.stop <- done
	<-done
	p.manager.UpdatePluginStatus(Name, &plugins.Status{State: plugins.StateNotReady})
	return
}

func (p *Plugin) Reconfigure(ctx context.Context, config interface{}) {
	p.reconfig <- config
	return
}

func (p *Plugin) NewClient(c rest.Config) (*http.Client, error) {
	t, err := rest.DefaultTLSConfig(c)
	if err != nil {
		return nil, err
	}
	return rest.DefaultRoundTripperClient(t, *c.ResponseHeaderTimeoutSeconds), nil
}

func (p *Plugin) Prepare(req *http.Request) error {
	req.Header.Add("X-Custom-Auth-Protocol", "knock knock")
	return nil
}

func init() {
	runtime.RegisterPlugin("my_custom_auth", &PluginFactory{})
}

Using private image from OCI repositories

When using a private image from an OCI registry the credentials are mandatory as the OCI downloader needs the credentials for the pull operation.

Examples of setting credetials for pulling private images: AWS ECR private image usually requires at least basic authentication. The credentials to authenticate can be obtained using the AWS CLI command aws ecr get-login and those can be passed to the service configuration as basic bearer credentials as follows:

 credentials:
      bearer:
        scheme: "Basic"
        token: "<username>:<password>"

The OCI downloader includes a base64 encoder for these credentials so they can be supplied as shown above.

For GHCR (Github Container Registry) you can use a developer PAT (personal access token) when downloading a private image. These can be supplied as:

 credentials:
      bearer:
        schema: "Bearer"
        token: "<PAT>"

Miscellaneous

Keys

Keys is a dictionary mapping the key name to the actual key and optionally the algorithm and scope.

Note: If the scope is provided in a bundle’s signing configuration (ie. bundles[_].signing.scope), it takes precedence over keys[_].scope.

The following signing algorithms are supported:

Caching

Caching represents the configuration of the inter-query cache that built-in functions can utilize.

Bundles

Bundles are defined with a key that is the name of the bundle. This name is used in the status API, decision logs, server provenance, etc.

Each bundle can be configured to verify a bundle signature using the keyid and scope fields. The keyid is the name of one of the keys listed under the keys entry.

Signature verification fails if the bundles[_].signing field is configured on a bundle but no .signatures.json file is included in the actual bundle gzipped tarball.

Status

Decision Logs

Discovery

⚠️ The plugin trigger mode configured on the discovery plugin will be inherited by the bundle, decision log and status plugins. For example, if the discovery plugin is configured to use the manual trigger mode, all other plugins will use manual triggering as well. If any of the plugins explicitly specify a different mode (for ex. periodic), OPA will generate a configuration error.

The following discovery configuration fields are supported but deprecated:

Distributed tracing

Distributed tracing represents the configuration of the OpenTelemetry Tracing.

The following encryption methods are supported:

Disk Storage

The storage configuration key allows for enabling, and configuring, the persistent on-disk storage of an OPA instance.

If disk is set to something, the server will enable the on-disk store with data put into the configured directory.

See the docs on disk storage for details about the settings.