Project: Open Policy Agent (OPA) (Provisioning / Security & Compliance)
File: configuration.md

title: Configuration kind: operations weight: 10 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: ```bash opa run -s -c config.yaml ``` The file can be either JSON or YAML format. The following is an example configuration file sets fields in many of the subcomponents inside of OPA. ```yaml services: acmecorp: url: https://example.com/control-plane-api/v1 responseheadertimeout_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: mindelayseconds: 60 maxdelayseconds: 120 signing: keyid: global_key scope: write decision_logs: service: acmecorp reporting: mindelayseconds: 300 maxdelayseconds: 600 status: service: acmecorp default_decision: /http/example/authz/allow persistence_directory: /var/opa keys: global_key: algorithm: RS256 key: <PEMencodedpublic_key> scope: read caching: interquerybuiltin_cache: maxsizebytes: 10000000 forcedevictionthreshold_percentage: 70 staleentryevictionperiodseconds: 3600 distributed_tracing: type: grpc address: localhost:4317 service_name: opa sample_percentage: 50 encryption: "off" server: encoding: gzip: min_length: 1024, compression_level: 9 ``` 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. | Field | Type | Required | Description | | | | | | | `services[_].name` | `string` | Yes | Unique name for the service. Referred to by plugins. | | `services[_].url` | `string` | Yes | Base URL to contact the service with. | | `services[].responseheadertimeoutseconds` | `int64` | No (default: 10) | Amount of time to wait for a server's response headers after fully writing the request. This time does not include the time to read the response body. | | `services[_].headers` | `object` | No | HTTP headers to include in requests to the service. | | `services[].tls.cacert` | `string` | No | The path to the root CA certificate. If not provided, this defaults to TLS using the host's root CA set. | | `services[].tls.systemca_required` | `bool` | No (default: `false`) | Require system certificate appended with root CA certificate. | | `services[].allowinsecure_tls` | `bool` | No | Allow insecure TLS. | | `services[_].type` | `string` | No (default: empty) | Optional parameter that allows to use an "OCI" service type. This will allow bundle and discovery plugins to download bundles from an OCI registry. | Services can be defined as an array or object. When defined as an object, the object keys override the `services[_].name` fields. For example: ```yaml services: s1: url: https://s1/example/ s2: url: https://s2/ ``` Is equivalent to ```yaml 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. 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. | Field | Type | Required | Description | | | | | | | `services[_].credentials.bearer.token` | `string` | Yes | Enables token-based authentication and supplies the bearer token to authenticate with. | |

| `string` | Yes | Enables token-based authentication and supplies the path to the bearer token to authenticate with. | | `services[_].credentials.bearer.scheme` | `string` | No | Bearer token scheme to specify. | 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. | Field | Type | Required | Description | | | | | | | `services[].credentials.clienttls.cert` | `string` | Yes | The path to the client certificate to authenticate with. | | `services[].credentials.clienttls.private_key` | `string` | Yes | The path to the private key of the client certificate. | | `services[].credentials.clienttls.privatekeypassphrase` | `string` | No | The passphrase to use for the private key. | OPA will authenticate using a bearer token obtained through the OAuth2 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 , only the HTTPS scheme is supported for the token endpoint URL. | Field | Type | Required | Description | | | | | | | `services[].credentials.oauth2.tokenurl` | `string` | Yes | URL pointing to the token endpoint at the OAuth2 authorization server. | | `services[].credentials.oauth2.clientid` | `string` | Yes | The client ID to use for authentication. | | `services[].credentials.oauth2.clientsecret` | `string` | Yes | The client secret to use for authentication. | | `services[_].credentials.oauth2.scopes` | `[]string` | No | Optional list of scopes to request for the token. | | `services[].credentials.oauth2.additionalheaders` | `map` | No | Map of additional headers to send to token endpoint at the OAuth2 authorization server | | `services[].credentials.oauth2.additionalparameters` | `map` | No | Map of additional body parameters to send token endpoint at the OAuth2 authorization server | OPA will authenticate using a bearer token obtained through the OAuth2 flow. Rather than providing a client secret along with the request for an access token, the client 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 , only the HTTPS scheme is supported for the token endpoint URL. | Field | Type | Required | Description | |-||-|-| | `services[].credentials.oauth2.tokenurl` | `string` | Yes | URL pointing to the token endpoint at the OAuth2 authorization server. | | `services[].credentials.oauth2.granttype` | `string` | No | Defaults to `client_credentials`. | | `services[].credentials.oauth2.clientid` | `string` | No | The client ID to use for authentication. | | `services[].credentials.oauth2.signingkey` | `string` | No | Reference to private key used for signing the JWT. Required if `aws_kms` is not provided | | `services[_].credentials.oauth2.thumbprint` | `string` | No | Certificate thumbprint to use for x5t header generation. | | `services[].credentials.oauth2.additionalclaims` | `map` | No | Map of claims to include in the JWT (see notes below) | | `services[].credentials.oauth2.includejti_claim` | `bool` | No | Include a uniquely generated `jti` claim in any issued JWT | | `services[_].credentials.oauth2.scopes` | `[]string` | No | Optional list of scopes to request for the token. | | `services[].credentials.oauth2.awskms.name` | `string` | No | To specify a KMS key, use its key ID, key ARN, alias name, or alias ARN. Required only for signing with AWS KMS. | |

| `string` | No | Specifies the signing algorithm used by the key `awskms.name` `(ECDSASHA256, ECDSASHA384 or ECDSASHA_512)`. Required only for signing with AWS KMS. | | `services[].credentials.oauth2.awssigning` | `{}` | No | AWS credentials for signing requests. Required if `aws_kms` is provided. | Two claims will always be included in the issued JWT: `iat` and `exp`. Any other claims will be populated from the `additional_claims` map. {{< info >}} For using `services[].credentials.oauth2.awskms`, a method for setting the AWS credentials has to be specified in the `services[].credentials.oauth2.awssigning`. The value of `services[].credentials.oauth2.awssigning.service` should be `kms`. Several methods of obtaining the necessary credentials are available; exactly one must be specified, see description for `services[].credentials.s3signing`. {{< /info >}} The following is an example of using the client credentials grant type with JWT client authentication replacing client secret as the credential used at the token endpoint. ```yaml services: remote: url: ${BUNDLESERVICEURL} credentials: oauth2: tokenurl: ${TOKENURL} granttype: clientcredentials client_id: opa-client signingkey: jwtsigning_key # references the key in `keys` below includejticlaim: 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: jwtsigningkey: algorithm: ES512 privatekey: ${BUNDLESERVICESIGNINGKEY} ``` The following is an example of using the client credentials grant type with JWT client authentication & AWS KMS signing of client assertions. ```yaml services: remote: url: ${BUNDLESERVICEURL} credentials: oauth2: tokenurl: ${TOKENURL} granttype: clientcredentials client_id: opa-client aws_kms: name: ${AWSKMSKEYID} algorithm: ECDSASHA256 awssigning: # similar to s3signing service: kms environment_credentials: awsdefaultregion: eu-west-1 includejticlaim: true scopes: read write additional_claims: sub: opa-client iss: opa-${POD_NAME} bundles: authz: service: remote resource: bundles/http/example/authz.tar.gz ``` OPA will authenticate using a bearer token obtained through the OAuth2 flow. Rather than providing a client secret along with the request for an access token, the client 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 , only the HTTPS scheme is supported for the token endpoint URL. | Field | Type | Required | Description | | | | | | | `services[].credentials.oauth2.tokenurl` | `string` | Yes | URL pointing to the token endpoint at the OAuth2 authorization server. | | `services[].credentials.oauth2.granttype` | `string` | No | Must be set to `jwtbearer` for JWT bearer grant type. Defaults to `clientcredentials`. | | `services[].credentials.oauth2.signingkey` | `string` | Yes | Reference to private key used for signing the JWT. | | `services[].credentials.oauth2.additionalclaims` | `map` | No | Map of claims to include in the JWT (see notes below) | | `services[].credentials.oauth2.includejti_claim` | `bool` | No | Include a uniquely generated `jti` claim in any issued JWT | | `services[_].credentials.oauth2.scopes` | `[]string` | No | Optional list of scopes to request for the token. | Two claims will always be included in the issued JWT: `iat` and `exp`. Any other claims will be populated from the `additional_claims` map. The following is an example of using a [Google Cloud Storage](https://cloud.google.com/storage/) bucket as a bundle service backend from outside the cloud account (for access from inside the account, see the [GCP Metadata Token](#gcp-metadata-token) section). ```yaml services: gcp: url: https://storage.googleapis.com/storage/v1/b/${BUCKET_NAME}/o credentials: oauth2: token_url: https://oauth2.googleapis.com/token granttype: jwtbearer signingkey: jwtsigning_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:

