Documentation / Relay Agent

Relay Agent

Reach identity systems in remote networks with outbound-only connectivity. No inbound firewall rules, no VPN tunnels — just a lightweight Windows service that connects back to your central Identity Mesh instance.

Architecture

The relay agent sits in the remote network alongside the identity source. It initiates an outbound HTTPS connection to the central Admin API using SignalR, then waits for import and export commands.

Remote Network                          Central Network
┌─────────────────────┐                 ┌──────────────────────────────────────┐
│                     │                 │                                      │
│  Identity Source    │                 │  Admin API                           │
│  (AD, SQL, etc.)    │                 │  ┌──────────────────────────────┐    │
│        ▲            │                 │  │  /hubs/relay (SignalR Hub)   │    │
│        │            │                 │  └──────────────▲───────────────┘    │
│        │ LDAP/SQL   │                 │               │                      │
│  ┌─────┴──────────┐ │  outbound       │               │                      │
│  │ Relay Agent    │──┼──HTTPS────────┼───────────────┘                      │
│  │ (Windows Svc)  │ │  SignalR        │                                      │
│  │ Connectors/    │ │                 │  Sync Engine ──▶ Projection ──▶ DB   │
│  └────────────────┘ │                 │                                      │
│                     │                 └──────────────────────────────────────┘
└─────────────────────┘

Outbound Only

The agent connects outward over HTTPS. No inbound ports need to be opened in the remote network's firewall.

Connector Agnostic

The same connector DLLs used by the sync engine work in the relay agent. Any IIdentityConnector implementation is supported.

Centrally Managed

Deployment Guide

Prerequisites

Ensure the remote server meets the minimum requirements.

Windows Server 2019 or later
.NET 8 Runtime installed on the remote server
Outbound HTTPS connectivity to the central Admin API
Network access from the remote server to the target identity source (AD, SQL, etc.)

Install the Relay Agent

Copy the published relay agent binaries to the remote server.

1. Copy the IdentityMesh.Relay.Agent binaries to a directory such as C:\Program Files\IdentityMesh\RelayAgent\
2. Register the Windows service: sc create IdentityMeshRelayAgent binPath="..."

Register the Agent

Use the Admin UI to register the agent and obtain credentials.

1. Open the Admin UI and navigate to Relay Agents
2. Click Add Agent and provide a descriptive name (e.g., "Branch-Office-West")
3. Save the returned Agent ID and API Key immediately — the API key is shown only once

Copy Connector DLLs

Place the connector assemblies the agent needs into the Connectors/ subfolder.

1. Create a Connectors\ folder under the agent install directory
2. Copy the relevant connector DLLs (e.g., IdentityMesh.Connectors.ActiveDirectory.dll)
3. Only include connectors needed for identity sources in this remote network

Configure appsettings.json

Set the hub URL and credentials from the registration step.

appsettings.json

Set Relay:HubUrl to the full URL of the Admin API relay hub (e.g., https://api.contoso.com/hubs/relay)

Set Relay:AgentId to the GUID returned during registration

Set Relay:ApiKey to the API key from registration

Optionally set Relay:AgentName (defaults to the machine name)

Start the Service

Start the Windows service. The agent connects to the Admin API, registers itself, and begins sending heartbeats.

1. Start the IdentityMeshRelayAgent Windows service
2. The agent reports its loaded connector types, machine name, and version to the hub
3. The Admin API marks the agent as Online

Assign Connectors

Switch connectors from direct mode to relay mode by assigning them to the agent.

1. Open the Admin UI and navigate to Connectors
2. Edit the connector that targets a system in the remote network
3. Set the Relay Agent dropdown to the registered agent
4. Save — future imports and exports for this connector will be executed by the relay agent

Verify

Confirm the agent is connected and operational.

Check the Relay Agents page — the agent should show Online status
Verify the loaded connector types match the DLLs you deployed
Trigger a manual import on the assigned connector and confirm objects flow through
Check connector logs to verify relay log entries are arriving

Security

API Key Authentication

Each agent receives a unique API key at registration. The key is SHA-256 hashed before storage. The agent sends the raw key in the X-Agent-ApiKey header on every connection. The key is displayed only once at creation — if lost, delete the agent and re-register.

TLS Encryption

All communication uses HTTPS (TLS 1.2+). The relay hub URL must use the https:// scheme. No identity data is transmitted in plaintext.

Centralized Secrets

Connector credentials and connection strings remain in the central IdentityMesh database. They are transmitted to the agent only during active operations over the encrypted SignalR channel. No secrets are stored on the relay agent machine.

Heartbeat Monitoring

Agents send a heartbeat every 30 seconds. If no heartbeat is received for 2 minutes, the Admin API automatically marks the agent as Offline and will not dispatch operations to it.

API Reference

Agent Management

Method	Path	Description
`GET`	/api/relay-agents	List all registered relay agents with status
`POST`	/api/relay-agents	Register a new agent (returns agentId and one-time apiKey)
`DELETE`	/api/relay-agents/{id}	Delete agent and unassign its connectors

Relay Operations

Method	Path	Description
`POST`	/api/relay/import	Dispatch an import operation to a relay agent
`POST`	/api/relay/export	Dispatch an export operation to a relay agent
`POST`	/api/relay/cancel/{correlationId}	Cancel a running relay operation

Need Help Deploying a Relay Agent?

Our team can help you plan and deploy relay agents across your remote sites.

Contact Support Getting Started Guide