Configuration

Setting Configuration Values

Fides can be configured in two different ways: either via a toml file or via environment variables. Both methods can be used simultaneously, with environment variables taking precedence over the toml file values.

Using a Configuration File

Fides will use the first config file it can read from the following locations. Listed in order of precedence they are:

At the path specified using the config file argument passed through the CLI, i.e. fides -f <config_path>
At the path specified by the FIDES__CONFIG_PATH environment variable
In the current working directory it will check for a subdir .fides and a file within named fides.toml, i.e. ./.fides/fides.toml

Generating a Config File

If you'd like to generate a new config file automatically using default values, run fides init. This will create the file at the default location of ./.fides/fides.toml

Setting Values Via Environment Variables

Fides follows a set pattern for configuration via environment variables. It looks for environment variables that start with FIDES followed by the config subsection name, followed by the key name, all separated with double underscores. In practice this would look like FIDES__<SUBSECTION>__<KEY>

As a toml configuration value:

[database]
host = config_example

As an environment variable:

EXPORT FIDES__DATABASE__HOST=config_example

Viewing your configuration

You can view the current configuration of your application via either the CLI or API.

CLI

To view your application configuration via the CLI, run:

fides view config

This will show all configuration variables, including sensitive ones. It is printed to the console as valid toml, so this can be copy/pasted as needed.

API

To view your application configuration in the API, run:

GET /api/v1/config

For security reasons, sensitive configuration values will not be shown here.

Fides Configuration Variable Reference

Application Database

Environment variable prefix: FIDES__DATABASE__

Name	Type	Default	Description
`user`	String	`postgres`	The database user with which to login to the application database.
`password`	String	`fides`	The password with which to login to the application database.
`server`	String	`fides-db`	The hostname of the Postgres database server.
`port`	String	`5432`	The port at which the Postgres database will be accessible.
`db`	String	`fides`	The name of the Postgres database.
`test_db`	String	`""`	Used instead of the `db` config when the `FIDES_TEST_MODE` environment variable is set to `True`, to avoid overwriting production data.
`load_samples`	bool	`False`	When set to True, initializes the database with sample data for testing.
`params`	bool	`False`	Additional connection parameters used when connecting to the application database.
`automigrate`	bool	`True`	Automatically runs migrations on webserver startup. If set to `false`, will require the user to run migrations manually via the CLI or API. WARNING: Must be set to `true` for first-time startup.
`api_engine_pool_size`	int	`50`	The `pool_size` for the API database Engine.
`api_engine_max_overflow`	int	`50`	The `max_overflow` for the API database Engine.
`api_engine_keepalives_idle`	int	`30`	Number of seconds of inactivity before the client sends a TCP keepalive packet to verify the database connection is still alive.
`api_engine_keepalives_interval`	int	`10`	Number of seconds between TCP keepalive retries if the initial keepalive packet receives no response.
`api_engine_keepalives_count`	int	`5`	Maximum number of TCP keepalive retries before the client considers the connection dead and closes it.
`task_engine_pool_size`	int	`50`	The `pool_size` for the celery task database Engine.
`task_engine_max_overflow`	int	`50`	The `max_overflow` for the celery task database Engine.
`task_engine_keepalives_idle`	int	`30`	Number of seconds of inactivity before the client sends a TCP keepalive packet to verify the database connection is still alive.
`task_engine_keepalives_interval`	int	`10`	Number of seconds between TCP keepalive retries if the initial keepalive packet receives no response.
`task_engine_keepalives_count`	int	`5`	Maximum number of TCP keepalive retries before the client considers the connection dead and closes it.

Redis cache

Environment variable prefix: FIDES__REDIS__

