Security Overview

Security is embedded into every layer of CRAFT. The security model is built on four pillars: authentication (who you are), authorization (what you can do), secrets management (protecting credentials), and multi-tenant isolation (keeping organizations separate).

Security Architecture

Authentication (AuthN)
Authorization (AuthZ)
Secrets Management
Multi-Tenant Isolation

Technology: Keycloak with multi-realm JWT and OIDC/PKCEKeycloak provides the identity layer for the entire platform. Each organization is a separate Keycloak realm, providing complete identity isolation between tenants.

Feature	Details
Protocol	OpenID Connect (OIDC) with PKCE for browser clients
Token format	JWT containing `org_id` (from realm), groups, and user claims
Multi-realm	Each organization = one Keycloak realm (realm ID = org ID)
SSO support	Enterprise SSO via SAML or OIDC identity provider federation
Session management	Token refresh, revocation, and session timeout policies

The project_id is never stored in the JWT. It is passed via the X-Project-ID HTTP header or as a path parameter, allowing users to switch project context without re-authenticating.

Technology: OpenFGA with Relationship-Based Access Control (ReBAC)OpenFGA provides fine-grained authorization based on relationships between entities rather than static role assignments. This enables permission inheritance and computed permissions.

Roles

Role	Scope	Description
`owner`	Organization	Full control over the organization and all resources
`admin`	Organization / Project	Administrative access to manage users and settings
`member`	Project	Standard access to project resources
`developer`	Project	Create and modify agents, connections, and workflows
`operator`	Project	Deploy, schedule, and monitor resources
`viewer`	Project	Read-only access to all resources

Computed Permissions

Permissions are computed at query time from role relationships, not statically assigned:

Permission	Derived From
`can_read`	All roles (viewer and above)
`can_write`	member, developer, admin, owner
`can_delete`	admin, owner
`can_execute`	developer, operator, admin, owner
`can_manage_secrets`	admin, owner

Permission Inheritance

Permissions flow downward through the resource hierarchy:A user who is an admin of an organization automatically has admin-level computed permissions on all projects and resources within it.

Solutions must never implement their own permission checks. All authorization is delegated to the Governance service via the require_permission() decorator or SDK calls. If Governance is unavailable, all downstream services return 403.

The platform supports two secrets backends, choose based on your deployment environment. See Secrets Management for a full comparison.

Layer	Options	Scope	Examples
Application (cloud)	ESO + GCP Secret Manager	Platform services, synced to K8s Secrets	Data connection credentials, API keys
Application (on-prem)	Infisical	Platform services	Data connection credentials, API keys, encryption keys
Infrastructure	GCP Secret Manager (via Terraform)	Terraform-managed resources	Database passwords, service account keys

Key properties:

Secrets are never exposed in API responses
Per-organization namespace isolation (Infisical) or IAM-scoped access (GCP SM)
Credentials are injected at runtime only when needed
Auto-rotation supported: ESO + Stakater Reloader (cloud), Infisical rotation policies (self-hosted)

Never commit secrets or credentials to configuration files or source code. Use the platform Secrets API for application secrets and GCP Secret Manager or your cloud provider’s equivalent for infrastructure secrets.

Multi-tenancy provides complete isolation between organizations at every layer of the stack:

Layer	Isolation Mechanism
Authentication	Separate Keycloak realm per organization
Authorization	Per-organization OpenFGA relationship tuples
Data	All database queries filtered by `org_id` from JWT
Secrets	Per-organization isolation (Infisical namespaces or GCP SM IAM bindings)
Storage	Tenant-scoped object storage paths

Security Invariants

These rules are enforced across all platform services:

The org_id always comes from the authenticated JWT token, never from request parameters
List operations filter by both org_id (from JWT) AND project_id (from header) at the database level
Write operations stamp the org_id from the JWT onto new resources
No cross-service foreign keys exist between databases
A missing org_id filter on a list query is treated as a security vulnerability

Platform services run entirely within your infrastructure. External data egress depends on the integrations and model providers you configure — for example, LLM calls via LiteLLM are sent to the provider you choose (Gemini, GPT, Claude, or a self-hosted model). You control what data leaves your environment.

Dual Authorization Pattern