keys: jwtsigningkey: algorithm: RS256 privatekey: ${BUNDLESERVICESIGNINGKEY} ``` {{< danger >}} OPA masks services authentication secrets which make use of the `credentials` field, in order to prevent the exposure of sensitive tokens. It is important to note that the allows clients to read the runtime configuration of OPA. As such, any credentials used by custom configurations not utilizing the credentials field will be exposed to the caller. Consider requiring authentication in order to prevent unauthorized read access to OPA's runtime configuration. {{< /danger >}} OPA will authenticate with an or version 4A signature. While version 4 is the default, version 4A must be used when making requests that might be handled by more than one region, such as an . You must use version 4A for this or requests will fail when routed to a different region than the one indicated in a version 4 signature. Furthermore, using version 4a also requires that temporary credentials are retrieved from a , rather than the global STS endpoint. 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`. The AWS signature version to sign the request with can be specified in the `signature_version` field. If omitted, the default is `4`. The only other valid value is `4a`. | Field | Type | Required | Description | |--| | |--| | `services[].credentials.s3signing.service` | `string` | No | The AWS service to sign requests with, eg `execute-api` or `s3`. Default: `s3` | | `services[].credentials.s3signing.signature_version` | `string` | No | The AWS signature version to sign requests with, eg `4` or `4a`. Default: `4` | If specifying `environment_credentials`, OPA will expect to find environment variables for `AWSACCESSKEYID`, `AWSSECRETACCESSKEY` and `AWS_REGION`, in accordance with the convention used by the . Please note that if you are using temporary IAM credentials (e.g. assumed IAM role credentials) you have to provide additional `AWSSESSIONTOKEN` or `AWSSECURITYTOKEN` environment variable. | Field | Type | Required | Description | | | | | | | `services[].credentials.s3signing.environment_credentials` | `{}` | Yes | Enables AWS signing using environment variables to source the configuration and credentials | If specifying `profile_credentials`, OPA will expect to find the `access key id`, `secret access key` and `session token` from the stored in the file on disk. On each request OPA will re-read the credentials from the file and use them for authentication. | Field | Type | Required | Description | | | | | | | `services[].credentials.s3signing.profilecredentials.path` | `string` | No | The path to the shared credentials file. If empty, OPA will look for the `AWSSHAREDCREDENTIALSFILE` env variable. If the variable is not set, the path defaults to the current user's home directory. `~/.aws/credentials` (Linux & Mac) or `%USERPROFILE%\.aws\credentials` (Windows) | | `services[].credentials.s3signing.profilecredentials.profile` | `string` | No | AWS Profile to extract credentials from the credentials file. If empty, OPA will look for the `AWSPROFILE` env variable. If the variable is not set, the `default` profile will be used | | `services[].credentials.s3signing.profilecredentials.awsregion` | `string` | No | The AWS region to use for the AWS signing service credential method. If unset, the `AWS_REGION` environment variable must be set | If specifying `metadata_credentials`, OPA will use the AWS metadata services for or to obtain the necessary credentials when running within a supported virtual

