Platform Integrations Configuration Guide

This guide explains how to configure the Platform Integrations Management feature, including encryption key setup for secure credential storage.

Overview

The Platform Integrations Management feature allows platform administrators to configure AWS, cloud providers (Azure, GCP), and 3rd party SaaS integrations through the admin UI. All credentials are encrypted at rest using AES-256-GCM encryption.

Encryption Master Key

Purpose

The ENCRYPTION_MASTER_KEY is used to encrypt sensitive integration credentials (AWS access keys, API tokens, etc.) before storing them in the database. This ensures credentials are never stored in plaintext.

Security Features:

  • AES-256-GCM encryption (authenticated encryption)
  • PBKDF2 key derivation (4096 iterations, SHA-256)
  • Random nonce for each encryption operation
  • Only sensitive fields are encrypted (access_key_id, secret_access_key, api_token, etc.)

Development Setup

For development, the encryption key is automatically generated by session-init.sh if not set. However, you can manually set it:

Option 1: Environment Variable

Add to your .env file or shell environment:

export ENCRYPTION_MASTER_KEY="your-secure-dev-master-key-change-in-production"

Option 2: Docker Compose Environment

Add to docker-compose.yml under the admin-service section:

admin-service:
  environment:
    - ENCRYPTION_MASTER_KEY=${ENCRYPTION_MASTER_KEY:-dev-master-key-change-in-production}

Production Setup

⚠️ IMPORTANT: In production, use a key management service (AWS KMS, HashiCorp Vault, etc.) instead of plain environment variables.

  1. Create a KMS key:
aws kms create-key --description "Platform Integrations Encryption Key"
  1. Update deploy-aws.sh to fetch the key:
ENCRYPTION_MASTER_KEY=$(aws kms decrypt --ciphertext-blob fileb://encrypted_key.bin --query Plaintext --output text)

Option 2: Environment Variable (Temporary)

If using environment variables in production temporarily:

  1. Generate a strong random key:
openssl rand -base64 32
  1. Set in your production environment:
export ENCRYPTION_MASTER_KEY="<generated-key>"

Security Best Practices:

  • Use a dedicated secrets management service
  • Rotate keys regularly
  • Never commit keys to version control
  • Use least-privilege access policies
  • Enable audit logging for key access

Configuration Files

Database Schema

The integration schema is automatically created via migration script:

  • scripts/database/22-platform-integrations-schema.sql

This creates:

  • platform_integrations – Main integration configuration table
  • platform_integration_secrets – Encrypted secrets storage (future use)
  • platform_integration_audit_log – Audit trail for credential changes

Service Configuration

The admin-service automatically initializes the integration service if ENCRYPTION_MASTER_KEY is set:

// services/admin-service/internal/api/server.go
if cfg.EncryptionMasterKey != "" {
    handlers.InitializeIntegrationService(db, cfg.EncryptionMasterKey, logger)
} else {
    log.Printf("Warning: ENCRYPTION_MASTER_KEY not set, integration management will be disabled")
}

Resource Tracker (AWS Cost Sync)

The resource-tracker-service reuses the same encryption key to decrypt AWS credentials when ingesting real cost data:

resource-tracker-service:
  environment:
    - ENCRYPTION_MASTER_KEY=${ENCRYPTION_MASTER_KEY}
    - AWS_COST_EXPLORER_ENABLED=true
    - AWS_COST_SYNC_INTERVAL=1h

When enabled, the service automatically loads the most recent active AWS integration, decrypts the stored access keys, and instantiates the AWS Cost Explorer client with those credentials. If no integration or key is available the job is automatically disabled and a warning is logged.

Usage

Via Admin UI

  1. Log in to the admin UI as a platform administrator
  2. Navigate to Settings → Integrations
  3. Select the integration type tab (AWS, Azure, GCP, SaaS)
  4. Click Add Integration
  5. Fill in the integration form with credentials
  6. Click Create Integration

Credentials are automatically encrypted before storage.

Via API

# List integrations
curl -X GET http://localhost:8080/api/v1/admin-service/admin/integrations 
  -H "Authorization: Bearer <admin-token>"

# Create AWS integration
curl -X POST http://localhost:8080/api/v1/admin-service/admin/integrations 
  -H "Authorization: Bearer <admin-token>" 
  -H "Content-Type: application/json" 
  -d '{
    "integration_type": "aws",
    "integration_name": "Production AWS",
    "provider": "cloud",
    "config": {
      "access_key_id": "AKIAIOSFODNN7EXAMPLE",
      "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "region": "us-east-1"
    },
    "account_id": "123456789012",
    "region": "us-east-1",
    "environment": "production",
    "is_enabled": true
  }'

