IntegrationService

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

Bounded context	BC-16 Connections
Platform / plane	Integration Platform / Capability & Tools
Deployment granularity	module of host · host IntegrationHost
Status	target · ConnectSoft.Factory.Integration.Connections
Built from	connectsoft-microservice · libraries: connectsoft-extensions-http-oauth2, connectsoft-extensions-saas-abstractions, connectsoft-extensions-messaging-model, connectsoft-extensions-persistence-model-nhibernate, connectsoft-extensions-audit-net
Decisions	ADR-0015, ADR-0019, ADR-0022
Traceability	FR-05 FR-01 FUX-01 FUX-02 NFR-02 NFR-03 XL-10 XL-13

Purpose and responsibilities

A connection is the Factory's named, governed way to reach one external system: a provider, an endpoint policy (allowed hosts, methods, rate limits), a credential kind and a reference to its value in Key Vault, rotation metadata, health, and grants that say which projects, agents, tools, sources and MCP servers may use it and with what narrowing. IntegrationService owns that record and the grant check; the Secret Broker (BC-40) turns a reference into a short-lived scoped credential per use. Knowledge sources, external tools, consumed MCP servers and outbound deliveries all name a connection and must hold a grant.

It absorbs the June-2026 SecretBindingService (binding a reference to a connection is a connection concern) while secret governance moves to the Secret Broker.

Context and boundaries

flowchart LR
    S["IntegrationService"]
    KnowledgeIngestionService["KnowledgeIngestionService"] -->|grpc| S
    ToolAdapterService["ToolAdapterService"] -->|grpc| S
    McpServerRegistryService["McpServerRegistryService"] -->|grpc| S
    ConnectorRegistryService["ConnectorRegistryService"] -->|grpc| S
    StudioBff["StudioBff"] -->|sync-http| S
    S -->|grpc| SecretBrokerService["SecretBrokerService"]
    S -->|grpc| PolicyEngineService["PolicyEngineService"]
    S -->|grpc| ProjectService["ProjectService"]
    S -. "ConnectionRegistered" .-> E_ConnectionRegistered(("event"))
    S -. "ConnectionStateChanged" .-> E_ConnectionStateChanged(("event"))
    S -. "ConnectionGrantChanged" .-> E_ConnectionGrantChanged(("event"))
    S -. "CredentialRotated" .-> E_CredentialRotated(("event"))

Hold "Alt" / "Option" to enable pan & zoom

Domain model

Connection — A tenant-scoped connection to one external system with its provider, endpoint policy (hosts, methods, rate limits), credential reference and kind, rotation metadata, grants and health. (catalog entry)

Field	Type	Required	Description
connectionId	guid	yes
tenantId	string	yes
name	string	yes
provider	string	yes	azure-devops
endpointPolicy	json	yes	Allowed hosts, base URL, methods, rate limits, timeouts
credentialKind	enum:CredentialKind	yes
credentialRef	string	yes	Key Vault reference; the Secret Broker resolves it per use.
rotation	json	yes	lastRotatedAt, rotationDays, nextRotationDue, rotationOwner
state	enum:ConnectionState	yes
healthy	bool	yes
lastVerifiedAt	datetime	no
version	long	yes

Invariants:

• A connection stores a credential reference and kind, never a value; verification and every use go through the Secret Broker, which issues a short-lived scoped credential.
• A connection is usable only in state Active and healthy and only by subjects with a grant; a project's source scope, an agent's release closure or a tool descriptor must name the connection and hold a grant.
• Secrets never appear in prompts, events, receipts or release manifests; receipts record the connection id and credential kind only.
• Revocation is immediate and emits an event that stops every dependent source, tool and server.

stateDiagram-v2
    Draft --> Verified : VerificationSucceeded
    Verified --> Active : Activate
    Active --> Degraded : HealthProbeFailed
    Degraded --> Active : HealthProbeRecovered
    Active --> Suspended : Suspend
    Suspended --> Active : Resume
    Active --> Revoked : Revoke
    Suspended --> Revoked : Revoke
    Degraded --> Revoked : Revoke

Hold "Alt" / "Option" to enable pan & zoom

Events: ConnectionRegistered, ConnectionStateChanged, ConnectionGrantChanged, CredentialRotated · Tables: Connections, ConnectionGrants · Repository: ConnectionRepository

