# Windows Server

### Overview

The Veza integration for Windows Server comprises an OAA package and a collection of .NET 8.0 applications. These tools discover metadata from a Windows Server host and forward it to a Veza instance. The application package comes as an MSI installer for deployment on Windows Server.

For automated deployment at scale with per-machine unique Team API Keys, see the [Enterprise Deployment](/4yItIzMvkpAvMVFAamTf/integrations/integrations/windows/enterprise-deployment.md) guide.

#### Components

The Veza Windows OAA application includes:

1. A service that discovers local groups, user accounts, services, and scheduled tasks within the Windows Server OS.
2. A service to detect Active Directory filesystem permissions on SMB file shares.
3. A GUI application for configuring discovery services and setting up the Veza connection.

#### Prerequisites

* Windows Server 2012 R2 or newer
* .NET 8.0 Runtime (included in the installer)
* You will need the installation program from Veza, available [here](https://veza-windows-dev.s3.us-west-1.amazonaws.com/Veza.msi)

### Deployment Specifications

#### System Requirements

| Resource              | Requirement          | Notes                                     |
| --------------------- | -------------------- | ----------------------------------------- |
| Memory                | < 50MB RAM           | During normal operation                   |
| Disk Space            | \~300MB              | For application installation              |
| Additional Disk Space | Varies               | Up to 1GB for logs when using Debug level |
| Network               | Outbound HTTPS (443) | To Veza tenant                            |
| Permissions           | Local Administrator  | Required for installation and operation   |

#### Performance Impact

The Veza Windows integration is engineered to operate with minimal resource utilization across enterprise environments:

* **CPU Utilization**: Typically insignificant during standard metadata collection operations
* **Memory Consumption**: <50MB RAM during normal operational cycles
* **Network Bandwidth**: Optimized data transmission with lightweight payloads transmitted at configurable intervals (default: 60 minutes)
* **Storage I/O**: Negligible impact on storage subsystems outside of scheduled log maintenance or diagnostic activities

#### Operational Schedule

* By default, the application collects and sends metadata to Veza every 60 minutes
* This interval can be configured between 1 hour and 1 day to suit your organizational requirements by modifying the configuration file or in the application settings.
* For file share discovery, a minimum interval of 120 minutes is recommended

**GUI Configuration:**

1. Open `Veza for Windows` from the Start menu
2. Go to the **Local Accounts** tab and modify the **Discovery Interval (minutes)** field (minimum 60 minutes) to change the local accounts discovery interval.
3. For file share intervals, go to the **Folders** tab and modify the **Discovery Interval (minutes)** field (minimum 120 minutes)
4. Click **Save** to apply changes

**Configuration File:**

To manage these settings in the configuration file at `C:\Program Files\Veza\Veza.config`:

1. Set `windows_local_accounts-interval` for local accounts discovery interval (recommended minimum 60 minutes)
2. Set `windows_files-interval` for file share discovery interval (recommended minimum 120 minutes)
3. Both values should be specified in minutes as quoted integers (e.g., `"120"`). See the [configuration parameters table](#example-configuration-file) for complete details

#### Log Management

* The application stores 14 days of logging information
* Logs are automatically purged as they age out
* At the standard `Info` level, log storage is negligible
* At `Debug` level, logs may consume up to 1GB of disk space
* Log locations:
  * `C:\Program Files\Veza\Local Accounts\logs\VezaWindows.log`
  * `C:\Program Files\Veza\Folders\logs\VezaFiles.log`

### Installation

#### Deployment Options

The Veza Windows integration supports both manual and automated deployment methods:

**Manual Installation**

Run the `Veza.msi` installation program and follow the on-screen prompts. By default, the application installs in `C:\Program Files\Veza`.

**Silent Installation (for automated deployment)**

The MSI package supports standard silent installation parameters for enterprise deployment:

> **Important**: API keys are encrypted using the Windows Data Protection API and **cannot** be set directly in configuration files.

```powershell
# Basic silent install
msiexec /i Veza.msi /qn

# Install with specific log file
msiexec /i Veza.msi /qn /l*v install.log

# Install to custom directory
msiexec /i Veza.msi /qn INSTALLDIR="D:\Applications\Veza"

# Install with an existing configuration file
msiexec /i Veza.msi /qn CONFIG="\\deployment-share\Veza\Veza.config"

# Install with an existing API key (recommended for automated deployment)
msiexec /i Veza.msi /qn APIKEY="<api_key>"

# Install with existing configuration file and API key
msiexec /i Veza.msi /qn CONFIG="\\deployment-share\Veza\Veza.config" APIKEY="<api_key>"
```

#### API Key Deployment Methods

**Method 1: MSI Installation with APIKEY Parameter (Recommended)**

This method encrypts the API key during installation:

```powershell
msiexec /i Veza.msi /qn CONFIG="\\deployment-share\Veza\Veza.config" APIKEY="<api_key>"
```

**Method 2: Post-Installation API Key Configuration**

If you cannot include the API key in the MSI command:

```powershell
# Install without API key (use full path for CONFIG)
msiexec /i Veza.msi /qn CONFIG="C:\path\to\Veza.config" /l*v install.log

# Configure API key post-installation
Start-Process -FilePath "C:\Program Files\Veza\VezaWindowsTray.exe" -ArgumentList "--api_key=<api_key>" -NoNewWindow -Wait
```

**Example Configuration File**

Below is a standard configuration template that can be customized for your environment:

```xml
<?xml version="1.0" encoding="utf-8"?>
<configuration>
 <configSections>
  <section name="PathConfigurationSection" type="Veza.Integrations.PathConfigurationDataSection, PathConfiguration, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
 </configSections>
 <PathConfigurationSection>
  		<PathConfigurations>
  		  </clear>
			  <add path=”\\fileserver01.example.com\Finance” depth=”1” />
			  <add path=”\\fileserver02.example.com\Human Resources\Benefits” depth=”1” />
  		</PathConfigurations>
 </PathConfigurationSection>
 <appSettings>
  <!-- Local Account Collection Settings -->
  <add key="windows_local_accounts-enabled" value="true" />
  <add key="windows_local_accounts-interval" value="60" />
  <add key="windows_local_accounts-services_enabled" value="true" />
  <add key="windows_local_accounts-tasks_enabled" value="true" />
  <add key="windows_local_accounts-save_json" value="false"/>

  <!-- Veza API Connection Settings -->
  <!-- WARNING: Do not set veza-api_key here - use MSI APIKEY parameter or post-install command -->
  <add key="veza-url" value="https://YOUR_TENANT.vezacloud.com" />
  <add key="veza-insight_point_proxy" value="http://INSIGHT_POINT_IP:8080" />
  <add key="veza-loglevel" value="Info" />

  <!-- File Share Discovery Settings -->
  <add key="windows_files-enabled" value="true" />
  <add key="windows_files-interval" value="120" />
  <add key="windows_files-threads" value="1" />
  <add key="windows_files-save_json" value="false"/>
 </appSettings>
</configuration>
```

Required configuration parameters are listed and described in the table below:

| Configuration Parameter                              | Description                                                                          | Notes                                                                                                                                                                                                |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `windows_local_accounts-enabled`                     | Enables the discovery of local accounts, services, and scheduled tasks               | `"true"` or `"false"`                                                                                                                                                                                |
| `windows_local_accounts-interval`                    | The execution interval in minutes for local accounts discovery                       | Set to an integer greater than 60 in quotes                                                                                                                                                          |
| `windows_local_accounts-services_enabled`            | Include local service metadata in Veza                                               | `"true"` or `"false"`                                                                                                                                                                                |
| `windows_local_accounts-tasks_enabled`               | Include Scheduled Tasks metadata in Veza                                             | `"true"` or `"false"`                                                                                                                                                                                |
| `windows_local_accounts-save_json`                   | Save the payload uploaded to Veza to disk into `<INSTALL_DIRECTORY>\Local Accounts\` | `"true"` or `"false"`                                                                                                                                                                                |
| `veza-api_key`                                       | The encrypted API key used to communicate with the Veza tenant                       | Populated by MSI APIKEY parameter or post-install command                                                                                                                                            |
| `veza-insight_point_proxy`                           | Local Insight Point proxy endpoint for outbound connection routing                   | Format: `http://FQDN:8080`. **Security Note**: HTTP indicates internal network endpoint only; external connections use HTTPS/TLS encryption. See [proxy architecture](#insight-point-proxy-security) |
| `veza-url`                                           | The URL of the Veza tenant                                                           | Veza tenant URL                                                                                                                                                                                      |
| `veza-loglevel`                                      | Sets the verbosity of the logs for the Veza service                                  | `"Info"` or `"Debug"`                                                                                                                                                                                |
| `windows_files-enabled`                              | Enables the discovery of Windows File Server folders and permissions                 | `"true"` or `"false"`                                                                                                                                                                                |
| `windows_files-interval`                             | The execution interval in minutes for Windows File Server discovery                  | Set to an integer greater than 120 in quotes                                                                                                                                                         |
| `windows_files-threads`                              | The number of simultaneous threads used during Windows File Server discoviry         | Set to `"1"` unless instructed to change by Veza support                                                                                                                                             |
| `windows_files-save_json`                            | Save the payload uploaded to Veza to disk into `<INSTALL_DIRECTORY>\Folders\`        | `"true"` or `"false"`                                                                                                                                                                                |
| `windows_files-max_unresolved_identities_per_folder` | Maximum number of unresolved identities to track per folder                          | Integer, default `"100"`. See [Unresolved identities](#unresolved-identities)                                                                                                                        |

#### GUI Configuration (manual deployment)

Post-installation, open `Veza for Windows` from the Start menu.

1. Under the `Veza API` tab, input your Veza instance URL into `Veza URL`.
2. Paste the previously created API key into `Veza API Key`.
3. Optionally provide the URL for the Insight Point Proxy (e.g., `http://insight-point:8080`). Note that HTTP URLs represent internal network endpoints, see [proxy architecture](#insight-point-proxy-security) for encryption details.
4. Click `Apply`.

To verify the successful connection, log in to Veza and open the Integrations page. You should see `Windows Server` enabled on the list of all integrations.

> **Note**: The installed service needs to run with Administrative privileges.

### Security Considerations

#### API Key Management

The Veza Windows integration uses an API key to authenticate with the Veza tenant. For least privilege, use a [Team API Key](/4yItIzMvkpAvMVFAamTf/developers/api/users-teams/team-api-keys.md) scoped to OAA Push. Team API Keys limit access to pushing metadata only, without granting broader administrative permissions.

A Personal API Key is required once to create the "Windows Server" and "Windows Files" providers on the Veza platform. After the providers exist, all subsequent data collection can use Team API Keys. For detailed setup instructions, see the [Enterprise Deployment](/4yItIzMvkpAvMVFAamTf/integrations/integrations/windows/enterprise-deployment.md) guide.

* **Key Types**:
  * **Team API Key (recommended)**: Scoped to OAA Push role. Use for ongoing data collection from deployed servers
  * **Personal API Key**: Required for initial provider creation and other administrative tasks
* **Key Deployment Options**:
  * Deploy a unique Team API Key per server for the highest security
  * Deploy a shared Team API Key across all servers for simplified management
  * Deploy keys by department or region for balanced security and management
* **Key Storage**:
  * The API key is encrypted using Windows Data Protection API
  * Stored in the configuration file at `C:\Program Files\Veza\Veza.config`
* **Key Rotation**:
  * Keys are not automatically rotated
  * Keys can be manually deleted and replaced with new ones via the Veza tenant
* **Key Compromise**:
  * A compromised Team API Key grants access only to the OAA Push endpoints for the scoped providers. A compromised Personal API Key grants broader access to the endpoints listed in [Veza APIs](/4yItIzMvkpAvMVFAamTf/developers/api.md)
  * Immediately delete and replace any compromised keys

See [Authentication](/4yItIzMvkpAvMVFAamTf/developers/api/authentication.md) for more about Veza API keys.

#### Network Security

The Veza Windows integration requires:

* Outbound HTTPS (443) access to the Veza tenant or Insight Point
* All data is transmitted using TLS 1.2 or higher

No inbound connectivity is required.

**Insight Point Proxy Security**

**Proxy Configuration**: HTTP URLs in proxy settings (e.g., `http://insight-point:8080`) represent internal network endpoints only, with all external connections using HTTPS/TLS encryption. You can use this option to enable Windows servers to reach Veza's cloud service via the Insight Point's encrypted tunnel.

For more about Insight Point connection flow and deployment considerations, see the [Insight Point documentation](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point/insight-point-install-script.md#configuring-insight-point-to-forward-connections-to-veza-early-access).

### Update Management

The Veza for Windows application follows a separate release cadence from the Veza platform:

* Updates are released only for bug fixes, security bulletins, and feature enhancements
* Updates are manually deployed via new MSI packages published by Veza
* No automatic updates are performed
* Update notifications are sent to tenant administrators

To update existing installations:

1. Download the latest MSI from Veza
2. Deploy using the same methods as the initial installation
3. The installation program will automatically upgrade the existing installation

Configuration settings are preserved during upgrades.

### Standard Functionality

#### Windows Local Accounts

This service identifies local security principals on the Windows Server host. By default, it detects:

1. Local user accounts
2. Local groups
3. (Optional) Installed services
4. (Optional) Configured scheduled tasks

**Properties**

| User Properties          | Description                                                                 |
| ------------------------ | --------------------------------------------------------------------------- |
| `last_login_at`          | Time of user last login                                                     |
| `cannot_change_password` | Indicates if the user's password can't be changed (boolean)                 |
| `locked_out`             | Shows if the user account is locked out (boolean)                           |
| `password_never_expires` | Checks if the user's password is set to never expire (boolean)              |
| `password_not_required`  | Checks if the user doesn't need a password (boolean)                        |
| `type`\*                 | Differentiates between `local` or `active directory` user accounts (string) |
| `home_directory`         | User home directory path                                                    |

| Group Properties | Details                                                                          |
| ---------------- | -------------------------------------------------------------------------------- |
| `type`\*         | Specifies if the group is `local` or associated with `active directory` (string) |

| Scheduled Task Properties | Details                                                      |
| ------------------------- | ------------------------------------------------------------ |
| `path`                    | Full path of the scheduled task (string)                     |
| `state`                   | Current state: `Ready`, `Running`, `Disabled`, etc. (string) |

| Service Properties     | Details                                             |
| ---------------------- | --------------------------------------------------- |
| `service_account_name` | Account used to run the service (string)            |
| `start_type`           | Start type: `Automatic`, `Manual`, etc. (string)    |
| `status`               | Current status: `Running`, `Stopped`, etc. (string) |

> Note (\*): Local groups on Windows Server can contain both Active Directory subgroups and local user accounts. The `type` property distinguishes between the two entities.

#### Windows Files

This service discovers filesystem permissions for specified paths and subdirectories based on the set depth. It primarily identifies:

1. Filesystem paths
2. Active Directory users and groups with permissions on each path
3. Permission inheritance

**Unresolved identities**

When discovering file share permissions, the agent resolves each security principal to an Active Directory user or group. If a security principal cannot be resolved (for example, an orphaned SID from a deleted account or a principal from an untrusted domain), the agent records it as an **unresolved identity** on the folder.

Unresolved identities appear as an `unresolved_identities` property on the folder entity in the Veza graph. The property contains a list of SAM account names that could not be resolved. These identities are not created as separate entities and do not connect to any Active Directory user or group.

To find folders with unresolved identities, query for folder entities where the `unresolved_identities` property is populated.

By default, the agent tracks up to 100 unresolved identities per folder. To change this limit, set the `windows_files-max_unresolved_identities_per_folder` configuration parameter. If a folder exceeds the limit, additional unresolved identities are discarded and a warning is logged.

**Limitations**

* Designed for SMB file shares utilizing Active Directory permissions
* Enumerating large shares can be more memory-intensive and will increase the RAM requirement during execution

### Configuration Options

These settings can be configured either through the GUI application (`Veza for Windows` from the Start menu) or by editing the configuration file at `C:\Program Files\Veza\Veza.config`. See the [configuration parameters table](#example-configuration-file) for file-based configuration details.

#### Local Accounts

In the `Local Accounts` tab, adjust settings as desired:

| Option                         | Purpose                                                   |
| ------------------------------ | --------------------------------------------------------- |
| `Enabled`                      | Toggles discovery (check mark to enable discovery)        |
| `Discovery Interval (minutes)` | Sets interval between discovery runs (minimum 60 minutes) |
| `Include Services`             | Enables service discovery (optional)                      |
| `Include Scheduled Tasks`      | Activates scheduled task data discovery (optional)        |
| `Save Payload`                 | Saves the payload uploaded to Veza to disk (optional)     |

#### Files

In the `Folders` tab, customize as needed:

| Option                         | Purpose                                               |
| ------------------------------ | ----------------------------------------------------- |
| `Enabled`                      | Toggles discovery                                     |
| `Discovery Interval (minutes)` | Time gap between discoveries (minimum 120 minutes)    |
| `Discovery Threads`            | Sets concurrent discovery threads                     |
| `Save Payload`                 | Saves the payload uploaded to Veza to disk (optional) |
| `Paths`                        | Use `Add Path` to specify discovery paths             |

### Troubleshooting

#### Common Issues

**API Key Not Working During MSI Installation**:

* **Problem**: API key included directly in configuration file
* **Solution**: API keys cannot be set in configuration files. Use MSI `APIKEY` parameter or post-installation configuration
* **Example**: `msiexec /i Veza.msi /qn CONFIG="C:\path\to\Veza.config" APIKEY="your_key"`

**Configuration Parameters Not Applied**:

* **Problem**: Configuration file path incorrect or MSI cannot access relative paths
* **Solution**: Use full filesystem path for CONFIG parameter, not relative paths
* **Example**: Use `CONFIG="C:\Users\Administrator\Desktop\Veza.config"` instead of `CONFIG="Veza.config"`
* **Root Cause**: MSI executes in different user context than current directory

**Connection Failures**:

* Verify network connectivity to the Veza tenant
* Check API key validity in the Veza tenant
* Ensure correct URL format (e.g. `https://tenant-name.vezacloud.com`)

**Performance Issues**:

* If memory usage exceeds 50MB during normal operation, check file share sizes
* Reduce the number of discovery threads for file shares
* Increase discovery intervals

**Log Analysis**:

* You can adjust the service's log level using the dropdown menu. By default, logs are saved at `C:\\Program Files\Veza\Local Accounts\logs\VezaWindows.log` and `C:\\Program Files\Veza\Folders\logs\VezaFiles.log`.
* Set log level to `Debug` temporarily to gather more information for troubleshooting and support requests.
* Reduce the logging level after troubleshooting to minimize disk usage

#### Support

For additional assistance, contact Veza Support at <support@veza.com> or through your account representative.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/integrations/integrations/windows.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.