Name	Type	Default	Description
`host`	string	N/A	The network address for the application Redis cache.
`port`	int	`6379`	The port at which the application cache will be accessible.
`user`	string	N/A	The user with which to login to the Redis cache.
`password`	string	N/A	The password with which to login to the Redis cache.
`db_index`	int	N/A	The application will use this index in the Redis cache to cache data.
`connection_url`	string	N/A	A full connection URL to the Redis cache. If not specified, this URL is automatically assembled from the `host`, `port`, `password` and `db_index` specified above.
`default_ttl_seconds`	int	604800	The number of seconds for which data will live in Redis before automatically expiring.
`enabled`	bool	`True`	Whether the application's Redis cache should be enabled. Only set to false for certain narrow uses of the application.
`charset`	string	`utf-8`	The character set to use for encoding data in the Redis cache. Not recommended to change.
`decode_responses`	bool	`True`	Whether or not to automatically decode the values fetched from Redis. Decodes using the `charset` configuration value.
`identity_verification_code_ttl_seconds`	bool	`True`	Sets TTL for cached identity verification code as part of subject requests.
`ssl`	bool	`False`	Whether the application's connections to the cache should be encrypted using TLS.
`ssl_cert_reqs`	string	required	If using TLS encryption, set this to "required" if you wish to enforce the Redis cache to provide a certificate. Note that not all cache providers support this without setting ssl_ca_certs e.g. AWS Elasticache.
`ssl_ca_certs`	string	N/A	If using TLS encryption, rooted with a custom Certificate Authority, set this to the path of the CA certificate

Logging

Environment variable prefix: FIDES__LOGGING__

Name	Type	Default	Description
`destination`	String	`""`	The output location for log files. Accepts any valid file path. If left unset, log entries are printed to `stdout` and log files are not produced.
`colorize`	Boolean	`False`	Force colored logs. Any value set via environment variables is considered 'True'.
`level`	Enum (String)	`INFO`	The minimum log entry level to produce. Also accepts `TRACE`, `DEBUG`, `WARNING`, `ERROR`, or `CRITICAL` (case insensitive).
`serialization`	Enum (String)	`""`	The format with which to produce log entries. If left unset, produces log entries formatted using the internal custom formatter. Also accepts `"JSON"` (case insensitive).
`log_pii`	Boolean	`False`	If `True`, PII values will display unmasked in log output. This variable should always be set to "False" in production systems.

CLI

Environment variable prefix: FIDES__CLI__

Name	Type	Default	Description
`analytics_id`	String	`""`	A fully anonymized unique identifier that is automatically generated by the application and stored in the toml file.
`local_mode`	Boolean	`False`	When set to `True`, forbids the Fides CLI from making calls to the Fides webserver.
`server_host`	String	`localhost`	The hostname of the Fides webserver.
`server_protocol`	String	`http`	The protocol used by the Fides webserver.
`server_port`	Integer	`8080`	The optional port of the Fides webserver.
`server_path`	String	`"/"`	The path of the Fides webserver.
`server_url`	String	`""`	The full server url generated from the other server configuration values.

Security

Environment variable prefix: FIDES__SECURITY__

