Project: Topaz (Provisioning / Security & Compliance)
File: config.md

The main configuration for Topaz can be divided in 3 main sections: Common configuration Auth configuration - optional Decision logger configuration - optional Controller configuration - optional The topaz service configuration uses the library, which allows all configuration parameters to be passed to the `topazd` service as environment variables with the `TOPAZ_` prefix. If you use topaz CLI to generate your configuration file by default it will add the TOPAZ_DIR environment variable to the path configurations. By default this is empty and considered an NOP addition, but it can easily allow you to specify the desired value to the run/start topaz CLI command with the `-e` flag. By default if you run/start the topaz container using the topaz CLI the following environment variables will be set in your topaz container: `TOPAZCERTSDIR` - default $HOME/.config/topaz/certs - the directory where topaz will load/generate the certs `TOPAZCFGDIR` - default $HOME/.config/topaz/cfg - the directory from where topaz will load the configuration file `TOPAZDBDIR` - default $HOME/.config/topaz/db - the directory where topaz will store the edge directory DB `TOPAZCERTSDIR` - default $HOME/.config/topaz/certs - the directory where topaz will load/generate the certs `TOPAZCFGDIR` - default $HOME/.config/topaz/cfg - the directory from where topaz will load the configuration file `TOPAZDBDIR` - default $HOME/.config/topaz/db - the directory where topaz will store the edge directory DB Both run and start topaz CLI commands allow passing optional environment variables to your running container using the -e flag. This will allow you to use any desired environment variable in your configuration file as long as you pass it to the container. The configuration version accepted by the version of topaz - current compatible version: 2 The for topaz is based on and has the following available settings: prod - boolean - if set to false the entire log output will be written using a zerolog ConsoleWriter, setting this to true will write the errors to the stderr output and other logs to the stdout log_level - string - this value is parsed by zerolog to match desired logging level (default: info), available levels: trace, debug, info, warn, error, fatal and panic grpc_log_level - string - same as above available values, however this is specific for the logged grpc messages, having the default value set to warn ``` logging: prod: true log_level: debug ``` The API section is defines the configuration for the health, metrics and services that topaz is able to spin up. The health configuration allows topaz to spin up a health server. listen_address - string - allows the health service to spin up on the configured port (default: "0.0.0.0:9494") certs - certs.TLSCredsConfig - based on package allows setting the paths of your certificate files. By default the certificates are not configured. The metrics configuration allows topaz to spin up a metric server. listen_address - string - allows the metric service to spin up on the configured port (default: "0.0.0.0:9696") certs - certs.TLSCredsConfig - based on package allows setting the paths of your certificate files. By default the certificates are not

