Proxy extensions

Proxy extensions are interceptors for PDP requests (CheckResources and PlanResources) and responses. Synapse exposes the same gRPC and HTTP API endpoints as the regular Cebos PDP without validation which allows applications to send partial CheckResources/PlanResources requests to the service. When Synapse receives a Cerbos API request, it is fed through the list of configured proxy extensions in the order of priority defined in the configuration. These extensions can modify the request by adding, updating or removing items before it is processed by the PDP. Similarly, the response from the PDP is fed through the list of configured extensions as well, allowing them to modify the response before it’s sent to the caller.

This ability to modify requests and responses unlocks many capabilities:

  • Lookup common and/or sensitive data points such as principal attributes from a single place which provides better security isolation, better performance, reduced resource utilization and increased visibility and accountability.

  • Redact sensitive information from responses.

  • Generate comprehensive logs, events, metrics and other internal data points required for monitoring or compliance purposes.

  • Integrate with legacy systems to source/sink data.

  • Roll out changes without modifying or restarting applications. For example, adding attributes required to enforce new requirements set by the organization or seamlessly migrating to a different provider for the same kind of data.

Configuring proxy extensions

Proxy extensions are defined under the extensions.proxyExtensions key in the Synapse configuration file.

extensions:
  dataDir: /global/data (1)
  proxyExtensions:
    lookupPrincipal: (2)
      extensionURL: "https://example.com/synapse/idp.wasm?checksum=sha256:677cce2788330f16f27981130eaa50aa4189beab2121903bcea5b3c4c918dccc" (3)
      priority: 100 (4)
      required: true (5)
      dataMount: /data (6)
      configuration: (7)
        environment: staging

    lookupFoo:
      extensionURL: "/extensions/foo.crbs?checksum=sha256:cb766ca03213d0ccb6ffab76e1988ad8e906f8033107d816f51abcfa85d4f507"
      priority: 90
1 This is the global data directory to be used by Synapse. All extension data mounts will be created under this directory.
2 Unique name for the extension.
3 URL to fetch the extension from. See extension URL format for more information.
4 Priority of the extensions. Higher value implies higher precedence. Extensions are applied in the descending order of their priority value.
5 Optional flag to mark the extension as required. If a required extension fails, Synapse terminates the chain and returns an error back to the caller.
6 Optional data mount. This virtual path will be available inside the extension for read/write operations.
7 Optional configuration values specific to the extension.

The dataMount option defines the virtual file system available to extensions. Extension code can only read/write data to this path. For example, if the dataMount is /data, then the extension can create or read any files under /data such as /data/foo.txt. If dataMount is not specified, reading or writing to any file path will fail. Locally, the data directory will be created under the global dataDir with the name of the extension (e.g. /global/data/lookupPrincipal) and persisted between restarts.

If multiple proxy extensions are configured to handle a particular request/response type, they are applied in the descending order of priority as defined in the configuration file. Failure of an individula extension is ignored and the chain continues unless the extension is marked as required. A failure from a required extension cause the chain to be terminated early and Synapse responds to the caller with an error in that case.

Building proxy extensions

See Building custom Synapse extensions.