README
¶
OpenTDF Platform Service
The OpenTDF Platform Service is the main entry point for the OpenTDF platform. It provides the scaffolding for running OpenTDF and ensures that all required services are configured and running as expected.
[!NOTE] It is advised to familiarize yourself with the terms and concepts used in the OpenTDF platform.
Quick Start
[!WARNING] This quickstart guide is intended for development and testing purposes only. The OpenTDF platform team does not provide recommendations for production deployments.
To get started with the OpenTDF platform make sure you are running the same Go version found in the go.mod file.
https://github.com/opentdf/platform/blob/main/service/go.mod#L3
Start the required infrastructure with compose-spec.
# Note this might be `podman compose` on some systems
docker compose -f docker-compose.yaml up
Copy the configuration file from the example and update it with your own values.
cp opentdf-example.yaml opentdf.yaml
Provision default configurations.
# Provision keycloak with the default configuration.
go run ./service provision keycloak
# Generate the temporary keys for KAS
./.github/scripts/init-temp-keys.sh
Run the OpenTDF platform service.
go run ./service start
Services
Services are the core building block of the platform. Generally, each service is one or more gRPC services that scoped to a namespace.
- Core Services
- Health - Provides rollup health checks for the platform based on the services running.
- Well Known - Provides well-known endpoints for the platform.
- Authorization - Validates the entity has the correct entitlements based on the policy.
- Entity Resolution - Resolves entity authorization using connected services (i.e. IdP).
- Key Access (KAS) - Controls access to TDF protected content.
- Policy - Manages the policy for the TDF platform.
Development
Generation
Our native gRPC service functions are generated from proto definitions using Buf.
The Makefile provides command scripts to invoke Buf with the buf.gen.yaml config, including OpenAPI docs, grpc docs, and the
generated code.
For convenience, the make toolcheck script checks if you have the necessary dependencies for proto -> gRPC generation.
Provisioning Custom Keycloak and Policy Data
To provision a custom Keycloak setup, create a yaml following the format of the sample Keycloak config. You can create different realms with separate users, clients, roles, and groups. The token_exchanges entries enable Keycloak standard token exchange on the requester clients. Run the provisioning with go run ./service provision keycloak -f <path-to-your-yaml-file>.
Developing a new platform service
This guide will help you to develop a new service within the platform. The platform is focused on a modular binary architecture, so the goal of the service is isolation while also getting the benefits of a shared platform.
Structure
OpenTDF services are located under the service directory. Each service should have a unique directory name which is
expected to relate to the service namespace.
Service Namespace
A service namespace is a unique identifier for the service. It is used to identify the service in the platform and to enable multiple gRPC services to be rolled up into a single service.
The namespace should be a unique identifier for the service. It should be a single word, all lowercase, and should not contain any special characters. It should be the same as the directory name for the service.
Registration
Services are registered with the platform by implementing the serviceregistry.IService interface, and
calling the serviceregistry.RegisterService function.
Notice that serviceregistry.RegisterService is called in server.Start.
https://github.com/opentdf/platform/blob/service/v0.5.2/service/pkg/server/start.go#L147-L157
Services will be started if the deployed mode is all (the default) or the service name is given
in the mode. Note that mode may contain a comma-separated list of services (see below).
https://github.com/opentdf/platform/blob/service/v0.5.2/opentdf-example.yaml#L11
https://github.com/opentdf/platform/blob/service/v0.5.2/opentdf-ers-mode.yaml#L3
The mode can be given as a list of strings as well, for instance core,foo,bar as
shown below:
mode: core,foo,bar
It's important that the service name matches the Namespace of the service. Optionally, you can
also specify configuration for the service in the opentdf.yaml file. The configuration
is not required, but it is recommended to provide a default configuration for the service.
For example, the opentdf.yaml file for a new service called myservice might include:
services:
myservice:
enabled: true
foo: bar
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
benchmark
command
Command benchmark runs the integration benchmarks reported by CI.
|
Command benchmark runs the integration benchmarks reported by CI. |
|
keygen
command
Package main generates post-quantum KAS key pairs (X-Wing, P256+ML-KEM-768, P384+ML-KEM-1024, ML-KEM-768, ML-KEM-1024) as PEM files for use with the OpenTDF platform.
|
Package main generates post-quantum KAS key pairs (X-Wing, P256+ML-KEM-768, P384+ML-KEM-1024, ML-KEM-768, ML-KEM-1024) as PEM files for use with the OpenTDF platform. |
|
internal
|
|
|
auth/authz
Package authz provides the authorization interface and types for the OpenTDF platform.
|
Package authz provides the authorization interface and types for the OpenTDF platform. |
|
auth/authz/casbin
Package casbin registers the Casbin authorization engine and dispatches to the configured versioned implementation.
|
Package casbin registers the Casbin authorization engine and dispatches to the configured versioned implementation. |
|
auth/authz/casbin/v1
Package v1 provides the legacy path-based Casbin authorization implementation.
|
Package v1 provides the legacy path-based Casbin authorization implementation. |
|
auth/authz/casbin/v2
Package v2 provides the resource/dimension-based Casbin authorization implementation.
|
Package v2 provides the resource/dimension-based Casbin authorization implementation. |
|
server/memhttp
Package memhttp provides an in-memory HTTP server and client.
|
Package memhttp provides an in-memory HTTP server and client. |
|
pkg
|
|