DOCSEARCHbyAlgolia
Submit Docs

Fides Documentation

repository·main·Indexed 19 days ago

https://github.com/ethyca/fides

An open-source privacy engineering platform for managing data privacy requests and enforcing regulations. Includes documentation for the Fides Admin UI, including its table hooks architecture (useTableState, useAntTable), environment configuration, and development workflows using turbo and Cypress, as well as the FidesJS JavaScript SDK for consent management.

Tokens
65K
Snippets
216
Records
298
Agent score
67%

What's inside Fides

  1. Overview of the Fides Ecosystem

    main

    Fides is an open-source privacy engineering platform designed to manage data privacy request fulfillment in runtime environments and enforce privacy regulations directly within your code. It enables engineers and legal teams to:

    • Label system privacy characteristics: Define how data is handled.
    • Orchestrate programmatic rights fulfillment: Automate Data Subject Requests (DSRs).
    • Audit PII: Identify and audit stored Personally Identifiable Information (PII) across application systems and infrastructure.

    Fides supports major privacy regulations such as GDPR, CCPA, and LGPD, as well as standards like ISO 19944.

  3. Overview of fides-js

    main

    fides-js is a TypeScript package and library designed to render a Fides overlay (consisting of both a banner and a modal) on top of an existing website. This overlay is used to manage user consent for cookies, privacy notices, and TCF (Transparency and Consent Framework) requirements.

    fides-js currently builds two distinct scripts:

    1. fides.js: Used for serving privacy notices.
    2. fides-tcf.js: Used for serving TCF.

    To function, fides-js must be hosted and accessed via the privacy-center's /api/fides-js endpoint.

  4. Overview of FidesJS: JavaScript SDK for Fides

    main

    FidesJS is a JavaScript SDK designed to integrate Fides consent into websites or applications. It functions as a Consent Management Platform (CMP) and provides UI components (banners, modals), state management, and utility functions to collect consent and enforce data privacy.

    Key capabilities include:

    • Automatic Configuration: Configures user sessions with default consent preferences based on location (e.g., opting out of data sales).
    • Consent UI: Displays banners or modals with applicable privacy notices.
    • Persistence: Stores consent preferences in first-party cookies.
    • Consent API: Exposes preferences via the Fides.consent JavaScript API.
    • Real-time Sync: Dispatches global window events (e.g., FidesUpdated, FidesUIShown) to sync consent changes to your application.
    • Third-party Integration: Integrates consent with tools like Google Tag Manager and IAB TCF.

  5. How API URLs are defined and versioned

    main

    API URLs are defined as constants within fides.common.api.v1.urn_registry (where v1 represents the specific API version). These constants are then imported into their respective API views.

    Currently, versioning is handled by prefixing the base path (e.g., /api/v1). Future versions may override the APIRouter class instantiation to change the base path (e.g., to /api/v2).

    Example URL patterns:

    • PRIVACY_REQUEST = "/privacy-request" resolves to /api/v1/privacy-request.
    • PRIVACY_REQUEST_DETAIL = "/privacy-request/{privacy_request_id}" resolves to /api/v1/privacy-request/{privacy_request_id}.

  6. Access the Fides global API object

    main

    Once FidesJS is initialized, it exports a global object to window.Fides. This is the primary API used to integrate Fides into web applications. You can use it to check consent preferences, enable integrations (like GTM), or programmatically control the UI.

    Important Initialization Note: Because FidesJS must be downloaded and initialized before the Fides object is available, you must ensure the object exists before calling it. You should either:

    1. Check for the existence of Fides (e.g., if (window.Fides) ...)
    2. Subscribe to the global FidesReady event.
    <head>
  <script src="path/to/fides.js"></script>
</head>
<body
  <!--- ...later, in your own application code... --->
  <script>
    // Query the current user's consent preferences
    if (Fides && Fides.consent.data_sales_and_sharing) {
      // Enable advertising scripts
      console.log("Current user has opt-in consent for the `data_sales_and_sharing` privacy notice!");
    }
  </script>