The platform enforces authorization through a dual pattern that combines database filtering with OpenFGA checks:

Operation Type	Database Filter	OpenFGA Check
List operations	Filter by `auth.org_id` + `project_id`	`require_permission()` for project access
Get-by-ID operations	Not needed	`require_permission()` handles authorization
Create operations	Stamp `auth.org_id` on resource	`require_permission()` for project write access
Delete operations	Not needed	`require_permission()` for resource delete access

This dual pattern prevents two classes of vulnerabilities: (1) listing resources across organizations (database filter) and (2) accessing specific resources without permission (OpenFGA check).

Authentication Flow

User Login

The user authenticates via OIDC/PKCE flow against their organization’s Keycloak realm. The browser receives a JWT token containing org_id and group memberships.

API Request

The client includes the JWT in the Authorization: Bearer <token> header and the active project in the X-Project-ID header.

Token Validation

The Governance service validates the JWT signature, expiry, and issuer. It extracts org_id from the realm claim.

Permission Check

OpenFGA evaluates the user’s relationship to the requested resource. Computed permissions are resolved at query time based on role inheritance.

Request Processing

If authorized, the request proceeds with the authenticated context. Database queries are scoped to org_id and project_id.

Network Security

Control	Implementation
SSRF protection	Webhook and data connection endpoints validate target URLs against allowlists
HMAC signatures	Webhook payloads will be signed with HMAC for integrity verification (planned — not yet released)
TLS	All inter-service communication uses TLS in production
Private networking	Cloud deployments use private VPC networking; self-managed clusters should use equivalent network segmentation
Firewall rules	Terraform-managed ingress/egress rules

Observability and Audit

The platform provides comprehensive observability for security monitoring:

Component	Technology	Purpose
Traces	OpenTelemetry + Tempo	Distributed request tracing across services
Metrics	OpenTelemetry + Mimir	Service health, latency, and throughput metrics
Logs	OpenTelemetry + Loki	Structured logging with correlation IDs
Dashboards	Grafana	Visualization and alerting for all telemetry

All telemetry is exported via the OTLP (OpenTelemetry Protocol) standard — a vendor-neutral protocol compatible with any OTLP-capable backend. You choose your observability stack; the Grafana LGTM bundle (Loki, Grafana, Tempo, Mimir) is included by default but never required.

Security Best Practices

For Platform Operators

Enable TLS for all ingress and inter-service communication
Configure Keycloak password policies and brute-force detection
Set up regular secret rotation (Infisical rotation policies or ESO + Stakater Reloader)
Monitor OpenFGA permission check latency and error rates
Review audit logs for unauthorized access attempts
Use private networking for database and cache connections

For Solution Developers

Never implement permission checks directly — always use require_permission()
Always use auth.org_id from JWT, never from request parameters
Never store secrets in configuration files or environment variables in source control
Use the Governance SDK for all authentication and authorization operations
Validate webhook signatures before processing events (when webhook feature is released)
Use parameterized queries to prevent SQL injection (enforced by SQLAlchemy ORM)

Next Steps

Authentication

Deep dive into Keycloak configuration and OIDC flows.

Data Classification

Understand data classification and handling policies.

Network Security

Learn about network-level security controls and firewall configuration.

RBAC Configuration

Step-by-step guide for configuring roles and permissions.

Observability

Security

Compliance

Release Notes

CRAFT Security Overview

Security Overview

Security Architecture

Roles

Computed Permissions

Permission Inheritance

Security Invariants

Dual Authorization Pattern

Authentication Flow

Network Security

Observability and Audit

Security Best Practices

Next Steps

Authentication

Data Classification

Network Security

RBAC Configuration

Observability

Security

Compliance

Release Notes

Documentation Index

​Security Overview

​Security Architecture

​Roles

​Computed Permissions

​Permission Inheritance

​Security Invariants

​Dual Authorization Pattern

​Authentication Flow

​Network Security

​Observability and Audit

​Security Best Practices

​Next Steps

Authentication

Data Classification

Network Security

RBAC Configuration

Security Overview

Security Architecture

Roles

Computed Permissions

Permission Inheritance

Security Invariants

Dual Authorization Pattern

Authentication Flow

Network Security

Observability and Audit

Security Best Practices

Next Steps