Connector Credentials and Workload Identity

Enterprise problem: A customer needs scheduled agents to reach enterprise systems, but a creator’s refresh token or a broad key can outlive that person, cross team boundaries, and turn one compromised run into standing access.

Whole-course context: Day 01 produced an immutable agent version with abstract connector requirements, and Day 02 separated preview/application data from provider authority; today provisions a machine-owned connector grant before human identity and on-behalf-of access are introduced.

Today’s slice: Provision the machine or service grant first, bind it to one team and deployment, and only then distinguish optional user-delegated access; generated-application users and data remain a separate plane.

End-of-day evidence: A reviewer receives one successful scheduled-call envelope and one revoked or wrong-team denial envelope, each tied to an immutable decision and trace identifier.

Still unsolved: Per-tool argument checks, resource-specific Model Context Protocol (MCP) token exchange, human approval, and agent-to-agent delegation remain for later slices.

If machine authority is borrowed from a human or copied into runtime configuration, personnel changes and code compromise can silently widen access. A workload identity is a platform-issued identity for running software, while a service grant is downstream authority owned by a durable team principal rather than by one employee.

Use case ID	Actor	Customer job	Success outcome	Denial or recovery evidence
D03-UC-01	Team connector administrator	Provision a team-managed connector for unattended campaign automation without using a creator’s credential	The active deployment can resolve one service-owned binding with only the approved provider scopes and resources	A wrong-team resolution attempt is denied, while the approved team remains a successful positive control
D03-UC-02	Security operator	Rotate or revoke the service grant and verify that scheduled runs lose only that connector authority	New runs stop using the retired binding, a replacement can be activated without a code deploy, and unrelated connectors continue	A post-revocation call is denied with the retired binding ID; an unaffected connector call still succeeds

The primary product path is deliberately machine-first: an administrator provisions service:marketing-automation, scopes its provider account to the Marketing Drive folder, Asana project, and Slack channel, then binds it to a reviewed deployment. A personal OAuth grant, meaning consent issued through the standard delegated-authorization protocol, is optional and creates a separate user binding; it never upgrades, inherits, or replaces the service grant. An API key, a bearer secret for a provider application programming interface, is a last-resort mode rather than a workload identity.

If connector ownership and proof are implicit, administrators cannot tell whose authority a scheduled run exercised or whether offboarding actually removed it. These stories therefore require visible ownership, bounded scope, and observed negative tests rather than configuration screenshots alone.

Story ID	Use case IDs	User story	Observable acceptance conditions
D03-US-01	D03-UC-01	As a team connector administrator, I want to provision a durable service identity before enabling a scheduled agent, so that automation does not depend on any employee’s refresh token	UI and API show team owner, authentication mode, provider subject, resource and scope bounds, deployment binding, active status, and a successful scheduled-run evidence envelope; a wrong-team probe records denial
D03-US-02	D03-UC-02	As a security operator, I want to revoke or rotate one credential binding, so that compromised or obsolete authority stops without disabling unrelated work	The old binding becomes unusable for newly authorized calls, replacement activation is atomic, in-flight token expiry is bounded, and an unrelated connector produces an observed positive-control result

Two separation rules keep the stories honest:

1. configured_by identifies the human who created a schedule for audit; it is not the authorization subject of the scheduled run.
2. A generated application may map one of its app tenants or end users to a provider deployment, but that opaque mapping does not grant connector access. The provider control plane still resolves the current team, deployment, and connector grant independently.

If provisioning records only the happy configuration, a broad service account can look safe until an unauthorized team or a revoked run uses it. Each flow begins with a customer-visible action and ends with an evidence envelope, a signed record containing actor, resource, scope, precondition, expected result, observed result, environment, timestamp, and an immutable run, trace, source, or artifact identifier.

