Skip to main content

Security & Access Control

Terragnos Core implements multi-layered security controls including JWT-based authentication, role-based access control (RBAC), tenant isolation, and audit logging. This guide covers how to configure and manage these security features.

Authentication​

JWT Token Structure​

All API requests require a valid JWT token in the Authorization header:

curl -H "Authorization: Bearer <your-jwt-token>" https://core.example.com/v1/objects

The JWT must include the following claims:

  • sub – User identifier (required)
  • tenant – Tenant ID for data isolation (required)
  • roles – Array of role names (e.g., ["owner", "admin"])
  • scope – Permission scope (optional)
  • iat – Issued at timestamp
  • exp – Expiration timestamp

Token Generation​

Generate JWT tokens using your organization's identity provider or a JWT library. The token must be signed with the secret specified in AUTH_JWT_SECRET.

Example token payload:

{
  "sub": "user-123",
  "tenant": "default",
  "roles": ["admin", "operator"],
  "scope": "read:objects write:objects",
  "iat": 1704067200,
  "exp": 1704153600
}

Configuration​

Set the following environment variables:

AUTH_JWT_SECRET=your-secret-key-minimum-32-characters
AUTH_JWT_ISSUER=your-issuer-name
AUTH_JWT_AUDIENCE=your-audience-name
AUTH_DEFAULT_TENANT=default
AUTH_DISABLED=false  # Set to true only for development/testing

Warning: Never set AUTH_DISABLED=true in production. This bypasses all authentication checks.

Role-Based Access Control (RBAC)​

Built-in Roles​

Terragnos Core includes several built-in roles:

  • owner – Full access to all resources within a tenant
  • admin – Administrative access, can manage object types, workflows, and automation
  • operator – Can create and modify objects, trigger workflows
  • viewer – Read-only access to objects and data

Permission Policy​

Each tenant has a permission policy that defines what each role can do. Manage the policy via:

# Get current policy
curl -H "Authorization: Bearer <token>" \
  https://core.example.com/v1/permissions/policy

# Update policy
curl -X PUT \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d @policy.json \
  https://core.example.com/v1/permissions/policy

The policy controls access to:

  • Object types (create, read, update, delete)
  • Objects (CRUD operations)
  • Workflows (transitions, state changes)
  • Automation rules (create, modify, execute)
  • Relations (create, read, delete)
  • Audit logs (read access)

Custom Roles​

You can define custom roles in the permission policy. Custom roles inherit no permissions by default and must be explicitly granted access to resources.

Tenant Isolation​

All data in Terragnos Core is scoped to tenants. The tenant claim in the JWT determines which tenant's data the user can access.

Row-Level Security​

The database enforces tenant isolation at the row level. Users can only access objects, workflows, and automation rules that belong to their tenant.

Multi-Tenant Configuration​

To support multiple tenants:

  1. Issue JWT tokens with different tenant claims
  2. Each tenant's data is automatically isolated
  3. Cross-tenant access is not possible through the API

Network Security​

HTTPS/TLS​

Always use HTTPS in production. Configure TLS termination at your load balancer or reverse proxy (nginx, Traefik, etc.).

Firewall Rules​

Restrict access to the API port (default 3000) to:

  • Your application servers
  • Your load balancer
  • Your monitoring systems

The worker service should not be exposed to the internet.

Rate Limiting​

Configure rate limiting to prevent abuse:

RATE_LIMIT_TTL=60        # Time window in seconds
RATE_LIMIT_LIMIT=120     # Maximum requests per window

Database Security​

Connection Security​

  • Use SSL/TLS for database connections when possible
  • Store database credentials in environment variables or secret managers
  • Rotate database passwords regularly

Backup Encryption​

Encrypt database backups at rest. Use your database's native encryption features or external backup tools.

Audit Logging​

All security-relevant events are logged to the audit trail:

  • Authentication failures
  • Permission denials
  • License limit violations
  • Object modifications
  • Workflow transitions
  • Automation rule executions

Access audit logs via:

curl -H "Authorization: Bearer <admin-token>" \
  https://core.example.com/v1/audit/events

Audit Log Integrity​

Each audit event includes a cryptographic hash that links it to previous events, creating a tamper-evident chain. Verify integrity:

curl -H "Authorization: Bearer <admin-token>" \
  https://core.example.com/v1/audit/events/{eventId}/proof

Best Practices​

  1. Use strong JWT secrets – Minimum 32 characters, randomly generated
  2. Rotate secrets regularly – Update AUTH_JWT_SECRET periodically
  3. Implement token expiration – Set reasonable exp values (e.g., 1 hour)
  4. Monitor authentication failures – Set up alerts for repeated 401 responses
  5. Restrict admin endpoints – Limit access to /v1/license, /v1/permissions/policy
  6. Use HTTPS everywhere – Never transmit tokens over unencrypted connections
  7. Review audit logs regularly – Check for suspicious activity
  8. Keep dependencies updated – Regularly update container images for security patches

Compliance​

Terragnos Core supports compliance requirements through:

  • Audit trails – Complete history of all data changes
  • Tenant isolation – Data separation for multi-tenant deployments
  • Access controls – Fine-grained permission management
  • Encryption – Support for encrypted license storage and database connections

For specific compliance requirements (GDPR, SOC 2, etc.), consult with Terragnos support.