To use the EC2 metadata service, the IAM role to use and the AWS region for the resource must both be specified as `iamrole` and `awsregion` 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. | Field | Type | Required | Description | | | | | | | `services[].credentials.s3signing.metadatacredentials.awsregion` | `string` | No | The AWS region to use for the AWS signing service credential method. If unset, the `AWS_REGION` environment variable must be set | | `services[].credentials.s3signing.metadatacredentials.iamrole` | `string` | No | The IAM role to use for the AWS signing service credential method | If specifying `assumerolecredentials`, OPA will use to obtain temporary security credentials for accessing AWS resources. In order to retrieve temporary security credentials from STS via valid AWS security credentials are required. {{< info >}} For using `services[].credentials.s3signing.assumerolecredentials`, a method for setting the AWS credentials has to be specified in the `services[].credentials.s3signing.assumerolecredentials.aws_signing`. The value of `services[].credentials.s3signing.assumerolecredentials.aws_signing.service` is set to `sts`. Several methods of obtaining the necessary credentials are available; exactly one must be specified, see description for `services[].credentials.s3signing`. Currently supported methods are `services[].credentials.s3signing.environmentcredentials`, `services[].credentials.s3signing.profilecredentials` and `services[].credentials.s3signing.metadata_credentials`. OPA will follow this internally defined order of precedence when multiple credential providers are specified. {{< /info >}} | Field | Type | Required | Description | |-| | -- | | | `services[].credentials.s3signing.assumerolecredentials.aws_region` | `string` | Yes | The AWS region to use for the sts regional endpoint. Uses the global endpoint by default | | `services[].credentials.s3signing.assumerolecredentials.iamrolearn` | `string` | Yes | The IAM Role ARN to be assumed. Can also be set via the `AWSROLEARN` environment variable (config takes precedence) | | `services[].credentials.s3signing.assumerolecredentials.aws_signing` | `{}` | Yes | AWS credentials for signing requests. | | `services[].credentials.s3signing.assumerolecredentials.session_name` | `string` | No | The session name used to identify the assumed role session. Default: `open-policy-agent` | | `services[].credentials.s3signing.assumerolecredentials.awsdomain` | `string` | No | The AWS domain name to use. Default: `amazonaws.com`. Can also be set via the `AWSDOMAIN` environment variable (config takes precedence) | The following is an example using Assume Role Credentials type with EC2 Metadata Credentials signing plugin: ```yaml services: remote: url: ${BUNDLESERVICEURL} credentials: assumerolecredentials: aws_region: us-east-1 iamrolearn: arn:aws::iam::123456789012:role/demo session_name: demo awssigning: # similar to s3signing metadata_credentials: aws_region: us-east-1 iam_role: s3access bundles: authz: service: remote resource: bundles/http/example/authz.tar.gz ``` If specifying `webidentitycredentials`, OPA will expect to find environment variables for `AWSROLEARN` and `AWSWEBIDENTITYTOKENFILE`, in accordance with the convention used by the . | Field | Type | Required | Description | | | | | | | `services[].credentials.s3signing.webidentitycredentials.aws_region` | `string` | Yes | The AWS region to use for the sts regional endpoint. Uses the global endpoint by default | | `services[].credentials.s3signing.webidentitycredentials.session_name` | `string` | No | The session name used to identify the assumed role session. Default: `open-policy-agent` | | `services[].credentials.s3signing.webidentitycredentials.awsdomain` | `string` | No | The AWS domain name to use. Default:

