Credentials & Security Design

Credential Types

Database Storage

Credentials stored in AIExt_Credentials table with two components:

• DisplayMetadata: Public configuration (JSON, plaintext) — provider name, host, port, from email
• EncryptedData: Secret data (AES-256-GCM encrypted) — passwords, API keys, tokens

Encryption Architecture

Algorithm: AES-256-GCM

• Cipher: AES-256 (256-bit key)
• Mode: GCM (Galois/Counter Mode) — authenticated encryption
• Key Derivation: Azure Key Vault (or equivalent) manages root keys
• Key Rotation: Supported via KeyVersion field

Encryption Process

1. ICredentialEncryptionService.EncryptAsync(plaintext, keyVersion)
2. Generates random IV (96-bit)
3. Encrypts with AES-256-GCM
4. Returns: IV + AuthTag + CiphertextHash

Decryption Process

1. ICredentialEncryptionService.DecryptAsync(encryptedData)
2. Extracts IV + AuthTag + Ciphertext
3. Decrypts with AES-256-GCM
4. Validates authentication tag
5. Returns plaintext or exception if invalid

Multi-Tenant Isolation

• TenantID: Every credential tied to one tenant
• Named Credentials: Each tenant configures own "email-primary" credential
• Database Index: IX_AIExt_Credentials_Name_TenantID ensures fast lookup
• No Cross-Tenant Leakage: GetCredentialByNameAsync(name, tenantID) enforces tenant isolation

Security Best Practices

Do's

• ✅ Store all credentials encrypted at rest
• ✅ Use HTTPS for all API calls to external providers
• ✅ Rotate keys regularly via KeyVersion
• ✅ Log credential access attempts (audit trail)
• ✅ Use named credentials, never hardcode secrets
• ✅ Implement rate limiting on credential lookups

Don'ts

• ❌ Never log plaintext credentials
• ❌ Never version control secrets
• ❌ Never pass credentials through query strings
• ❌ Never cache decrypted credentials across requests
• ❌ Never share credentials between tenants

Secret Rotation

If an API key is compromised:

1. Generate new API key at provider
2. Create new credential with same name in database
3. Old credential automatically becomes inactive
4. No code changes required

Audit Logging

All credential access is logged with:

• Timestamp of access
• TenantID
• Credential name
• Success/failure
• Error message (if failed)

Next Steps

• Tenant-Specific Providers
• First-Time Configuration
• Production Deployment