Flow ID	Use case IDs	Path	Trigger	Numbered steps	Terminal evidence
D03-FLOW-01	D03-UC-01	Happy	Administrator selects “Create team-managed connection”	1. Choose connector type and team-owned service principal.<br>2. Complete provider authorization outside the agent runtime.<br>3. Vault the refresh token or key and persist only its secret reference.<br>4. Record granted scopes, provider tenant, resource allowlist, expiry, and consent version.<br>5. Bind the active connector tools to one immutable deployment.<br>6. Launch a scheduled probe as the service principal.<br>7. Broker a transient access token directly to the adapter and discard it after use.	Signed envelope records actor service:marketing-automation, approved resource and scopes, active-binding precondition, expected allow, observed provider success, production-like environment, timestamp, run ID, decision ID, trace ID, and provider request ID
D03-FLOW-02	D03-UC-01	Denied	Administrator runs the built-in “Test another team” negative probe	1. Construct an otherwise valid run for an unbound team.<br>2. Resolve current team membership and connector-team access.<br>3. Fail closed before secret retrieval.<br>4. Run the same probe for Marketing as a positive control.	Paired envelopes record the wrong-team actor, connector resource, requested scope, absent team grant, expected and observed connector_not_available_to_team, environment, timestamp, immutable decision and trace IDs, plus the Marketing success control
D03-FLOW-03	D03-UC-02	Recovery	Security operator selects “Rotate credential”	1. Authorize a new provider grant for the same durable service principal.<br>2. Store a new secret version and validate its exact scope.<br>3. Atomically activate the new binding and retire the old binding.<br>4. Start a new scheduled probe.<br>5. Confirm no runtime, prompt, browser, or log received either credential.	Rotation envelope records operator, binding resource, old and new scope sets, active-old precondition, expected cutover, observed new-binding success, environment, timestamp, immutable rotation artifact, decision ID, and trace ID
D03-FLOW-04	D03-UC-02	Denied	Security operator selects “Revoke and verify”	1. Mark the binding revoked and revoke it at the provider.<br>2. Invalidate broker caches and deny new token minting.<br>3. Attempt a new scheduled call with the retired binding reference.<br>4. Call an unrelated connector as a positive control.<br>5. Retain redacted evidence without retaining token material.	Paired envelopes record service actor, retired binding and unaffected resource, scopes, revoked precondition, expected denial and control success, observed credential_binding_revoked and provider success, environment, timestamp, immutable run, decision, trace, and provider request IDs

Why the runtime stays credential-free

The hosted runtime receives a short-lived run token, immutable workflow version, and filtered tool catalogue. It does not receive refresh tokens, API keys, connector secrets, or the right to select an arbitrary credential. The credential broker resolves an authorized binding only after current team, deployment, connector, tool, and scope checks, then hands a transient access token directly to the connector adapter. Prompt text, model output, Python code, browser JavaScript, agent state, and event logs never see the credential.

If control-plane metadata, runtime identity, and downstream secrets share one trust boundary, compromising any agent process can expose every connector. The design separates the provider control plane that owns grants and deployments, the hosted-runtime boundary that owns execution and workload identity, the generated-application plane that owns app users and domain data, and the source-owned enterprise system that makes the final authorization decision.

Use case ID	Entry point	Responsible services	Authoritative store	Failure evidence
D03-UC-01	“Create team-managed connection” and scheduled-run test	Connector Administration API validates ownership and policy; Identity Service issues the workload subject; Credential Broker retrieves the secret only after authorization; connector adapter calls the provider; Evidence Service signs results	Connector Registry owned by Connector Service; secret bytes remain in the Credential Vault; provider account and ACLs remain authoritative at the enterprise provider	connector_not_available_to_team, no_authorized_credential_binding, provider scope denial, or evidence showing any secret exposed to runtime
D03-UC-02	“Rotate credential” or “Revoke and verify”	Lifecycle Service stages and atomically activates versions; Credential Broker invalidates caches; provider revocation endpoint removes source authority; scheduler launches fresh probes; Evidence Service pairs denial with positive control	Credential Binding Registry owned by Connector Service for status and version; Vault for secret versions; provider authorization server for actual grant revocation	credential_binding_revoked, stale version used after cutover, provider token still mintable after revocation, or unrelated connector control failure

Workload identity and stable trust anchors

A workload identity must be ambient: the compute platform maps the running workload to a stable cloud or service identity without embedding a key. An internal cluster issuer is only a bootstrap and must not become the external trust anchor; cluster rebuilds would otherwise break every customer grant. Place the stable per-environment service identity in a dedicated identity account or project, separate from routinely rebuilt compute.

This is also the correct pattern for a connector adapter that opens a customer-managed database. A stored password proves only knowledge of a long-lived, copyable string; an identity-based database token proves which workload is connecting now and expires within minutes or an hour. Mint that token in the database driver from ambient workload identity, refresh it before expiry, require encrypted transport, and map it to a narrowly scoped database user rather than the owner or superuser. Authentication happens when a connection opens, so a warm per-tenant connection pool reuses authenticated connections and keeps steady-state token minting cheap without a sidecar. Tokens and temporary credentials are never logged.

For cross-account access in the same cloud, the customer can use native trust to let the stable identity assume a customer-owned, connect-only role. Across clouds, federation exchanges a token from the provider’s identity domain for short-lived credentials in the customer domain. In both cases the customer owns and can delete the target principal, the platform holds no durable customer credential, and a per-customer correlation value or exact subject-and-audience pin closes the confused-deputy risk of using a shared caller for the wrong tenant. A negative onboarding test must prove that an unlinked tenant cannot assume the role.

Cache the bridged customer-domain credential only for its short lifetime, roughly an hour, and mint the shorter database token from it as connections are established. Separating the infrequent cross-domain bridge from cheap per-connection token minting avoids putting federation latency on every query. Before onboarding, surface customer organization guardrails that block outside identities; otherwise a correct trust policy can fail late with an opaque provider error.

Shared service identities and optional user grants