Name	Type	Default	Description
`app_encryption_key`	string	N/A	The key used to sign Fides API access tokens.
`aes_encryption_key_length`	int	`16`	Length of desired encryption key when using Fides to generate a random secure string used for AES encryption. Length of desired random byte str for the AES GCM encryption used throughout Fides.
`aes_gcm_nonce_length`	int	`12`	Length of desired random byte str for the AES GCM encryption used throughout Fides.
`cors_origins`	List	[]	A list of origins that should be permitted to make cross-origin requests. eg. `['https://example.org', 'https://www.example.org']`. Adding a wildcard CORS origin i.e. `*` to this variable is not supported, but see `cors_origin_regex` variable below for allowing any origin.
`cors_origin_regex`	string	None	A regex string to match against origins that should be permitted to make cross-origin requests. eg. `'https://.\.example\.org'`. To allow any origin, set this variable to `'.'`.
`drp_jwt_secret`	string	N/A	JWT secret by which passed-in identity is decrypted according to the HS256 algorithm.
`dsr_testing_tools_enabled`	bool	`False`	If set to True, contributor and owner roles will be able to run test privacy requests.
`oauth_root_client_id`	string	N/A	The value used to identify the Fides application root API client.
`oauth_root_client_secret`	string	N/A	The secret value used to authenticate the Fides application root API client.
`oauth_access_token_expire_minutes`	int	`11520`	The time for which Fides API tokens will be valid.
`oauth_root_client_secret_hash`	string	N/A	Automatically generated by Fides, and represents a hashed value of the oauth_root_client_secret.
`oauth_client_id_length_bytes`	int	`16`	Sets desired length in bytes of generated client id used for oauth.
`oauth_client_secret_length_bytes`	int	`16`	Sets desired length in bytes of generated client secret used for oauth.
`parent_server_password`	string	N/A	When using a parent/child Fides deployment, this password will be used by the child server to access the parent server.
`parent_server_username`	string	N/A	When using a parent/child Fides deployment, this username will be used by the child server to access the parent server.
`root_username`	string	None	If set, this can be used in conjunction with `root_password` to log in without first creating a user in the database.
`root_password`	string	None	If set, this can be used in conjunction with `root_username` to log in without first creating a user in the database.
`root_user_scopes`	list of strings	All available scopes	The scopes granted to the root user when logging in with `root_username` and `root_password`.
`root_user_roles`	list of strings	Owner	The list of roles that are given to the root user.
`subject_request_download_ui_enabled`	bool	`False`	If set to True, the user interface will display a download button for subject requests.
`subject_request_download_link_ttl_seconds`	int	`432000`	The number of seconds that a pre-signed download URL when using S3 storage will be valid.
`request_rate_limit`	str	`1000/minute`	The number of requests from a single IP address allowed to hit an endpoint within a rolling 60 second period.
`public_request_rate_limit`	str	`2000/minute`	The number of requests from a single IP address allowed to hit a public endpoint within a rolling 60 second period.
`rate_limit_prefix`	str	`fides-`	The prefix given to keys in the Redis cache used by the rate limiter.
`identity_verification_attempt_limit`	int	`3`	The number of identity verification attempts to allow.
`env`	sting	`prod`	This determines which API endpoints require authentication. The default, `prod`, requires authentication for all endpoints that may contain sensitive information. The other option, `dev`, does not apply authentication to endpoints typically used by the CLI.
`encoding`	string	`utf-8`	Text encoding to use for the application.
`enable_audit_log_resource_middleware`	bool	`False`	Either enables the collection of audit log resource data or bypasses the middleware.
`bastion_server_host`	string	`""`	An optional field to store the bastion server host.
`bastion_server_ssh_username`	string	`""`	An optional field to store the username used to access the bastion server.
`bastion_server_ssh_private_key`	string	`""`	An optional field to store the key used to SSH into the bastion server.
`bastion_server_ssh_timeout`	float	`0.1`	The timeout in seconds for the transport socket (`socket.settimeout`).
`bastion_server_ssh_tunnel_timeout`	float	`10`	The timeout in seconds for tunnel connection (open_channel timeout).

Execution

Environment variable prefix: FIDES__EXECUTION__

Name	Type	Default	Description
`privacy_request_delay_timeout`	int	`3600`	The amount of time to wait for actions which delay privacy requests (e.g., pre- and post-processing webhooks).
`task_retry_count`	int	`0`	The number of times a failed request will be retried.
`task_retry_delay`	int	`1`	The delays between retries in seconds.
`task_retry_backoff`	int	`1`	The backoff factor for retries, to space out repeated retries.
`subject_identity_verification_required`	bool	`False`	Whether privacy requests require user identity verification.
`require_manual_request_approval`	bool	`False`	Whether privacy requests require explicit approval to execute.
`masking_strict`	bool	`True`	If set to `True`, only use UPDATE requests to mask data. If `False`, Fides will use any defined DELETE or GDPR DELETE endpoints to remove PII, which may extend beyond the specific data categories that configured in your execution policy.
`use_dsr_3_0`	bool	`False`	If set to `True`, privacy requests will be processed using DSR 3.0 which supports parallelization, asynchronous tasks, and task persistence. If `False`, DSR 2.0 execution will be applied which processes tasks sequentially and in-memory.
`request_task_ttl`	int	604800	For DSR 3.0, the number of seconds a Request Task should live (Privacy Request subtasks). Older request tasks will be cleaned up from completed Privacy Requests periodically.
`state_polling_interval`	int	30	For DSR 3.0, the number of seconds between a scheduled process that checks to see if a Privacy Request's subtasks have "completed" and the overall Privacy Request needs to be placed in an errored state so it can be reprocessed.
`disable_consent_identity_verification`	bool	`None`	Allows selective disabling of identity verification specifically for consent request. Identity verification for consent requests will be enabled if subject_identity_verification_required is set to true and this setting is empty or false.
`allow_custom_privacy_request_field_collection`	bool	`False`	Allows the collection of custom privacy request fields from incoming privacy requests.
`allow_custom_privacy_request_fields_in_request_execution`	bool	`False`	When set to `True`, allows the use of custom fields during the execution of privacy requests.
`interrupted_task_requeue_interval`	int	`300`	Seconds between polling for interrupted tasks to requeue.
`fuzzy_search_enabled`	bool	`True`	Whether fuzzy search is enabled for privacy request lookups.