Can also be set via the `AWSDOMAIN` environment variable (config takes precedence) | OPA will authenticate with a GCP or fetched from the . 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 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. | Field | Type | Required | Description | | | | | | |`services[].credentials.gcpmetadata.audience`|`string`|No|The audience to use when fetching identity tokens.| |`services[].credentials.gcpmetadata.endpoint`|`string`|No|The metadata endpoint to use.| |`services[].credentials.gcpmetadata.scopes`|`array`|No|The set of scopes to use when fetching access token.| |`services[].credentials.gcpmetadata.accesstokenpath`|`string`|No|The access token metadata path to use.| |`services[].credentials.gcpmetadata.idtokenpath`|`string`|No|The identity token metadata path to use.| The following is an example using a service as a bundle service backend. ```yaml services: cloudrun: url: ${BUNDLESERVICEURL} responseheadertimeout_seconds: 5 credentials: gcp_metadata: audience: ${BUNDLESERVICEURL} bundles: authz: service: cloudrun resource: bundles/http/example/authz.tar.gz persist: true polling: mindelayseconds: 60 maxdelayseconds: 120 ``` Using as a bundle service backend. ```yaml services: gcs: url: https://storage.googleapis.com/storage/v1/b/${BUCKET_NAME}/o responseheadertimeout_seconds: 5 credentials: gcp_metadata: scopes: "https://www.googleapis.com/auth/devstorage.read_only" bundles: authz: service: gcs resource: 'bundles%2fhttp%2fexample%2fbundle.tar.gz?alt=media' persist: true polling: mindelayseconds: 60 maxdelayseconds: 120 ``` When the given resource (the object in the GCS bucket) contains slashes (/) or other special characters, these need to be url-encoded here. OPA will authenticate with an token. The 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. | Field | Type | Required | Description | | | | | | | `services[].credentials.azuremanaged_identity.endpoint` | `string` | No | Request endpoint. (default: `http://169.254.169.254/metadata/identity/oauth2/token`, the Azure Instance Metadata Service endpoint (recommended))| | `services[].credentials.azuremanagedidentity.apiversion` | `string` | No | API version to use. (default: `2018-02-01`, the minimum version) | | `services[].credentials.azuremanaged_identity.resource` | `string` | No | App ID URI of the target resource. (default: `https://storage.azure.com/`) | | `services[].credentials.azuremanagedidentity.objectid` | `string` | No | Optional object ID of the managed identity you would like the token for. Required, if your VM has multiple user-assigned managed identities. | | `services[].credentials.azuremanagedidentity.clientid` | `string` | No | Optional client ID of the managed identity you would like the token for. Required, if your VM has multiple user-assigned managed identities. | | `services[].credentials.azuremanagedidentity.mires_id` | `string` | No | Optional Azure Resource ID of the managed identity you would like the token for. Required, if your VM has multiple user-assigned managed identities. | The following is an example of how to use an [Azure storage account](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-overview) 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](https://docs.microsoft.com/en-us/rest/api/storageservices/authorize-with-azure-active-directory#call-storage-operations-with-oauth-tokens). ```yaml services: azurestorageaccount: url: ${STORAGEACCOUNTURL} headers: x-ms-version: 2017-11-09 responseheadertimeout_seconds: 5 credentials: azuremanagedidentity: {} bundles: authz: service: azurestorageaccount resource: bundles/http/example/authz.tar.gz persist: true polling: mindelayseconds: 60 maxdelayseconds: 120 ``` When using a private image from an OCI registry you need to specify an authentication method. Supported authentication methods are listed in the section. The Azure managed identity plugin is not supported at this point in time. Examples of setting credentials for pulling private images: AWS ECR private images usually require at least basic

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: ```yaml credentials: bearer: scheme: "Basic" token: "<username>:<password>" ``` Other AWS authentication methods also work: ```yaml credentials: s3_signing: service: "ecr" metadata_credentials: aws_region: us-east-1 ``` Note, that the authentication method `s3_signing` does work for signing requests to other AWS services. A special case is that bearer authentication works differently to normal service authentication. The OCI downloader base64-encodes the credentials for you so that they need to be supplied in plain text. For GHCR (Github Container Registry) you can use a developer PAT (personal access token) when downloading a private image. These can be supplied as: ```yaml credentials: bearer: scheme: "Bearer" token: "<PAT>" ``` The following is a complete exmaple using an OCI service type to download a bundle from an OCI repository. ```yaml services: ghcr-registry: url: https://ghcr.io type: oci bundles: authz: service: ghcr-registry resource: ghcr.io/${ORGANIZATION}/${REPOSITORY}:${TAG} persist: true polling: mindelayseconds: 60 maxdelayseconds: 120 persistencedirectory: ${PERSISTENCEPATH} ``` 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. If none of the existing credential options work for a service, OPA can authenticate using a custom plugin, enabling support for any authentication scheme. | Field | Type | Required | Description | | | | | | |`services[_].credentials.plugin`|`string`|No|The name of the plugin to use for authentication| The following is an example of using a custom plugin for service credentials: ```yaml services: my_service: url: https://example.com/v1 credentials: plugin: mycustomauth plugins: mycustomauth: foo: bar ``` ```go 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("mycustomauth", &PluginFactory{}) } ``` 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 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

| Field | Type | Required | Description | | | | | | | `bundles[_].resource` | `string` | No (default: `bundles/<name>`) | Resource path to use to download bundle from configured service. | | `bundles[_].service` | `string` | Yes | Name of service to use to contact remote server. | | `bundles[].polling.mindelay_seconds` | `int64` | No (default: `60`) | Minimum amount of time to wait between bundle downloads. | | `bundles[].polling.maxdelay_seconds` | `int64` | No (default: `120`) | Maximum amount of time to wait between bundle downloads. | | `bundles[_].trigger` | `string` (default: `periodic`) | No | Controls how bundle is downloaded from the remote server. Allowed values are `periodic` and `manual` (`manual` triggers are only possible when using OPA as a Go package). | | `bundles[].polling.longpollingtimeoutseconds` | `int64` | No | Maximum amount of time the server should wait before issuing a timeout if there's no update available. | | `bundles[_].persist` | `bool` | No | Persist activated bundles to disk. | | `bundles[_].signing.keyid` | `string` | No | Name of the key to use for bundle signature verification. | | `bundles[_].signing.scope` | `string` | No | Scope to use for bundle signature verification. | | `bundles[].signing.excludefiles` | `array` | No | Files in the bundle to exclude during verification. | | `bundles[].sizelimit_bytes` | `int64` | No (default: `1073741824`) | Size limit for individual files contained in the bundle. | | Field | Type | Required | Description | | | | | | | `status.service` | `string` | Yes | Name of service to use to contact remote server. | | `status.partition_name` | `string` | No | Path segment to include in status updates. | | `status.console` | `boolean` | No (default: `false`) | Log the status updates locally to the console. When enabled alongside a remote status update API the `service` must be configured, the default `service` selection will be disabled. | | `status.prometheus` | `boolean` | No (default: `false`) | Export the status (bundle and plugin) metrics to prometheus (see ). When enabled alongside a remote status update API the `service` must be configured, the default `service` selection will be disabled. | | `status.plugin` | `string` | No | Use the named plugin for status updates. If this field exists, the other configuration fields are not required. | | `status.trigger` | `string` (default: `periodic`) | No | Controls how status updates are reported to the remote server. Allowed values are `periodic` and `manual` (`manual` triggers are only possible when using OPA as a Go package). | | Field | Type | Required | Description | | | | | | | `decision_logs.service` | `string` | No | Name of the service to use to contact remote server. If no `plugin` is specified, and `console` logging is disabled, this will default to the first `service` name defined in the Services configuration. | | `decisionlogs.partitionname` | `string` | No | Deprecated: Use `resource` instead. Path segment to include in status updates. | | `decision_logs.resource` | `string` | No (default: `/logs`) | Full path to use for sending decision logs to a remote server. | | `decisionlogs.reporting.buffersizelimitbytes` | `int64` | No | Decision log buffer size limit in bytes. OPA will drop old events from the log if this limit is exceeded. By default, no limit is set. Only one of `buffersizelimitbytes`, `maxdecisionspersecond` may be set. | |

| `float64` | No | Maximum number of decision log events to buffer per second. OPA will drop events if the rate limit is exceeded. Only one of `buffersizelimitbytes`, `maxdecisionspersecond` may be set. | | `decisionlogs.reporting.uploadsizelimitbytes` | `int64` | No (default: `32768`) | Decision log upload size limit in bytes. OPA will chunk uploads to cap message body to this limit. | | `decisionlogs.reporting.mindelay_seconds` | `int64` | No (default: `300`) | Minimum amount of time to wait between uploads. | | `decisionlogs.reporting.maxdelay_seconds` | `int64` | No (default: `600`) | Maximum amount of time to wait between uploads. | | `decision_logs.reporting.trigger` | `string` | No (default: `periodic`) | Controls how decision logs are reported to the remote server. Allowed values are `periodic` and `manual` (`manual` triggers are only possible when using OPA as a Go package). | | `decisionlogs.maskdecision` | `string` | No (default: `/system/log/mask`) | Set path of masking decision. | | `decisionlogs.dropdecision` | `string` | No (default: `/system/log/drop`) | Set path of drop decision. | | `decision_logs.plugin` | `string` | No | Use the named plugin for decision logging. If this field exists, the other configuration fields are not required. | | `decision_logs.console` | `boolean` | No (default: `false`) | Log the decisions locally to the console. When enabled alongside a remote decision logging API the `service` must be configured, the default `service` selection will be disabled. | | Field | Type | Required | Description | | | | |-| | `discovery.resource` | `string` | Yes | Resource path to use to download bundle from configured service. | | `discovery.service` | `string` | No | Name of the service to use to contact remote server. If omitted, the configuration must contain exactly one service. Discovery will default to this service. | | `discovery.decision` | `string` | No | The path of the decision to evaluate in the discovery bundle. By default, OPA will evaluate `data` in the discovery bundle to produce the configuration. | | `discovery.polling.mindelayseconds` | `int64` | No (default: `60`) | Minimum amount of time to wait between configuration downloads. | | `discovery.polling.maxdelayseconds` | `int64` | No (default: `120`) | Maximum amount of time to wait between configuration downloads. | | `discovery.trigger` | `string` (default: `periodic`) | No | Controls how bundle is downloaded from the remote server. Allowed values are `periodic` and `manual` (`manual` triggers are only possible when using OPA as a Go package). | | `discovery.polling.longpollingtimeout_seconds` | `int64` | No | Maximum amount of time the server should wait before issuing a timeout if there's no update available. | | `discovery.signing.keyid` | `string` | No | Name of the key to use for bundle signature verification. | | `discovery.signing.scope` | `string` | No | Scope to use for bundle signature verification. | | `discovery.signing.exclude_files` | `array` | No | Files in the bundle to exclude during verification. | | `discovery.persist` | `bool` | No | Persist activated discovery bundle to disk. | 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

The following `discovery` configuration fields are supported but deprecated: | Field | Type | Required | Description | | | | | | | `discovery.prefix` | `string` | No (default: `bundles`) | Deprecated: Use `resource` instead. Path prefix to use to download configuration from remote server. | | `discovery.name` | `string` | No | Deprecated: Use `resource` instead. Name of the discovery configuration to download. If `discovery.name` is specified and `discovery.resource` is unset, the `discovery.decision` field will default to the `discovery.name` value. | Keys is a dictionary mapping the key name to the actual key and optionally the algorithm and scope. | Field | Type | Required | Description | | | | | | | `keys[].key` | `string` | Yes (unless `privatekey` provided) | PEM encoded public key to use for signature verification. | | `keys[].privatekey` | `string` | Yes (unless `key` provided`) | PEM encoded private key to use for signing. | | `keys[_].algorithm` | `string` | No (default: `RS256`) | Name of the signing algorithm. | | `keys[_].scope` | `string` | No | Scope to use for bundle signature verification. | 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: | Name | Description | | | | | `ES256` | ECDSA using P-256 and SHA-256 | | `ES384` | ECDSA using P-384 and SHA-384 | | `ES512` | ECDSA using P-521 and SHA-512 | | `HS256` | HMAC using SHA-256 | | `HS384` | HMAC using SHA-384 | | `HS512` | HMAC using SHA-512 | | `PS256` | RSASSA-PSS using SHA256 and MGF1-SHA256 | | `PS384` | RSASSA-PSS using SHA384 and MGF1-SHA384 | | `PS512` | RSASSA-PSS using SHA512 and MGF1-SHA512 | | `RS256` | RSASSA-PKCS-v1.5 using SHA-256 | | `RS384` | RSASSA-PKCS-v1.5 using SHA-384 | | `RS512` | RSASSA-PKCS-v1.5 using SHA-512 | Caching represents the configuration of the inter-query cache that built-in functions can utilize. | Field | Type | Required | Description | | | | | | | `caching.interquerybuiltincache.maxsize_bytes` | `int64` | No | Inter-query cache size limit in bytes. OPA will drop old items from the cache if this limit is exceeded. By default, no limit is set. | | `caching.interquerybuiltincache.forcedevictionthresholdpercentage` | `int64` | No | Threshold limit configured as percentage of `caching.interquerybuiltincache.maxsize_bytes`, when exceeded OPA will start dropping old items permaturely. By default, set to `100`. | | `caching.interquerybuiltincache.staleentryevictionperiodseconds` | `int64` | No | Stale entry eviction period in seconds. OPA will drop expired items from the cache every `staleentryevictionperiod_seconds`. By default, set to `0` indicating stale entry eviction is disabled. | Distributed tracing represents the configuration of the OpenTelemetry Tracing. | Field | Type | Required | Description | | | | | | | `distributed_tracing.type` | `string` | No | Setting this to "grpc" enables distributed tracing with an collector gRPC endpoint | | `distributed_tracing.address` | `string` | No (default: `localhost:4317`) | Address of the OpenTelemetry Collector gRPC endpoint. | | `distributedtracing.servicename` | `string` | No (default: `opa`) | Logical name of the service. | | `distributedtracing.samplepercentage` | `int` | No (default: `100`) | Percentage of traces that are sampled and exported. | | `distributed_tracing.encryption` | `string` | No (default: `off`) | Configures TLS. | | `distributedtracing.allowinsecure_tls` | `bool` | No (default: `false`) | Allow insecure TLS. | | `distributedtracing.tlscacertfile` | `string` | No | The path to the root CA

| | `distributedtracing.tlscert_file` | `string` | No (unless `encryption` equals `mtls`) | The path to the client certificate to authenticate with. | | `distributedtracing.tlsprivatekeyfile` | `string` | No (unless `tlscertfile` provided) | The path to the private key of the client certificate. | The following encryption methods are supported: | Name | Description | | | | | `off` | Disable TLS | | `tls` | Enable TLS | | `mtls` | Enable mutual TLS | 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`. | Field | Type | Required | Description | | | | | | | `storage.disk.directory` | `string` | Yes | This is the directory to use for storing the persistent database. | | `storage.disk.auto_create` | `bool` | No (default: `false`) | If set to true, the configured directory will be created if it does not exist. | | `storage.disk.partitions` | `array[string]` | No | Non-overlapping `data` prefixes used for partitioning the data on disk. | | `storage.disk.badger` | `string` | No (default: empty) | "Superflags" passed to Badger allowing to modify advanced options. | See for details about the settings. The `server` configuration sets: the gzip compression settings for `/v0/data`, `/v1/data` and `/v1/compile` HTTP `POST` endpoints The gzip compression settings are used when the client sends `Accept-Encoding: gzip` buckets for `httprequestduration_seconds` histogram | Field | Type | Required | Description | |-|-||| | `server.encoding.gzip.min_length` | `int` | No, (default: 1024) | Specifies the minimum length of the response to compress | | `server.encoding.gzip.compression_level` | `int` | No, (default: 9) | Specifies the compression level. Accepted values: a value of either 0 (no compression), 1 (best speed, lowest compression) or 9 (slowest, best compression). See https://pkg.go.dev/compress/flate#pkg-constants | | `server.metrics.prom.httprequestdurationseconds.buckets` | `[]float64` | No, (default: [1e-6, 5e-6, 1e-5, 5e-5, 1e-4, 5e-4, 1e-3, 0.01, 0.1, 1 ]) | Specifies the buckets for the `httprequestdurationseconds` metric. Each value is a float, it is expressed in seconds and subdivisions of it. E.g `1e-6` is 1 microsecond, `1e-3` 1 millisecond, `0.01` 10 milliseconds | | Field | Type | Required | Description | | | | | | | `labels` | `object` | Yes | Set of key-value pairs that uniquely identify the OPA instance. Labels are included when OPA uploads decision logs and status information. | | `default_decision` | `string` | No (default: `/system/main`) | Set path of default policy decision used to serve queries against OPA's base URL. | | `defaultauthorizationdecision` | `string` | No (default: `/system/authz/allow`) | Set path of default authorization decision for OPA's API. | | `persistencedirectory` | `string` | No (default `$PWD/.opa`) | Set directory to use for persistence with options like `bundles[].persist`. | | `plugins` | `object` | No (default: `{}`) | Location for custom plugin configuration. See for details. | | `ndbuiltincache` | `boolean` | No (default: `false`) | Enable the non-deterministic builtins caching system during policy evaluation, and include the contents of the cache in decision logs. Note that decision logs that are larger than `uploadsizelimitbytes` will drop the `ndbuiltin_cache` key from the log entry before uploading. | 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 `BASEURL` and `BEARERTOKEN` environment variables: ```yaml services: acmecorp: url: "${BASE_URL}" credentials: bearer: token: "${BEARER_TOKEN}" discovery: resource: /configuration/example/discovery decision: example ``` The environment variables `BASEURL` and `BEARERTOKEN` 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. 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: `decisionlogs.reporting.mindelay_seconds=300` is equivalent to JSON `{"decisionlogs": {"reporting": {"mindelay_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: ```yaml 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 ```bash 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. 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: ```yaml 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: ```yaml 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. When running the server to quickly try a remote public bundle such as those published from the , you may find it convenient to provide the URL of the bundle directly, rather than via repeated `--set` flags: ```shell opa run -s https://example.com/bundles/bundle.tar.gz ``` The above shorthand command is identical to: ```shell opa run -s --set "services.cli1.url=https://example.com" \ --set "bundles.cli1.service=cli1" \ --set "bundles.cli1.resource=/bundles/bundle.tar.gz" \ --set "bundles.cli1.persist=true" ``` If you need to set an empty object with the CLI overrides, for example with plugin configuration like: ```yaml decision_logs: plugin: my_plugin plugins: my_plugin: ``` You can do this by setting the value with `null`. For example: ``` opa run --set "decisionlogs.plugin=myplugin" --set "plugins.my_plugin=null" ``` 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: ```yaml 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.