How the 365TUNE Hybrid Agent works

This article explains how the agent fits together, how a server is linked to your tenant, how an approved change travels from the portal to Active Directory, and how the agent is monitored. For what the agent is, read What is the 365TUNE Hybrid Agent; for the controls that protect your directory, read How the 365TUNE Hybrid Agent is secured.

Architecture at a glance

The architecture has three zones: your local network, the Microsoft cloud and the 365TUNE cloud. Every connection starts in the local network and goes outward; nothing connects inbound to the server.

The three zones hold:

Local network. An IT administrator runs the installer on a member server. The installer and its elevated registration tool talk to Active Directory once, to create the service account and its delegation, and to 365TUNE to register. The agent service then runs as the group managed service account with a non-exportable key and a protected configuration, and writes the allowed attributes in Active Directory.
Microsoft cloud. Microsoft Entra ID handles the Microsoft Work ID sign-in and issues a one-hour token. Azure Service Bus carries signed commands to each agent on its own queue and results back.
365TUNE cloud. The 365TUNE agent API validates tokens, maps the sign-in to your tenant, registers agents, serves configuration and receives heartbeats, audit records and renewal requests. A key vault and certificate authority hold the signing secrets, issue agent certificates and publish the revocation list.

Every link from the server is outbound TLS 1.2 or 1.3 with revocation checking. The agent authenticates to the API and to the queue with its own certificate; the administrator's identity is used only to register.

Installation and registration

The installer is a signed Windows setup package that you run on a domain-joined member server or domain controller. Installation and registration are two separate acts: installing puts the files and the service in place; registering, which needs a 365TUNE sign-in, is what connects the server to your tenant. Nothing talks to 365TUNE until you sign in. The step-by-step guide is How to install and set up the 365TUNE Hybrid Agent.

Before anything is installed, the installer runs read-only checks on the server. A failed check blocks the install until you fix the cause and choose Check again. A warning does not block the install; it names something registration will need. Nothing is written to Active Directory by the checks.

Check	Why it matters
Windows session is a domain account	The registration needs directory rights that a local or cloud-only account does not have
Server is joined to a domain, and a writable domain controller answers	The agent cannot operate on a workgroup machine
Clock within tolerance of the domain controller	Kerberos and signed commands both depend on time
Windows session is a Domain Admin or Enterprise Admin (warning only)	Creating the service account and its delegation needs these rights once, at registration only. If the session lacks them, the Connect step asks for a separate Active Directory administrator account for that registration
Key Distribution Service root key present and usable	Required for a group managed service account
Active Directory PowerShell module installed	Used for the service account ceremony
Embedded browser runtime present	The sign-in page runs inside the installer
login.microsoftonline.com and app.365tune.com reachable over HTTPS	Needed for sign-in and registration. The running agent also needs your Service Bus namespace, which the checks do not test (see Network requirements)
Server is not a domain controller (warning only)	Suitable for a lab. In production use a member server, so that no third-party service runs on a domain controller
.NET 8 runtime present	The agent runs on it. The runtime is included in the setup package and can be installed from the same screen; nothing is downloaded

Install the agent on a domain-joined member server in production. A domain controller is suitable for a lab only, because running a third-party service there places it on one of your most sensitive hosts.

Registration then runs in this order, each step reported on screen:

You choose the Active Directory domain, choose Sign in with 365TUNE, and sign in with your Microsoft Work ID, the work account you use on the 365TUNE portal. Sign-in happens on Microsoft's own page inside the installer; 365TUNE never sees your password.
The installer hands the sign-in token to an elevated registration tool over a local protected channel that only your session and local administrators can open. You approve the elevation prompt. If your Windows session is not a Domain Admin, the separate administrator account you entered travels the same way, never on a command line or in a log.
The tool asks 365TUNE which tenant your account may register an agent for, and shows the tenant's name.
The tool checks that this forest belongs to that tenant (see Who can register an agent) and stops if it cannot prove it.
Only now is a 4096-bit RSA key pair generated, non-exportable, in the Windows machine key store. A certificate signing request goes to 365TUNE; nothing else leaves the server.
365TUNE issues the agent's certificate and returns the queue details and your configured organisational units and attribute list. The tool installs the certificate.
The tool creates the group managed service account, grants it only what the agent needs, applies the delegation on your authorised organisational units, writes the protected configuration file, and starts the service.
The service sends its first heartbeat and the installer shows the tenant name and agent id. Reopening the Start menu entry later shows the Connected screen with the live status.

If any step fails the installer shows one sentence explaining why, with a Read more link to the troubleshooting page and a button to copy the full message for support. A failure before step 5 leaves no key, certificate or service account behind. The installed files stay, and you can register later from the Start menu entry. The administrator rights used in step 7 are used once; the running service never has them.

Tip: Select the authorised organisational units and the attribute list in the 365TUNE portal before you register. Registration stops with "no Authorised OUs configured" if none is selected, and an agent with no authorised units refuses every command.

How a change reaches Active Directory