User

Environment variable prefix: FIDES__USER__

Name	Type	Default	Description
`encryption_key`	String	`test_encryption_key`	An arbitrary string used to encrypt the user data stored in the database. Encryption is implemented using PGP.
`analytics_opt_out`	Boolean	`""`	When set to `true`, prevents sending anonymous analytics data to Ethyca.
`username`	Boolean	`""`	The username used to log into the Fides webserver.
`password`	Boolean	`""`	The password used to log into the Fides webserver.

Credentials

Environment variable prefix: FIDES__CREDENTIALS__

The credentials section uses custom keys which can be referenced in specific commands that take the --credentials-id option. For example, a command that uses a credential might look like fides scan dataset db --credentials-id app_postgres. The credential object itself will be validated at the time of use depending on what type of credential is required. For instance if fides scan system okta is used, it will expect the object to contain orgUrl and token key/value pairs. In the case of a typical database like postgres, it will only expect a connection_string. The following is an example of what a credentials section might look like in a given deployment with various applications:

Name	Type	Description
`my_postgres.connection_string`	String	Sets the `connection_string` for `my_postgres` database credentials.
`my_aws.aws_access_key_id`	String	Sets the `aws_access_key_id` for `my_aws` credentials.
`my_aws.aws_secret_access_key`	String	Sets the `aws_secret_access_key` for `my_aws` credentials.
`my_aws.aws_session_token`	String	Sets the `aws_session_token` for `my_aws` credentials.
`my_aws.region_name`	String	Sets the `region_name` for `my_aws` credentials.
`my_okta.orgUrl`	String	Sets the `orgUrl` for `my_okta` credentials.
`my_okta.token`	String	Sets the `token` for `my_okta` credentials.
`my_bigquery.dataset`	String	Sets the `dataset` for `my_bigquery` credentials.
`my_bigquery_creds.type`	String	Sets the `type` for `my_bigquery` credential keyfile.
`my_bigquery_creds.project_id`	String	Sets the `project_id` for `my_bigquery` credentials keyfile.
`my_bigquery_creds.private_key_id`	String	Sets the `private_key_id` for `my_bigquery` credentials keyfile.
`my_bigquery_creds.private_key`	String	Sets the `private_key` for `my_bigquery` credentials keyfile.
`my_bigquery_creds.client_email`	String	Sets the `client_email` for `my_bigquery` credentials keyfile.
`my_bigquery_creds.client_id`	String	Sets the `client_id` for `my_bigquery` credentials keyfile.
`my_bigquery_creds.auth_uri`	String	Sets the `auth_uri` for `my_bigquery` credentials keyfile.
`my_bigquery_creds.token_uri`	String	Sets the `token_uri` for `my_bigquery` credentials keyfile.
`my_bigquery_creds.auth_provider_x509_cert_url`	String	Sets the `auth_provider_x509_cert_url` for `my_bigquery` credentials keyfile.
`my_bigquery_creds.client_x509_cert_url`	String	Sets the `client_x509_cert_url` for `my_bigquery` credentials keyfile.

Admin UI

Environment variable prefix: FIDES__ADMIN_UI__