Integration Types

AWS

Required Fields:

  • access_key_id – AWS Access Key ID
  • secret_access_key – AWS Secret Access Key
  • account_id – AWS Account ID (12-digit number)
  • region – Primary AWS region

Optional Fields:

  • session_token – For temporary credentials (STS)
  • environment – production, staging, development
  • description – Human-readable description

Azure (Coming Soon)

Configuration form will be added in future release.

GCP (Coming Soon)

Configuration form will be added in future release.

SaaS Integrations (Coming Soon)

Support for Slack, PagerDuty, Datadog, and other SaaS platforms will be added.

Security Considerations

Credential Storage

  • All sensitive fields are encrypted using AES-256-GCM
  • Encryption uses PBKDF2 key derivation (4096 iterations)
  • Each encryption operation uses a unique random nonce
  • Encrypted credentials are stored in JSONB columns in the database

Access Control

  • Integration management requires platform.settings permission
  • Only platform administrators can create/update/delete integrations
  • All credential changes are logged in the audit trail
  • Audit log includes user ID, timestamp, and changed fields (without exposing values)

Audit Logging

Every integration change is logged to platform_integration_audit_log:

  • Action type (created, updated, deleted, tested, credential_rotated)
  • User who performed the action
  • Config hashes (for comparison without exposing values)
  • Changed fields (field names only, not values)
  • Success/failure status
  • Error messages (if applicable)

Troubleshooting

"Integration management will be disabled" Warning

Problem: ENCRYPTION_MASTER_KEY is not set.

Solution:

  1. Set ENCRYPTION_MASTER_KEY in your environment
  2. Restart the admin-service container
  3. Verify the key is loaded: Check service logs for "Integration service initialized"

"Failed to encrypt config" Error

Problem: Encryption service failed to initialize.

Possible Causes:

  • ENCRYPTION_MASTER_KEY is empty
  • Key derivation failed

Solution:

  1. Verify ENCRYPTION_MASTER_KEY is set and not empty
  2. Check service logs for detailed error messages
  3. Ensure the key is a valid string (not binary data if using plain text)

Integration Not Appearing in UI

Problem: Integration created but not visible.

Possible Causes:

  • Integration soft-deleted (deleted_at is set)
  • RBAC permission issue
  • UI filter applied

Solution:

  1. Check integration status via API: GET /admin-service/admin/integrations
  2. Verify user has platform.settings permission
  3. Check browser console for errors
  4. Verify integration is not filtered by type

Cannot Decrypt Existing Credentials

Problem: Error decrypting credentials after key change.

Cause: The encryption master key was changed, but existing encrypted credentials were encrypted with the old key.

Solution:

  • DO NOT change the encryption key if you have existing integrations
  • If you must change the key, you must:
    1. Export all integration credentials (decrypt with old key)
    2. Update the encryption key
    3. Re-create all integrations (encrypt with new key)
    4. Or implement a key rotation mechanism

Prevention: Use a key management service that handles key rotation automatically.

Future Enhancements

Planned Features

  1. AWS KMS Integration – Use AWS KMS for key management in production
  2. Key Rotation – Automatic key rotation without downtime
  3. Multi-Key Support – Support for multiple encryption keys (for migration)
  4. Credential Rotation – Automated credential rotation for integrations
  5. Connection Testing – Test integration connections before saving
  6. Integration Templates – Pre-configured templates for common integrations

Migration to Secrets Management Service

When moving to a 3rd party secrets management service:

  1. Export current credentials (decrypt with current key)
  2. Store in secrets management service (HashiCorp Vault, AWS Secrets Manager, etc.)
  3. Update encryption service to fetch keys from the service
  4. Re-encrypt existing credentials with new key source
  5. Test thoroughly before removing old key
  • AWS Cost Explorer Setup – AWS-specific integration setup
  • Security Architecture – Overall security design

Support

For issues or questions:

  1. Check service logs: docker-compose logs admin-service
  2. Review audit logs: Query platform_integration_audit_log table
  3. Check encryption service logs for initialization errors
  4. Verify RBAC permissions for your user account