zpages - bool - if enabled the metrics server will enable on the "/debug" route The grpc section allows configuring the listen address, the connection timeout and the certificates. fqdn - string - optional value to set the fully qualified domain name for the service endpoint listen_address - string - allows the topaz GRPC server to spin up on the requested port (default: "0.0.0.0:8282") connection_timeout_seconds - uint32 - sets the timeout for a (default: 120) certs - certs.TLSCredsConfig - based on package allows setting the paths of your certificate files. If you do not have your certificates in the specified paths, topaz will generate self-signed certificates for you. By default topaz will generate the certificates in ` ~/.config/topaz/certs/` path Example: ``` grpc: listen_address: "localhost:8282" connectiontimeoutseconds: 160 certs: tlscertpath: "/app/grpc.crt" tlskeypath: "/app/grpc.key" tlscacert_path: "/app/grpc-ca.crt" ``` The gateway section allows configuring the for your topaz authorizer. fqdn - string - optional value to set the fully qualified domain name for the service endpoint listen_address - string - allows the topaz Gateway server to spin up on the requested port (default: "0.0.0.0:8383") http - boolean - when set to true it allows the gateway service to respond to plain http request (default: false) certs - certs.TLSCredsConfig - based on package allows setting the paths of your certificate files. If you do not have your certificates in the specified paths, topaz will generate self-signed certificates for you. By default topaz will generate the certificates in ` ~/.config/topaz/certs/` path allowed_origins - Detailed information about the gateway http server timeout configuration is available read_timeout - time.Duration - default value set to 2 * time.Second (default: 2000000000) read_header_timeout - time.Duration - default value set to 2 * time.Second (default: 2000000000) write_timeout - time.Duration - default value set to 2 * time.Second (default: 2000000000) idle_timeout - time.Duration - default is set to 30 * time.Second (default: 30000000000) Example: ``` gateway: listen_address: "localhost:8383" http: false fqdn: "https://mygateway.demo.org" certs: tlscertpath: "/app/gateway.crt" tlskeypath: "/app/gateway.key" tlscacert_path: "/app/gateway-ca.crt" allowed_origins: https://*.aserto.com https://*aserto-console.netlify.app https://*aserto-playground.netlify.app ``` The `needs` section allows adding a dependency between the services started. For example when using an edge directory with a reader service it is recommended to set the authorizer services to be dependent on the reader spin-up to be able to resolve the identity for the authorization calls. Example: ``` api: reader: gateway: listen_address: localhost:9393 grpc: listen_address: localhost:9595 authorizer: needs: reader gateway: allowed_origins: https://*.aserto.com https://*aserto-console.netlify.app https://*aserto-playground.netlify.app grpc: connectiontimeoutseconds: 2 ``` The directory section allows setting the configuration for the topaz . db_path - string - path to the bbolt database file request_timeout - time.Duration - request timeout setting for the bbolt database connection enable_v2 - boolean - enable directory version 2 services for backward compatibility (default: false) Topaz is able to communicate with a directory service based on the definitions. When the remote address is configured to localhost, topaz is able to spin-up a grpc based on The remote address can also be configured to a service that implements the proto definitions (for example, the Postgres-based Aserto directory

In this case, Topaz will NOT spin-up a local edge directory service, and instead send all directory requests to this remote service. address - string - address:port of the remote directory service api_key - string - API key for the directory tenant_id - string - the directory tenant ID Example (using the hosted Aserto directory): ``` remote_directory: address: "directory.prod.aserto.com:8443" api_key: <Your Aserto Directory Access Key> tenant_id: <Your Aserto Tenant ID> ``` The OPA configuration section represent the . The main elements of the runtime configuration are: local_bundles - runtime.LocalBundlesConfig - allows the runtime to run with a local bundle (local path or local policy OCI image) instance_id - string - represent the unique identifier of the runtime plugins_error_limit - int - represents the maximum number of errors that an OPA plugin can trigger before killing the runtime graceful_shutdown_period_seconds - int - passed to the runtime plugin manager, this represents the allowed time to stop the running plugins gracefully max_plugin_wait_time_seconds - int - passed to the runtime plugin manager, this represents the maximum wait time for a plugin to spin-up (default: 30) flags - runtime.Flags - currently only the boolean enable_status_plugin is available. When set to true the runtime status is affected by the OPA status plugin config - runtime.OPAConfig - the details of the For more details regarding the OPA configuration see The JWT section allows setting a custom acceptable_time_skew_seconds - int - this specifies the duration in which exp (Expiry) and nbf (Not Before) claims may differ by (default: 5). By default Topaz authentication configuration is disabled, however if you want to configure API key basic authentication this section of the configuration allows you to set this up. The options section allows you to specify overrides for specific paths if you want to enable the api key authentication or/and the anonymous authentication for these. Example: ``` auth: api_keys: dc8a1524dec311eda1ff8bd042196110: myuser@email.com options: default: enableapikey: true enable_anonymous: false overrides: paths: /aserto.authorizer.v2.Authorizer/Info override: enable_anonymous: true enableapikey: false ``` By default Topaz does not initiate a decision logger, however if you need to keep a history of the decisions taken by the IS API call a rolling logger based on is available to keep decision logs in a file. Example configuration: ``` decision_logger: type: "file" config: logfilepath: /tmp/mytopaz.log maxfilesize_mb: 50 maxfilecount: 2 ``` To use the decision logger the OPA configuration must contain the for the decision log plugin. Example of the decision log plugin configuration: ``` opa: instance_id: "-" gracefulshutdownperiod_seconds: 2 local_bundles: paths: [] skip_verification: true config: plugins: asertodecisionlog: enabled: true policy_info: registry_service: 'ghcr.io' registry_image: 'aserto-policies/policy-peoplefinder-rbac' digest: 'b36c9fac3c4f3a20e524ef4eca4ac3170e30281fe003b80a499591043299c898' ``` When deploying topaz as an you can configure the decision logger to send the logs to the upstream Aserto policy instance. For configuration details see: https://docs.aserto.com/docs/edge-authorizers/decision-logs The controller allows an edge Topaz authorizer to connect to the Aserto Control Plane through a secure mTLS connection. This way the edge authorizers can sync their running policy with an upstream policy instance and sync their local directory with a remote directory. For more details on the security and management of edge authorizers see documentation available . ``` controller: enabled: true server: address: relay.prod.aserto.com:8443 clientcertpath: <path to client certificate> clientkeypath: <path to client key> ```