Name	Type	Default	Description
`enabled`	bool	`True`	Toggle whether the Admin UI is served from `/`.
`url`	String	`""`	The base URL for the Admin UI.
`max_privacy_request_download_rows`	int	`100000`	The maximum number of rows permitted to be returned in a privacy request report download.

Notifications

Environment variable prefix: FIDES__NOTIFICATIONS__

Name	Type	Default	Description
`send_request_completion_notification`	bool	`False`	When set to `True`, enables subject notifications upon privacy request completion.
`send_request_receipt_notification`	bool	`False`	When set to `True`, enables subject notifications upon privacy request receipt.
`send_request_review_notification`	bool	`False`	When set to `True`, enables subject notifications upon privacy request review.
`notification_service_type`	String	N/A	Sets the notification service type used to send notifications. Accepts `aws_ses`, `mailchimp_transactional`, `mailgun`, `twilio_sms`, or `twilio_email`.
`enable_property_specific_messaging`	bool	`False`	When set to True, enables property specific messaging feature, otherwise fall back on the messaging template type env flags set above.

Consent

Environment variable prefix: FIDES__CONSENT__

Name	Type	Default	Description
`tcf_enabled`	bool	`False`	When set to `True`, enables the IAB Transparency and Consent Framework. This feature requires additional configuration in the privacy center as well as a Fides Enterprise license.
`ac_enabled`	bool	`False`	When set to `True`, enables the Google Ads additional consent string. Requires TCF and a Fides Enterprise license.
`override_vendor_purposes`	bool	`False`	When set to `True`, allows for overriding the flexible legal legal basis of some TCF purposes.

Additional environment variables

The following environment variables are not included in the default fides.toml configuration, but may be set in your environment:

ENV Variable	Default	Description
`FIDES__HOT_RELOAD`	`False`	If `True`, the Fides server will reload code changes without needing to restart the server. This variable should always be set to `False` in production systems.
`FIDES__DEV_MODE`	`False`	If `True`, the Fides server will log error tracebacks, and log details of third party requests. This variable should always be set to `False` in production systems.
`FIDES__CONFIG_PATH`	None	If this is set to a path, that path will be used to load `.toml` files first. Any .toml files on this path will override any installed .toml files.

Fidesplus Configuration Variable Reference

Fidesplus supports all the Fides configuration variables above. Additionally, it also supports several Fidesplus-specific configuration sections, listed below.

Detection and Discovery

Environment variable prefix: FIDESPLUS__DETECTION_DISCOVERY__

Name	Type	Default	Description
`website_monitor_enabled`	bool	`False`	Enables the website monitor service.
`website_monitor_service_url`	String	`""`	The hostname (including protocol prefix and port) to use for the website monitor service.
`website_monitor_service_api_key`	String	`sample_api_key`	The API key to use for authenticating with the website monitor service.
`website_monitor_polling_timeout_seconds`	int	`600`	The maximum number of seconds to wait for website monitor jobs to finish.
`website_monitor_results_page_size`	int	`100`	The number of results to fetch per page when retrieving website monitor results.

Dictionary

Environment variable prefix: FIDESPLUS__DICTIONARY__

Name	Type	Default	Description
`enabled`	bool	`False`	Enables the Privacy Dictionary service.
`dictionary_service_url`	String	`"http://sample-dictionary-service:8081"`	The hostname (including protocol prefix and port) to use for the dictionary service.
`dictionary_service_api_key`	String	`sample_api_key`	The API key to use for authenticating with the dictionary service.

Endpoint Cache Settings

Environment variable prefix: FIDESPLUS__ENDPOINT_CACHE__

Name	Type	Default	Description
`privacy_experience_cache_ttl`	float	`3600`	The TTL (time-to-live), in seconds, for entries in the GET /privacy-experience endpoint cache. If set to a value <= 0, the cache is disabled.
`privacy_experience_gvl_translations_cache_ttl`	float	`86400`	The TTL (time-to-live), in seconds, for entries in the GET /privacy-experience/gvl/translations cache. If set to a value <= 0, the cache is disabled.
`privacy_experience_meta_cache_ttl`	float	`3600`	The TTL (time-to-live), in seconds, for entries in the GET /privacy-experience-meta endpoint cache. If set to a value <= 0, the cache is disabled.
`get_property_by_path_cache_ttl`	float	`3600`	The TTL (time-to-live), in seconds, for entries in the GET /property?path endpoint cache. If set to a value <= 0, the cache is disabled.