erDiagram
    Connection {
        guid connectionId PK
        string tenantId
        string name
        string provider
        json endpointPolicy
        enum_CredentialKind credentialKind
        string credentialRef
        json rotation
        enum_ConnectionState state
        bool healthy
        datetime lastVerifiedAt
        long version
    }
    Grant {
        guid grantId

        enum_GrantSubjectKind subjectKind

        string subjectId

        list_string scopes

        string grantedBy

        datetime grantedAt

        datetime expiresAt

    }
    Connection ||--o{ Grant : contains

Hold "Alt" / "Option" to enable pan & zoom

stateDiagram-v2
    [*] --> Draft: RegisterConnection
    Draft --> Verified: verification through the Secret Broker succeeded
    Verified --> Active: Activate
    Active --> Degraded: health probe failed
    Degraded --> Active: recovered
    Active --> Suspended: Suspend
    Suspended --> Active: Resume
    Active --> Revoked: Revoke
    Suspended --> Revoked: Revoke
    Degraded --> Revoked: Revoke
    Revoked --> [*]

Hold "Alt" / "Option" to enable pan & zoom

Entities and value objects

Grant (entity, in Connection) — Permission for a subject to use the connection with an optional scope narrowing.

Field	Type	Required	Description
grantId	guid	yes
subjectKind	enum:GrantSubjectKind	yes
subjectId	string	yes
scopes	list:string	yes	Narrowing of the endpoint policy for this subject.
grantedBy	string	yes
grantedAt	datetime	yes
expiresAt	datetime	no

Data model and storage

Store	Role	Engine / profile	Tables
Integration store	primary	azure-sql / nhibernate-sqlserver	Connections, ConnectionGrants

Table	Owner	Columns	Indexes
dbo.Connections	Connection	12	2
dbo.ConnectionGrants	Grant	9	1

Full DDL: appendix.

APIs

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
POST	/factory/connections	RegisterConnection	factory.connections.admin	shared-write	key-header	GW-03	Register a connection with provider, endpoint policy, credential kind and a Key Vault reference (Workspace admin or Platform admin); the value is written to Key Vault by the caller or the Secret Broker flow, never posted here.
GET	/factory/connections	ListConnections	factory.connections.read	read	natural	GW-03	Connections in scope with provider, state, health, rotation due and grant counts.
POST	/factory/connections/{connectionId}/verify	VerifyConnection	factory.connections.admin	external	key-header	GW-03	Verify the credential through the Secret Broker and a provider health call (external class, read-only probe).
PUT	/factory/connections/{connectionId}/grants/{subjectKind}/{subjectId}	SetGrant	factory.connections.admin	shared-write	natural	GW-03	Grant or narrow a subject's use of the connection.
POST	/factory/connections/{connectionId}/rotate	RotateCredential	factory.connections.admin	production	key-header	GW-03	Record a rotation (new reference) and re-verify; production class because dependent systems are affected.
POST	/factory/connections/{connectionId}/revoke	RevokeConnection	factory.connections.admin	production	natural	GW-03	Revoke immediately; dependent sources, tools and servers stop.

gRPC service	Method	Streaming	Visibility	Side effects	Summary
Connections	Resolve	none	internal	read	Resolve a connection for a subject with a grant check; returns endpoint policy and a broker ticket the caller exchanges for a short-lived credential.

Resolve answers the question every dependent asks: may this subject use this connection now, and with which endpoint policy; the answer carries a broker ticket, never a credential.

Messages

Event	Topic	Scope / v	Aggregate	Consumers	Summary
ConnectionRegistered	connections.connections.v1.connection-registered	integration / 1	Connection	StudioBff, AuditService	A connection exists.
ConnectionStateChanged	connections.connections.v1.connection-state-changed	integration / 1	Connection	KnowledgeIngestionService, ToolAdapterService, McpServerRegistryService, ConnectorRegistryService, StudioBff, DashboardService, AuditService	Verified, active, degraded, suspended or revoked.
ConnectionGrantChanged	connections.grants.v1.connection-grant-changed	integration / 1	Connection	StudioBff, AuditService	A grant was set, narrowed or removed.
CredentialRotated	connections.connections.v1.credential-rotated	integration / 1	Connection	AuditService, DashboardService	A new credential reference is in force.

ConnectionRegistered payload:

Field	Type	Required	Description
connectionId	guid	yes
tenantId	string	yes
provider	string	yes
credentialKind	enum:CredentialKind	yes

ConnectionStateChanged payload:

Field	Type	Required	Description
connectionId	guid	yes
tenantId	string	yes
fromState	enum:ConnectionState	yes
toState	enum:ConnectionState	yes

ConnectionGrantChanged payload:

Field	Type	Required	Description
connectionId	guid	yes
tenantId	string	yes
subjectKind	enum:GrantSubjectKind	yes
subjectId	string	yes
change	string	yes

CredentialRotated payload:

Field	Type	Required	Description
connectionId	guid	yes
tenantId	string	yes
rotatedAt	datetime	yes

Command	Handled by	Result events	Summary
RegisterConnection	Connection	ConnectionRegistered
VerifyConnection	Connection	ConnectionStateChanged
RotateCredential	Connection	CredentialRotated, ConnectionStateChanged
RevokeConnection	Connection	ConnectionStateChanged

Event	Producer	Handler	Purpose
ProjectStateChanged	ProjectService	RevokeProjectGrants	Revoke project grants on Closing (XL-13).

Workers and jobs

Worker	Trigger	Output events	Retry	Idempotency key	Summary
ConnectionHealthProbe	schedule */10 * * * *	ConnectionStateChanged	fixed	connectionId + probeWindow	Probes Active connections with a read-only provider call through brokered credentials and marks Degraded or Active.
RotationReminder	schedule 0 6 * * *	—	fixed	connectionId + day	Raises Studio tasks and audit events for connections whose rotation is due or whose grants expire.

Actors and grains

None modelled

No grains are modelled for this item yet.

Sagas and long-running flows

None modelled

No sagas are modelled for this item yet.

Options and configuration

Section	Key	Type	Default	Reloadable	Secret	Summary
Integration:Connections	DefaultRotationDays	int	90	yes	no	Rotation period when the provider policy does not set one.
Integration:Connections	VerifyOnActivate	bool	true	no	no	A connection cannot be Active without a successful verification.

Metrics and observability

Metric	Instrument	Unit	Dimensions	Summary
connectsoft.factory.integration.connections	updown	{connection}	tenant, provider, state	Connections by state.
connectsoft.factory.integration.rotation_due	updown	{connection}	tenant	Connections past rotation due.
connectsoft.factory.integration.resolves	counter	{resolve}	tenant, provider, outcome	Resolve calls and grant outcomes.

Security

Authentication	client-credentials
Scopes	factory.connections.read (Read connections in scope.); factory.connections.admin (Register, verify, grant, rotate, revoke.)
Roles	Operator, WorkspaceAdmin, PlatformAdmin, Observer
Tenant isolation	row-filter
Data classification	confidential
Max side-effect class	production
Secrets	—

Dependencies

Outbound

Target	Kind	Purpose	Failure mode	Required
SecretBrokerService	grpc	Resolve references into short-lived scoped credentials; verification.	fail-fast	yes
PolicyEngineService	grpc	Grant policy (who may grant what to whom).	fail-fast	yes
ProjectService	grpc	Project scope for grants.	fail-fast	yes

Inbound

Target	Kind	Purpose	Failure mode	Required
KnowledgeIngestionService	grpc	Resolve for source sync.	—	yes
ToolAdapterService	grpc	Resolve for external tools.	—	yes
McpServerRegistryService	grpc	Resolve for consumed MCP servers.	—	yes
ConnectorRegistryService	grpc	Resolve for outbound deliveries.	—	yes
StudioBff	sync-http	Connection administration.	—	yes

Failure and recovery

Scenario	Detection	Recovery	Data impact	RTO (min)
Credential expired at the provider	verification or probe failure	connection Degraded; dependent calls fail fast with a rotation task	none	60
Grant missing for a caller	Resolve refused	the caller's action is Denied with reason; a Workspace admin grants	none	0

NFR targets

Target	Class value (pilot-interactive)	Override
latency_p95_ms	2000	—
availability_pct	99.5	—
throughput_rps	50	—
rpo_minutes	15	—
rto_minutes	240	—
cost_class	low	—

Deployment

Granularity	module of host · host IntegrationHost
Topologies	saas-default, hybrid, on-prem
Runtime	—; replicas —–—
Ports	—

Current implementation

ConnectSoft.Extensions.Http.OAuth2 manages tokens for HTTP clients; no connection registry, grants, verification or rotation lifecycle exists.

Later capabilities

Secret-expiry forecasting; identity-provider connections (SCIM, SSO) for generated products; connection templates per connector with pre-filled endpoint policies.

Decisions and traceability

Family	Ids
FR	FR-05, FR-01
FUX	FUX-01, FUX-02
NFR	NFR-02, NFR-03
XL	XL-10, XL-13

Related

• Integration overview · Security · ConnectorRegistryService · Tools & MCP security

• Integration Platform microservices · bounded contexts · APIs · events · data model

• Services catalog · Ownership map