Skip to main content

Documentation Index

Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Portal Connect Agent is a stateless proxy service that:
  • Runs as a containerized application (Docker/Kubernetes)
  • Establishes an outbound-only WebSocket connection to your Portal instance
  • Proxies HTTP requests to internal services without storing data
  • Authenticates using mutual TLS (mTLS) certificates
The Agent never listens for or accepts inbound connections, eliminating the inbound attack surface.

​
Transport Security

​
TLS Configuration

Protocol Version
  • Uses Node.js 22 TLS defaults: TLS 1.2 and TLS 1.3
  • TLS 1.3 preferred, with TLS 1.2 fallback for compatibility
  • SSL 3.0, TLS 1.0, and TLS 1.1 explicitly disabled
WebSocket Security
  • WebSocket Secure (WSS) over TLS for broker connection
  • Enforces server certificate validation (rejectUnauthorized: true)
  • Persistent connection with automatic reconnection and exponential backoff
Cipher Suites
  • Uses Node.js 22 default cipher suite selection
  • Prioritizes AEAD ciphers (AES-GCM, ChaCha20-Poly1305)
  • Excludes weak ciphers (RC4, DES, 3DES, MD5)
  • Forward secrecy enabled via ECDHE/DHE key exchange
Connection Settings
  • HTTP/HTTPS connection pooling with keep-alive
  • 30-second request timeout (configurable)
  • 10-second WebSocket connection timeout
  • Automatic decompression disabled to preserve data integrity

​
Authentication and Authorization

​
Mutual TLS (mTLS)

Certificate Requirements
  • Algorithm: RSA (2048-4096 bits) or ECDSA (P-256, P-384 curves)
  • Format: PEM-encoded X.509 certificates
  • Maximum Lifespan: 180 days (enforced at startup validation)
Certificate Validation
  • Automatic validation on Agent startup
  • Validates certificate expiry, lifespan, algorithm, key size, and extensions
  • Warns when certificate expires within 7 days (configurable threshold)
  • Fails fast if certificates are invalid, expired, or missing
Certificate Lifecycle
  • Certificates generated using Agent’s built-in tool (--generate-cert)
  • Customer registers certificate with Spotify (public cert only, private key never leaves network)
  • Manual rotation required before 180-day expiration

​
Key Management

  • Private keys remain within customer network perimeter
  • Recommended file permissions: 400 or 600 (owner read-only)
  • File-based secrets supported via ${VAR_NAME_FILE} environment variable substitution
  • Keys loaded from filesystem at startup (paths: clientCertPath, clientKeyPath)

​
Route-Based Access Control

Authorization Model
  • Agent explicitly registers allowed routes (URL patterns) with Portal
  • Portal only forwards requests matching registered routes to Agent
  • Supports exact match and wildcard patterns (e.g., https://api.github.com/*)
  • Route headers can inject authentication credentials for downstream services
Credential Handling
  • Service credentials (API keys, tokens) configured at Agent level
  • Environment variable substitution prevents hardcoded secrets in config files
  • Credentials injected into outbound requests to internal services
  • Portal never sees or stores internal service credentials

​
Data Handling and Privacy

​
Data in Transit

Encryption
  • All data transmitted via TLS-encrypted WebSocket (WSS)
  • Request and response bodies encrypted end-to-end between Portal and Agent
  • Agent-to-internal-service connections use HTTPS where configured
  • No cleartext transmission of sensitive data
Data Processing
  • Agent operates as a stateless proxy - no persistent storage
  • Requests and responses held in memory only during active processing
  • Binary and compressed content preserved without decompression
  • No caching of request or response data
Data Encoding
  • UTF-8 encoding for text content
  • Base64 encoding for binary and compressed content
  • Automatic detection of content type and compression
  • Preserves Content-Encoding headers for compressed responses

​
Data at Rest

Storage
  • No persistent data storage - Agent is entirely stateless
  • Configuration file stored on disk (contains routes, not credentials)
  • Certificates stored on disk (required for mTLS)
  • No request/response logging to disk (logged to stdout only)
Temporary Data
  • Request/response buffers in memory during processing
  • Memory cleared when processing completes or Agent restarts
  • No swap or core dump file generation (depends on OS configuration)

​
Container Security

​
SBOM (Software Bill of Materials)

  • Complete inventory of all packages, libraries, and dependencies in Docker images
  • Generated automatically during CI/CD builds in SPDX JSON format using Anchore Syft
  • Enables rapid vulnerability scanning - quickly identify if images contain packages with known CVEs
  • Required for compliance with emerging regulations (NIST guidelines, EU Cyber Resilience Act)
  • Stored as GitHub Actions artifacts and cryptographically signed attestations attached to images
  • Use cosign verify-attestation to view the SBOM of any deployed image
  • Critical for incident response: identify all affected images when a dependency vulnerability is disclosed

​
Image Signing

  • All Docker images are cryptographically signed using Cosign (Sigstore) with key-based signing
  • Provides proof of authenticity - verifies images were built by CI/CD pipeline and haven’t been tampered with
  • Prevents supply chain attacks: unauthorized or modified images fail signature verification
  • Public key (cosign.pub) is shared with teams for image verification before deployment
  • Signatures are stored alongside images in Google Artifact Registry

​
Base Image

Image Details
  • Base: node:22-alpine (Alpine Linux 3.x)
  • Official Node.js Docker images from Docker Hub
  • SHA-256 digest pinning prevents tag mutation attacks
  • Regular security updates applied via apk upgrade --no-cache
User Configuration
  • Runs as non-root user
  • Minimal privileges
  • File ownership set
  • No sudo or privilege escalation capabilities

​
Container Hardening

Filesystem
  • Configuration mounted read-only (:ro flag)
  • Certificates mounted read-only
  • No write access to sensitive directories
  • Application runs from /app directory
Runtime Security
  • No privileged mode required
  • Minimal exposed ports: 9466 (metrics only, internal to network)

​
Network Security

​
Network Architecture

Outbound Connections
  • Destination: Portal broker (e.g., wss://broker.${subdomain}.spotifyportal.com)
  • Protocol: WSS (WebSocket Secure over TLS)
  • Port: 443 (HTTPS/WSS standard) or custom as configured
  • Persistent connection maintained with heartbeat
  • Connections to internal services as configured in routes
Inbound Connections
  • None required for primary function - Agent never listens for connections
  • Metrics endpoint (port 9466) accessible only within internal network
  • No public internet exposure needed

​
Firewall Configuration

  • Inbound: No changes required - Agent does not accept connections
  • Outbound: Allow WSS to Portal broker URL
  • Outbound: Allow HTTPS/HTTP to internal services in routes
This architecture ensures that your firewall configuration for incoming traffic remains unchanged, eliminating the inbound attack surface while still enabling Portal to access your internal services.