A change starts in the 365TUNE portal, for example a mover policy that updates a user's department and manager after an HR change is approved. From there:

365TUNE signs a command naming the user, the action, the attributes and their new values, with an identifier, an issue time and a sequence number, and places it on a queue dedicated to your agent in Azure Service Bus.
The agent collects it. The agent connects outbound to the queue with its own certificate; no inbound connection is ever made to your server. Nothing on the queue is trusted yet.
The agent verifies before it reads. The signature must match the secret issued at registration; the command must be younger than the configured maximum age; its identifier must not have been seen before, including across service restarts; and its sequence number must be higher than the last one accepted. A command that fails any of these is rejected, logged as a possible replay, and never executed.
The agent checks scope. The action must be one you have allowed; the target user must sit inside one of your authorised organisational units; every attribute in the command must be on your attribute allow-list. The organisational units, attribute list and allowed actions come from your portal configuration and are refreshed every few minutes, so removing an attribute in the portal takes effect at the next refresh without a restart. If the portal shows no authorised organisational units, the agent refuses every command.
The agent applies the change in Active Directory through its service account: an attribute write, an enable, disable or unlock, a password reset, a group membership change or a new user, each only within the capabilities, attributes and organisational units delegated to it. Active Directory enforces that limit even if the agent were somehow asked for more.
The agent reports. A signed result goes back on the results queue, and an audit record with the command id, target, attributes, outcome and time is sent to 365TUNE and written to the Windows Application event log on the server. Audit records that cannot be delivered are queued and retried, never dropped.

The portal, the queue, the agent and the directory each enforce the scope independently. A compromised portal account, a compromised queue, or a compromised server each gets no further than the next layer allows.

Network requirements

The agent needs outbound HTTPS on port 443 only. No inbound port is opened, no firewall rule is needed for traffic towards the server, and no VPN or relay is installed.

Destination	Used by	Purpose
login.microsoftonline.com	Installer, at registration	Microsoft sign-in
app.365tune.com	Installer, registration tool, agent	Tenant check, registration, configuration, heartbeat, audit, certificate renewal
Your tenant's Service Bus namespace (*.servicebus.windows.net, AMQP over WebSockets on 443)	Agent	Command and results queues
Your domain controllers	Installer, registration tool, agent	LDAP and Kerberos, inside your network

The installer uses the server's system proxy settings and default credentials for the proxy. TLS inspection by a corporate proxy works as long as the proxy's root certificate is trusted by the server and the proxy passes JSON error responses through unchanged; the agent verifies certificate chains and checks revocation, so a proxy that serves an untrusted certificate or blocks revocation lookups will stop it. Certificate pinning is deliberately not used, so that enterprise inspection remains possible.

The installer's server checks confirm that the Microsoft sign-in service and app.365tune.com are reachable before installation, and name the one that failed. The Service Bus namespace is not part of those checks, so confirm it on your proxy and firewall before registering.

Allow outbound HTTPS to all three destinations before you register: login.microsoftonline.com, app.365tune.com and your tenant's Service Bus namespace. The installer tests only the first two. If a TLS inspection proxy is in the path, the server must trust its root certificate, and the proxy must not rewrite error responses or block revocation lookups.

Monitoring, renewal and revocation

On the server. The service writes to the Windows Application event log under the source 365TuneHybridADAgent: start and stop, each command's outcome, rejected commands with the reason, certificate renewals and configuration refreshes. A registration record and a status record in the registry hold the agent id, tenant, certificate expiry and the last heartbeat; the Start menu entry reads them to show the Connected screen.

In the portal. Each tenant lists its agents with server name, registrant, registration time, certificate expiry, last heartbeat and state. Administrators are notified of every new registration. The audit trail shows every command and its result.

Certificate renewal. From 30 days before expiry the agent requests a new certificate for a new key, over its existing mutual TLS connection. 365TUNE refuses a renewal that names a different tenant. The new certificate is used on the next connection; the old one expires.

Revocation. An administrator can revoke an agent in the portal. In one action the certificate is placed on the revocation list, the command signing secret is invalidated and the queue access is removed; the agent's next heartbeat and configuration call are refused and it stops processing. Revoke when a server is retired, rebuilt or suspected compromised, before you reinstall; a new registration on the same server creates a new agent identity.

Revoke the agent in the portal before you retire, rebuild, re-image or hand over the server. Uninstalling alone does not revoke it. A new registration on the same server creates a new agent identity and does not reuse the old one.

Frequently asked questions

What happens if the server is turned off or loses connectivity? Nothing is lost. Commands wait on the queue until the agent returns, are rejected if they have passed their time limit, and audit records that could not be sent are retried. The portal shows the last heartbeat so you can see an agent is offline.

Can I see what the agent did? Yes: every command and its outcome is in the Windows Application event log on the server and in the audit trail in the portal.

Where is the troubleshooting guide? Every message the installer can show, with its cause and fix, is on the page Troubleshooting 365TUNE Hybrid Agent Installation and Registration. The installer links to it from every error it shows.