Technical enablement · 07

Integrations & provider connections

How {{product.name}} connects to the systems around it: the AI providers whose spend it reads, the LiteLLM gateway that reports usage, and Microsoft Entra ID for sign-in. It also gives the recipe for adding a provider.

The model: ports and adapters

Product code talks to one product-owned interface, the ProviderAdapter contract in lib/tdal/adapters/base.ts. Each provider implements it in its own file and writes into one unified schema that uses FOCUS 1.5 field names (ADR 006). Adding a provider is therefore adding one adapter file and registering it; the schema does not change. The registry is also the only list the connections page consults, so a provider cannot be syncable in one place and unknown in another.

Integration inventory

Provider connections

A connection is a named record per provider account, with a scope and a credential. It is created disconnected; verification promotes it to active, and only active (and errored) connections are synced. verify() runs on save and edit, reports the granted scope, and the Test connection button re-runs it.

The platform requests read-only access and never model-invocation scope. The in-app "What do I need?" guide is generated from lib/connections/credential-fields.ts; change requirements there, not in the UI.

How a credential is supplied

• Entered in the app. The value is encrypted at rest with AES-256-GCM using CREDENTIAL_ENCRYPTION_KEY; the connection stores only that a value exists.
• By reference. Accepted forms are env:<VAR>, keyvault:<secret> and, on Azure, managed-identity:system, managed-identity:<id> or azure-default. A field decides which it is by its value; a malformed reference is rejected rather than stored as a secret.
• Never in the repository, and never in these pages.

Azure credentials

Use the azure-default reference. It resolves by chain: a managed identity where the platform provides one, else a service principal from AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET, else AZURE_ARM_TOKEN. The same connection record works in Azure, in another cloud and on a laptop; moving host means changing environment variables, not connections. Pinning to a specific managed identity works only inside Azure. AZURE_MI_CLIENT_ID selects a user-assigned identity and is deliberately separate from AZURE_CLIENT_ID, because they are different directory objects.

AWS credentials

A deployed connection needs a long-lived read-only IAM user (key ids beginning AKIA), not temporary SSO credentials, which expire within hours and would break a scheduled sync. The policy needs only the two actions above. AWS charges per Cost Explorer request, so sync frequency is a cost decision (see operations: cost). make aws-creds refreshes temporary credentials in a local .env for testing only. A least-privilege policy document is kept in docs/aws/.

Google credentials

A service account key is recognised however it was pasted (raw JSON or base64), and a token is distinguished from a key by its value. Without a billing export, Vertex cost is estimated from the public price catalogue and marked as such.

LiteLLM gateway

LiteLLM is the substrate that routes model calls; the product adds Gate A authorisation and monitoring on top and does not fork it (ADR 001).

Microsoft Entra ID

• Auth.js v5 with the Microsoft Entra ID provider; configuration in lib/auth/config.ts.
• The OAuth callback path is /api/auth/callback/azure-ad on the app's public base URL; register that full URL as a redirect URI under Authentication → Web in the app registration.
• Variables: AUTH_SECRET, AUTH_URL, AUTH_TRUST_HOST, ENTRA_CLIENT_ID, ENTRA_CLIENT_SECRET, ENTRA_TENANT_ID.
• A signed-in user must be provisioned with a role in the app; otherwise they reach a no-access page.
• Client users: a per-tenant identity provider or email one-time code is described in the build brief but is not built. Proposed approach: guest invitation to the product's Entra ID directory, with a role assigned in the app; to be confirmed.

Adding a provider

1. Confirm the port

   Read lib/tdal/adapters/base.ts and a similar existing adapter, for example openai.ts or bedrock.ts.

2. Map the capability gap

   List what the provider cannot do or does differently: whether it publishes actual cost, how it meters tokens, its rate limits and its grouping concept (for example account, resource group or project).

3. Implement and register

   Write the adapter, use the shared retry profiles in retry.ts so waiting fits inside the request ceiling, and register it in registry.ts. Add the provider to the provider enum with a migration, and describe its credential requirements in credential-fields.ts.

4. Test against recorded fixtures

   Add a contract test in tests/domain/ in the style of adapters-openai.test.ts. An adapter should not ship without one.

5. Verify on a real account, then roll out

   Create a connection, press Test connection, check the granted scope, and watch a scheduled run. Adding a column to the unified schema does not break the lock; renaming one does.

API access