GVL Settings

Environment variable prefix: FIDESPLUS__GVL__

Name	Type	Default	Description
`gvl_source_url`	String	`"https://vendor-list.consensu.org/v3/vendor-list.json"`	The URL from which to fetch the official GVL vendor list.

Job Settings

Environment variable prefix: FIDESPLUS__JOBS__

Name	Type	Default	Description
`system_change_webhook_url`	String	`""`	The URL to send the system change digest to. Defaults to None.

Consent Extension

These are Fidesplus Extensions from the core Fides Consent Settings

Environment variable prefix: FIDES__CONSENT__

Name	Type	Default	Description
`max_rapid_consent_rows`	int	`100000`	The maximum number of rows permitted to be returned in a rapid consent report response.
`rapid_consent_db_buffer_size`	int	`1000`	The number of rows in the rapid consent DB query buffer.
`enable_translations`	bool	`False`	Enables a customer to set their own content in various languages.
`enable_oob_translations`	bool	`False`	Enables translations on out-of-the-box Experiences and Notices.
`enable_auto_tcf_translation`	bool	`False`	Enables automatic (server-side) translations of the minimal TCF experience response to the user's preferred language based on the Accept-Language header. WARNING: this can significantly decrease cache hit ratios and reduce performance.
`tcf_publisher_country_code`	String	`None`	The country code of the country that determines the legislation of reference. Commonly, this corresponds to the country in which the publisher's business entity is established.
`privacy_experiences_tcf_db_cache_enabled`	bool	`True`	If true, TCF privacy experience responses will be pre-calculated and stored in the database. See the privacy_experiences_error_on_cache_miss setting to configure behavior when a cache miss occurs.
`privacy_experiences_error_on_cache_miss`	bool	`False`	If true, an error will be returned for privacy experiences that are not found in the DB cache instead of calculating the experience response on the fly.

Security Extension

These are Fidesplus Extensions from the core Fides Security settings

Environment variable prefix: FIDES__SECURITY__

Name	Type	Default	Description
`consent_webhook_access_token_expire_minutes`	int	`129600`	The time in minutes for which consent webhook access tokens will be valid. Default value is equal to 90 days.

System Scanner Settings

Environment variable prefix: FIDESPLUS__SYSTEM_SCANNER__

Name	Type	Default	Description
`enabled`	bool	`False`	Enables the system scanner.
`cluster_id`	string	`""`	The cluster ID for the system scanner. Must be a valid UUID if the system scanner is enabled.
`pixie_api_key`	string	`""`	The API key for the Pixie service. Must be provided if the system scanner is enabled.
`use_encryption`	bool	`False`	Whether to use encryption for the system scanner.
`pixie_cloud_server_url`	string	`work.getcosmic.ai`	The URL of the Pixie cloud server.

Celery Configuration

Fides uses Celery (opens in a new tab) for asynchronous task management.

Fides supports configuring some Celery values via environment variables. These settings are listed below. Environment variable prefix: FIDES__CELERY__

Name	Type	Default	Description
`event_queue_prefix`	String	`fides_worker`	The prefix to use for event receiver queue names.
`task_default_queue`	String	`fides`	The name of the default queue if a message has no route or no custom queue has been specified.
`task_always_eager`	Boolean	`True`	If true, tasks are executed locally instead of being sent to the queue. If False, tasks are sent to the queue.

Also, to simplify deployments and remove the need for two different toml configuration files, it is possible to configure celery via the Fides configuration file. Any valid configuration key/value pair for celery can instead be added to the Fides toml configuration file and will automatically be passed through to the celery deployment. Note that Fides will not validate any of these key/value pairs. See the above configuration file reference for an example of using celery configuration pass-through.

For a full list of possible variable overrides, see the Celery configuration (opens in a new tab) documentation.

Security Best Practices Properties