One service identity per environment is usually simpler than creating one identity per customer, provided each customer scopes its own principal and the platform selects a tenant-specific connection record. This concentrates reach in a high-value principal, so least privilege, close monitoring, per-customer pinned proof, and independent revocation are mandatory. Onboarding becomes an idempotent row: publish the stable identity, let the customer create a scoped grant, store secret-free connection metadata, then validate link, bridge, token minting, and connection.

Only after that machine path is complete should the product offer user-level OAuth. A user binding preserves the provider’s user ACLs and human attribution but can expire, requires consent, and cannot power unattended work after that user leaves. An API key is a last resort when the provider lacks stronger delegation; effective authority is the intersection of agent capability, key team scope, endpoint policy, resource bounds, and provider ACLs.

If credentials are stored beside connector metadata or tenant isolation is represented by copied secrets, deletion becomes ambiguous and accidental disclosure becomes likely. The model keeps durable ownership and lifecycle state in the control plane, secret bytes in a vault, runtime tokens ephemeral, and enterprise resources authoritative at their source.

Generated-application database: Not created in this slice — connector grants, workload principals, deployment bindings, lifecycle jobs, and evidence are durable provider control-plane records; generated-application tenants use only opaque deployment references and gain no connector authority.

Record or entity	Store and owner	Primary key	Foreign key or opaque reference	Tenant key	Material constraint	Lifecycle and deletion	Use case IDs
ConnectorInstance	Connector Registry, owned by Connector Service	connector_instance_id	created_by_user_id is a provider-user FK; MCP resource URI is an opaque source reference	organization_id	Authentication mode and ownership scope are immutable after first active binding; status must be active for resolution	Create in draft, activate after validation, disable before delete; retain tombstone and policy digest for audit	D03-UC-01, D03-UC-02
ConnectorTeamAccess	Connector Registry, owned by Connector Service	(connector_instance_id, team_id)	Local FKs to ConnectorInstance and provider Team	organization_id	Unique connector-team pair; approver must hold current connector-admin role	Create on approval, revoke independently, retain approver and revocation evidence under audit policy	D03-UC-01, D03-UC-02
ServicePrincipal	Identity Registry, owned by Identity Service	principal_id	provider_subject is an opaque reference to the external identity	organization_id	Principal type is service; owner team and environment are required; creator is audit metadata only	Provision before scheduling, disable on team retirement, retain stable ID and ownership history, delete after dependent grants expire	D03-UC-01, D03-UC-02
CredentialBinding	Connector Registry, owned by Credential Broker	credential_binding_id	Local FK to ConnectorInstance and ServicePrincipal; secret_reference is opaque to Vault	organization_id	Granted scopes must be a subset of connector policy; one active version per connector-principal pair; secret material prohibited	Create version, activate atomically, expire, rotate or revoke; Vault crypto-shreds secret after retention while binding tombstone remains	D03-UC-01, D03-UC-02
DeploymentConnectorBinding	Deployment Store, owned by Deployment Service	deployment_connector_binding_id	Local FKs to immutable DeploymentVersion and ConnectorInstance	organization_id	Enabled tools and resources may only narrow connector policy; inactive deployments cannot resolve bindings	Create during review, freeze with deployment version, supersede on redeploy, retain with release audit, delete on organization erasure	D03-UC-01, D03-UC-02
CredentialLifecycleJob	Lifecycle Store, owned by Connector Service	lifecycle_job_id	Local FK to CredentialBinding; provider job ID is opaque	organization_id	Idempotency key is unique per requested operation and binding version; terminal state is append-only	Create for rotate or revoke, retry safely, retain terminal outcome, purge operational payload after evidence retention	D03-UC-02
ConnectorEvidenceEnvelope	Append-only Evidence Store, owned by Evidence Service	evidence_id	Opaque run, decision, trace, provider request, and artifact references	organization_id	Required actor, resource, scope, precondition, expected, observed, environment, timestamp, and immutable ID fields; token material forbidden	Append on every test and call decision, seal digest, retain per audit policy, legal-hold when required, then cryptographically erase payload and retain tombstone	D03-UC-01, D03-UC-02

Credential binding fields that matter

The durable binding stores principal type and ID, secret reference, issuer, provider subject and tenant, granted scopes, permitted resources, status, expiry, consent version, last successful use, and revocation state. It never stores the decrypted refresh token in ordinary application data. Revocation is effective in two places: the control plane denies future resolution immediately, while the source provider invalidates the underlying grant; bounded transient tokens expire naturally.

Review checklist

• [ ] Team-managed service authority exists and passes positive and wrong-team tests before optional user OAuth is enabled.
• [ ] No creator identity is the subject of a scheduled run; configured_by remains audit-only.
• [ ] Runtime, model, prompt, Python, browser, state, and logs never receive refresh tokens, keys, or brokered access tokens.
• [ ] Stable identity outlives compute; customer-owned target principals are least-privilege and independently revocable.
• [ ] Rotation and revocation evidence includes an unaffected positive control and immutable identifiers.