</body>

  7. Evaluate Match and Unless blocks

    main

    Match Evaluation

    The match block determines applicability. Dimensions are AND'd.

    • Built-in dimensions: data_use, data_category, and data_subject (using any or all operators) and custom taxonomies.
    • Hierarchical matching: A match on user.contact will match a request for user.contact.email (child), but not user (parent).

    Unless Evaluation

    The unless block defines conditions that invert the decision if ALL conditions are met (AND'd).

    Inversion Logic:

    • ALLOW + unless_triggered $\rightarrow$ DENY (Decisive: stops evaluation).
    • DENY + unless_triggered $\rightarrow$ Suppressed (Not decisive: evaluation continues).

    Supported Condition Types:

    • consent: Checks opt-in/opt-out status via request.context["subject"] and a consent DB lookup.
    • geo_location: Checks request.context["environment"]["geo_location"].
    • data_flow: Checks system ingress/egress relationships configured in Fides.

  8. Understand how `StringEncryptedType` works

    main

    The StringEncryptedType (using AesGcmEngine) is the primary mechanism for column-level database encryption. It uses sqlalchemy-utils to transparently encrypt/decrypt values at the ORM layer.

    Encryption Process (Write):

    1. The engine derives a 32-byte key via SHA256(app_encryption_key).
    2. A random 12-byte nonce (IV) is generated.
    3. Data is encrypted with AES-256-GCM, producing ciphertext and a 16-byte authentication tag.
    4. The result is stored in the database as a base64 string in the format: base64(nonce + tag + ciphertext).

    Decryption Process (Read):

    • The engine transparently reverses the process when the ORM attribute is accessed.

    Important Limitations:

    • Key Binding: The key is captured at model class definition time (when the module is imported). You cannot switch keys at runtime.
    • No Versioning: There is no metadata stored with the ciphertext to indicate which key version was used. If the key changes, old data becomes unreadable.

  9. Manage credentials in the configuration

    main

    The [credentials] section allows you to define named credential objects that can be referenced in Fides commands using the --credentials-id option.

    Example usage:

    fides scan dataset db --credentials-id app_postgres

    Configuration format: Credentials are defined as key-value pairs within the [credentials] section. The required keys depend on the type of service being accessed:

    • Postgres/Databases: Typically requires a connection_string.
    • OAuth2 (e.g., Okta): Requires orgUrl, clientId, and privateKey.

    Example fides.toml snippet:

    [credentials]
app_postgres = {connection_string="postgresql+psycopg2://postgres:fides@fides-db:5432/fides"}

  10. How the Table Hooks architecture works

    main

    The table system is built on a layered architecture that separates state management, UI integration, and business logic. This allows for a standardized, reusable table system that supports URL synchronization and Ant Design integration.

    The Layered Flow:

    1. useTableState: Manages the core state (pagination, sorting, filtering, search) and optionally synchronizes it with the URL query parameters.
    2. useAntTable: Takes the state from useTableState and integrates it with Ant Design Table components.
    3. useComponentTable (Pattern): A combination of the two hooks above that encapsulates specific table business logic.
    4. Table Component: The final UI component that renders the table and associated controls (search, bulk actions, etc.).
    useTableState (State + URL Sync) + RTK Query
    +
useAntTable (Ant Design Integration)
    ↓
useComponentTable (Combination of the 2 hooks + table business logic)
    ↓
Table Component

  11. Configure Celery via the Fides configuration file

    main

    Fides uses Celery for asynchronous task management. To avoid maintaining separate configuration files, you can pass Celery configuration directly through the Fides toml file.

    Any valid Celery configuration key/value pair can be added under a [celery] section. Note that Fides does not validate these keys; they are passed through to the Celery deployment as-is. For a full list of available variables, refer to the Celery configuration documentation.

    [celery]
event_queue_prefix = "fides_worker"
task_default_queue = "fides"
task_always_eager = true

  12. Understand Purpose-Based Access Control (PBAC) outcomes

    main

    Fides PBAC evaluates whether a data consumer has the declared purposes required to access specific datasets. Every query evaluation results in one of three distinct outcomes:

    • Compliant: The consumer's purposes overlap with the dataset's required purposes; access is authorized.
    • Violation: The consumer's purposes do not overlap with the dataset's required purposes, indicating a policy breach.
    • Gap: The evaluation could not be completed due to incomplete configuration. Gaps are not violations and are used for auditing configuration completeness.

    Common GapType values include:

    • UNRESOLVED_IDENTITY: The user identity could not be mapped to a consumer.
    • UNCONFIGURED_CONSUMER: A consumer was found, but no purposes are assigned to them.
    • UNCONFIGURED_DATASET: The dataset does not have purposes configured.