Identity Stack Agent

Identity Stack Agent connects Identity Stack to your on-premises Active Directory. You install it on Windows servers in your domain. See Install Identity Stack Agent for the installation procedure.

Services

Identity Stack Agent installs two Windows services on each host:

Service	Account	Function
Identity Stack Agent	LocalSystem	Holds the connection to Identity Stack. Installs updates. Starts and stops the connector.
Identity Stack Agent AD Connector	Your Group Managed Service Account (gMSA)	Reads and changes objects in Active Directory.

This design separates the privileges:

• The agent service has no permissions in Active Directory.
• The connector has only the permissions that you give the gMSA. It cannot change the program files, the host key, or the service configuration.

Named pipe

The two services communicate with gRPC through the local named pipe identitystack-connector. The connector has no network listener. The pipe has these protections:

• Access. Only LocalSystem and the gMSA have access to the pipe. The pipe is not available on the network.
• Pipe name. The connector creates the pipe as the first instance of the name. If a different process already has the name, the connector does not start.
• Identity of the connector. For each new pipe connection, the agent service finds the process that serves the pipe. The process must run as the configured gMSA. If it does not, the agent service closes the connection and sends no command.

Commands

Identity Stack controls the agent with commands. A command has a method name, a JSON payload, and a timeout.

Command flow

1. Identity Stack API finds the primary host of your organization. The host must have a connection that was active in the last 12 minutes.
2. Identity Stack API sends the command to the agent service through the open connection.
3. The agent service compares the method name with its fixed list of methods. It rejects all other methods. The connector never receives them.
4. The agent service sends a directory command to the connector through the named pipe. It does a host command, such as an update, itself.
5. The connector does the operation in Active Directory over LDAPS.
6. The result goes back to Identity Stack API through the agent service.

Each directory command uses the permissions of the gMSA. See Grant permissions to the gMSA for the permissions to grant.

Timeouts and errors

• Each directory command has a timeout of 15 seconds.
• The agent service waits up to 5 seconds for the connector to accept the pipe connection. If the connector does not accept, the command fails.
• If the host has no active connection, or does not reply before the timeout, the command fails.
• Identity Stack does not send a failed command again.

If a read command fails with an unexpected error, the connector returns only a general error message. The full details stay in the connector log on the host. If a write command fails, the result contains an error code and the error details.

The agent service sends a status report to Identity Stack when it connects, and then every 5 minutes. The report contains the version of the agent and the state of the connector service.

Active Directory connection

Every connection is a SASL bind using Windows Negotiate (GSS-SPNEGO), signed in as the gMSA, over LDAPS on TCP port 636. The connector uses System.DirectoryServices. The connection has these properties:

• Bind. The connector does not use a simple bind. Negotiate selects Kerberos. If Kerberos is not available, Negotiate uses NTLM.
• Credentials. The connector sends no user name or password. The host stores no password for Active Directory. Windows manages the password of the gMSA.
• Encryption. The connection uses TLS from the start. The connector does not use LDAP on port 389 or StartTLS.
• Certificate. Windows validates the certificate of the domain controller. The host must trust the certification authority that issued it.
• Connection lifetime. The connector opens a new connection for each command and closes it after the command.

How the connector binds

The connector runs as the gMSA. Windows gives the connector process the Kerberos credentials of the gMSA. The connector uses these credentials for the bind. It does not send a user name or a password in the bind request.

For each directory command, the connector does these steps:

1. It opens a TLS connection to a domain controller on port 636. Windows validates the certificate of the domain controller.
2. It binds with Negotiate as the gMSA. Negotiate gets a Kerberos ticket for the LDAP service on the domain controller.
3. It finds the user by the sAMAccountName, the security identifier (SID), or the distinguished name. The search starts at the configured container.
4. It reads or changes the user.
5. It closes the connection.

Active Directory checks each read and each change against the permissions of the gMSA. The connector can only do what you delegate to the gMSA. If you remove a permission, the next command that needs it fails.

The connector never knows the password of the gMSA. Active Directory changes that password automatically.

Configuration

The connector reads its target from the registry key HKEY_LOCAL_MACHINE\SOFTWARE\IdentityStack\Agent\DirectoryService:

Value	Function
Domain	The DNS name of the domain, for example domain.local. The connector connects to Domain:636. The installer sets the value from the domain of the host. An upgrade keeps the current value.
Container	Optional. The distinguished name where user lookups and the OU list start, for example OU=Users,DC=domain,DC=local. If it is empty, they start at the root of the domain. A search for users by attribute value always searches the full domain.

The installer does not install the agent on a host that is not in a domain.

At start, the connector makes sure that the Domain value exists and that it can write to its log folder. If one of these checks fails, the connector does not start.

Network requirements

Identity Stack Agent makes outbound connections only. It needs no inbound ports.

Destination	Port	Purpose
The control plane URL that you entered at installation, for example api.identitystack.dk	TCP 443 (HTTPS)	Enrollment, authentication, and the connection to Identity Stack
*.service.signalr.net	TCP 443 (HTTPS)	The connection to Identity Stack
identitystacksharedst.blob.core.windows.net	TCP 443 (HTTPS)	Download of updates
Your domain controllers	TCP 636 (LDAPS)	Active Directory operations

The connection to Identity Stack stays open. If the connection breaks, the agent connects again automatically.

Hosts

Install Identity Stack Agent on two or more hosts. Then you can install operating system updates on one host while the other host operates.

One host is the primary host. Identity Stack sends all operations to the primary host. An Identity Stack administrator can make a different host the primary host.

Enrollment and authentication

The installer enrolls the host with an enrollment token:

• The token is valid for one host only.
• The token expires after 7 days.
• The token is not stored on the host.

At enrollment, the agent creates a key pair on the host. The private key cannot be exported. When the host has a TPM 2.0 chip, the TPM stores the key. The agent stores a self-signed certificate with the name Identity Stack Agent in the local computer certificate store (LocalMachine\My). Identity Stack stores only the certificate.

The private key never leaves the host. To authenticate, the agent signs a single-use challenge from Identity Stack with the private key. Identity Stack then issues a session token that is valid for 60 minutes. The agent uses the token to open the connection to Identity Stack. Each time the agent connects again, it gets a new session token.

Updates

Identity Stack sends updates to the agent. You do not need to install updates on the host. Before the agent installs an update, it verifies the installer:

• The SHA-256 hash must match the value from Identity Stack.
• The Authenticode signature must be valid.
• The package must be signed by Identity Stack A/S.

The installer updates both services together. To go back to an earlier version, Identity Stack sends the signed installer of that version.

Logs

Each service writes logs to a logs folder in the installation folder. The logs can contain user names from Active Directory. The installer gives the gMSA write access to the connector log folder. All other access comes from the permissions of the installation folder.