Prebid Sales Agent - Security Model

• Authentication Layers
  • Super Admin
  • OAuth / SSO
  • Tenant Admin Token
  • Principal Token
• Token Management
  • How Tokens Are Stored
  • Token Lifecycle
  • Token Expiry
• Encryption at Rest
  • Fernet Symmetric Encryption
  • ENCRYPTION_KEY
  • Encrypted Fields
• Multi-Tenant Isolation
  • Composite Primary Keys
  • Tenant-Scoped Queries
  • No Cross-Tenant Data Access
  • Request Flow
• Network Security
  • Nginx Reverse Proxy
  • Port Exposure
  • Cloud Deployments
• Super Admin Access
  • Configuration
  • Security Considerations
• Audit Trail
  • Audit Log Schema
• Production Hardening Checklist
• Next Steps

Authentication Layers

The Prebid Sales Agent uses a layered authentication model with four distinct levels. Each level serves a different actor and grants different capabilities.

Super Admin

Super admin privileges are granted based on environment variables:

• SUPER_ADMIN_EMAILS: Comma-separated list of specific email addresses (e.g., alice@corp.com,bob@corp.com)
• SUPER_ADMIN_DOMAINS: Comma-separated list of email domains (e.g., corp.com). All users with an email at any listed domain receive super admin access.

Super admins can:

• Create, read, update, and delete tenants
• Access any tenant’s data and configuration
• Manage platform-wide settings

OAuth / SSO

Each tenant can configure its own OIDC provider for Admin UI authentication. Supported providers:

SSO credentials (client ID, client secret) are encrypted at rest. Configure SSO in the Admin UI under Settings > SSO, or see the Admin UI Guide for details.

Tenant Admin Token

Each tenant has an admin_token field used for programmatic API access. This token is separate from principal tokens and grants tenant-level management capabilities.

Principal Token

Principals (advertisers and buying agents) authenticate using tokens sent in request headers:

Either header is accepted. The x-adcp-auth header takes precedence if both are present.

Token Management

How Tokens Are Stored

Auth tokens are hashed before storage in the database. The original plaintext token is displayed only once – at creation time – and cannot be retrieved afterward.

Token Lifecycle

Token Expiry

The auth_token_expires_at field on the principal record sets an expiry time for the token. After this timestamp, the token is rejected even if the hash matches. This provides automatic credential rotation without manual intervention.

Encryption at Rest

Fernet Symmetric Encryption

The Sales Agent uses Fernet symmetric encryption (from the cryptography library) to encrypt sensitive fields before they are stored in the database. This provides authenticated encryption – data is both encrypted and integrity-protected.

ENCRYPTION_KEY

The ENCRYPTION_KEY environment variable holds the Fernet key used for all encryption operations. If not provided, a key is auto-generated on first run.

Generate a key manually:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Encrypted Fields

The following fields are encrypted before database storage:

All other data (product definitions, media buys, audit logs) is stored unencrypted in PostgreSQL and protected by database-level access controls.

Multi-Tenant Isolation

When ADCP_MULTI_TENANT=true, tenant isolation is enforced at the application layer through several mechanisms.

Composite Primary Keys

Database tables that hold tenant-specific data use composite primary keys that include tenant_id. This ensures that records from different tenants cannot collide.

Tenant-Scoped Queries

Every database query includes a WHERE tenant_id = :tenant_id clause. The tenant ID is resolved from the request’s Host header (subdomain routing) and injected into the query context by middleware.

No Cross-Tenant Data Access

The UnifiedAuthMiddleware (ASGI middleware) resolves the tenant from the request and creates an AuthContext that is passed through the entire request lifecycle. Business logic functions receive a ResolvedIdentity object that is always scoped to a single tenant. There is no API endpoint that returns data across tenants except for super admin tenant management.

Request Flow

Request → Host header → Subdomain extraction → Tenant resolution
       → Token validation (scoped to resolved tenant)
       → AuthContext created (tenant_id + principal_id)
       → ResolvedIdentity passed to business logic
       → All queries filtered by tenant_id

Network Security

Nginx Reverse Proxy

In Docker deployments, nginx sits in front of the application and provides:

• TLS termination: HTTPS with configurable certificates
• CORS: Cross-origin request filtering
• Rate limiting: Request rate limits to prevent abuse
• Request buffering: Protection against slow-client attacks
• Header injection: X-Real-IP, X-Forwarded-For, X-Forwarded-Proto

Port Exposure

Only port 8000 (nginx) should be exposed to the public internet. Internal ports are:

As of v1.5.0, all protocols (MCP, A2A, REST, Admin UI) are served by a single FastAPI process on port 8080. Ports 8001 and 8091 from the legacy multi-process architecture are no longer used.

Cloud Deployments

On Fly.io and Cloud Run, TLS termination and load balancing are handled by the platform. Set SKIP_NGINX=true and let the platform manage network security.

Super Admin Access

Super admin access is controlled entirely through environment variables and checked at authentication time.

Configuration

# Specific email addresses
SUPER_ADMIN_EMAILS=alice@corp.com,bob@corp.com

# All users at these domains
SUPER_ADMIN_DOMAINS=corp.com,platform.io

Security Considerations

• Use SUPER_ADMIN_EMAILS for the tightest control – only named individuals receive super admin access.
• Use SUPER_ADMIN_DOMAINS cautiously – anyone with an email at the listed domain can gain super admin access if they authenticate via SSO.
• In multi-tenant mode, super admins are the only users who can access data across tenants.
• Super admin status is not stored in the database – it is evaluated at request time from the environment variables.

Audit Trail

Every operation is logged in the audit_logs table, providing a complete trail for security review and compliance.

Audit Log Schema

See Monitoring & Audit Logging for querying and alerting on audit data.

Production Hardening Checklist

Use this checklist before deploying to production:

Next Steps

• Monitoring & Audit Logging – health checks, structured logging, and alerting
• Admin UI Guide – SSO setup and user management
• Multi-Tenant Deployment – tenant isolation in practice
• Deployment Overview – platform-specific security configuration