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

The numbers are the steps below. The result goes back on the same path (step 6). The agent opens the TCP 443 connection. The host needs no inbound ports.

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.
• 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 finds the domain that issued the security identifier (SID) of the user. See Multiple domains and forests.
2. It opens a TLS connection to a domain controller of that domain on port 636. Windows validates the certificate of the domain controller.
3. It binds with Negotiate as the gMSA. Negotiate gets a Kerberos ticket for the LDAP service on the domain controller.
4. It finds the user by the SID.
5. It reads or changes the user.
6. 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 of the host, for example domain.local. The commands that do not find an existing user, such as the OU list, connect 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 the OU list starts, for example OU=Users,DC=domain,DC=local. If it is empty, the list starts at the root of the domain. A lookup by SID and a search for users by attribute value always search 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.

Multiple domains and forests

The connector can find users in more than one domain. It finds each user by the SID, in the domain that issued the SID. That domain can be:

• The domain of the host.
• A different domain in the forest of the host.
• A domain in a different forest that trusts the forest of the host.

You do not install Identity Stack Agent in the other domains. The same hosts serve all domains.

How the connector finds the domain

Identity Stack sends the SID of the user with each command. Identity Stack gets the SID from the onPremisesSecurityIdentifier attribute of the user in Microsoft Entra ID. Microsoft Entra Connect synchronizes this attribute from Active Directory. If a user has no SID, Identity Stack does not send the command and shows an error.

For each SID, the connector does these steps:

1. Windows translates the SID to the name of the domain. For a SID from a different forest, the domain controller of the host follows the forest trust.
2. The domain controller locator finds the DNS name of that domain.
3. The connector connects to a domain controller of that domain over LDAPS. It searches the full domain for the SID.

The connector keeps the DNS name of each domain in memory. It does steps 1 and 2 one time for each domain. If you rename a domain, restart the Identity Stack Agent AD Connector service.

If no trusted domain knows the SID, or the domain has no user with the SID, the command fails.

Requirements for each domain

Do these steps for each domain that has users:

• Trust. For a different forest, make sure that the forest trusts the forest of the host. If the trust uses selective authentication, give the gMSA the Allowed to authenticate permission on the domain controllers of that forest.
• Permissions. Give the gMSA the necessary permissions in the domain. See Grant permissions to the gMSA.
• Network. Make sure that the host can connect to the domain controllers of the domain on TCP port 636. The host must resolve the DNS name of the domain.
• Certificate. Make sure that the host trusts the certification authority that issued the certificates of the domain controllers.

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
The domain controllers of each domain that has users	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.