Prerequisites

Image Management #

To get started with Image Management, there is only one prerequisite: a working connection to your environment. Configure your connection by navigating to Connections, then clicking the Add new connection button in the upper-right corner.

In the slide-out panel, select the connection Type and Provider. Fill in the remaining required information and click Confirm to save your connection.

If you need assistance with configuring your access credentials, please refer to the Connect your infrastructure documentation.

In the following sections, you will find more information about the required permissions for your infrastructure. Please note that these are the minimum permissions needed to create Image Definitions.

If you plan to use the same connection for Scripted Actions, the required permissions may vary depending on the specific use case.

AWS #

To create a customized image, a default VPC must be available in the AWS account you’re using.

Additionally, you need to assign appropriate IAM permissions to the user specified in the connection. At a minimum, the following permissions are required:

#Codeblock

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:AttachVolume",
        "ec2:AuthorizeSecurityGroupIngress",
        "ec2:CopyImage",
        "ec2:CreateImage",
        "ec2:CreateKeyPair",
        "ec2:CreateSecurityGroup",
        "ec2:CreateSnapshot",
        "ec2:CreateTags",
        "ec2:CreateVolume",
        "ec2:DeleteKeyPair",
        "ec2:DeleteSecurityGroup",
        "ec2:DeleteSnapshot",
        "ec2:DeleteVolume",
        "ec2:DeregisterImage",
        "ec2:DescribeImageAttribute",
        "ec2:DescribeImages",
        "ec2:DescribeInstances",
        "ec2:DescribeInstanceStatus",
        "ec2:DescribeRegions",
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeSnapshots",
        "ec2:DescribeSubnets",
        "ec2:DescribeTags",
        "ec2:DescribeVolumes",
        "ec2:DetachVolume",
        "ec2:GetPasswordData",
        "ec2:ModifyImageAttribute",
        "ec2:ModifyInstanceAttribute",
        "ec2:ModifySnapshotAttribute",
        "ec2:RegisterImage",
        "ec2:RunInstances",
        "ec2:StopInstances",
        "ec2:TerminateInstances"
      ],
      "Resource": "*"
    }
  ]
}

#EndOfCodeblock

Read more about the required permissions here.

Azure #

To create images on Azure, ensure the following prerequisite is met: you must create a Service Principal with Contributor role access to your Azure subscription. Use the Azure CLI to generate the Service Principal.

Command format #

#Codeblock
az ad sp create-for-rbac \
  --name [ServicePrincipalName] \
  --role Contributor \
  --scopes /subscriptions/[SubscriptionId] \
  --years 1
#EndOfCodeblock

Command example #

#Codeblock

az ad sp create-for-rbac \
  --name xoap-image-principal \
  --role Contributor \
  --scopes /subscriptions/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --years 1

#EndOfCodeblock

Command output #

#Codeblock

{
  "appId": "[ClientId (Guid)]",
  "displayName": "xoap-image-principal",
  "name": "http://xoap-image-principal",
  "password": "[ClientSecret]",
  "tenant": "[TenantId (Guid)]"
}

#EndOfCodeblock

Using this output, you can now configure your connection in XOAP:

Subscription ID: xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Tenant ID: [TenantId (GUID)]
Client ID: [appId]
Client Secret: [password]

Read more about the required permissions here.

Google #

The file you’re required to upload is a Google Cloud Service Account key file in JSON format. You can generate and download it like this:

Open Google Cloud Console: https://console.cloud.google.com/iam-admin/serviceaccounts.
Select your project from the top-left dropdown.
Create or select a service account: If you don’t have one yet, click “Create Service Account” under “IAM&Admin” menu. Give it a name and optional description.
Assign the required roles (see below for full list).
After creating or selecting a service account:
- Click the ⋮ (three dots) next to the service account name → Manage Keys
- Under the “Keys” section, click Add Key → Create new key
- Choose JSON, then click Create
The file will download automatically – this is the file you need to upload into XOAP to authenticate with Google Cloud.

Required IAM Roles for Packer to build Images #

To allow the service account to build custom images with Packer, you need to assign at least these roles:

Role Name	Role ID	Purpose
Compute Instance Admin (v1)	roles/compute.instanceAdmin.v1	Required to create, configure, and delete instances, disks, and snapshots
Service Account User	roles/iam.serviceAccountUser	Allows using the service account to launch instances
Storage Admin (optional)	roles/storage.admin	Required if storing images or artifacts in Cloud Storage
IAP Tunnel Resource Accessor (optional)	roles/iap.tunnelResourceAccessor	Needed only if using IAP to tunnel SSH
Compute Network User (Shared VPC only)	roles/compute.networkUser	Required if you’re using a Shared VPC network

Read more about the required permissions here.

vSphere #

To integrate XOAP with VMware vSphere for image builds, create a custom vSphere role that includes only the privileges required for XOAP to perform its operations. Assign this role to a dedicated service account to ensure XOAP has least-privilege access to the vSphere infrastructure.

Required privileges #

Clone the default Read-Only vSphere role and add the following privileges:

Category	Privilege	Reference
Content Library	Add library item	ContentLibrary.AddLibraryItem
Content Library	Update Library Item	ContentLibrary.UpdateLibraryItem
Cryptographic Operations	Direct Access (Required for cache upload.)	Cryptographer.Access
Cryptographic Operations	Encrypt (Required for vTPM.)	Cryptographer.Encrypt
Datastore	Allocate space	Datastore.AllocateSpace
Datastore	Browse datastore	Datastore.Browse
Datastore	Low level file operations	Datastore.FileManagement
Host	Configuration > System Management	Host.Config.SystemManagement
Network	Assign network	Network.Assign
Resource	Assign virtual machine to resource pool	Resource.AssignVMToPool
vApp	Export	vApp.Export
Virtual Machine	Configuration > Add new disk	VirtualMachine.Config.AddNewDisk
Virtual Machine	Configuration > Add or remove device	VirtualMachine.Config.AddRemoveDevice
Virtual Machine	Configuration > Advanced configuration	VirtualMachine.Config.AdvancedConfig
Virtual Machine	Configuration > Change CPU count	VirtualMachine.Config.CPUCount
Virtual Machine	Configuration > Change memory	VirtualMachine.Config.Memory
Virtual Machine	Configuration > Change settings	VirtualMachine.Config.Settings
Virtual Machine	Configuration > Change Resource	VirtualMachine.Config.Resource
Virtual Machine	Configuration > Modify device settings	VirtualMachine.Config.EditDevice
Virtual Machine	Configuration > Set annotation	VirtualMachine.Config.Annotation
Virtual Machine	Edit Inventory > Create from existing	VirtualMachine.Inventory.CreateFromExisting
Virtual Machine	Edit Inventory > Create new	VirtualMachine.Inventory.Create
Virtual Machine	Edit Inventory > Remove	VirtualMachine.Inventory.Delete
Virtual Machine	Interaction > Configure CD media	VirtualMachine.Interact.SetCDMedia
Virtual Machine	Interaction > Configure floppy media	VirtualMachine.Interact.SetFloppyMedia
Virtual Machine	Interaction > Connect devices	VirtualMachine.Interact.DeviceConnection
Virtual Machine	Interaction > Inject USB HID scan codes	VirtualMachine.Interact.PutUsbScanCodes
Virtual Machine	Interaction > Power off	VirtualMachine.Interact.PowerOff
Virtual Machine	Interaction > Power on	VirtualMachine.Interact.PowerOn
Virtual Machine	Provisioning > Create template from virtual machine	VirtualMachine.Provisioning.CreateTemplateFromVM
Virtual Machine	Provisioning > Mark as template	VirtualMachine.Provisioning.MarkAsTemplate
Virtual Machine	Provisioning > Mark as virtual machine	VirtualMachine.Provisioning.MarkAsVM
Virtual Machine	State > Create snapshot	VirtualMachine.State.CreateSnapshot

Configuration Management #

PowerShell #

All nodes that will be used to author or receive configurations are running WMF version 5.1 or later. Authoring nodes that are used to write configurations locally need to have internet connectivity to download new DSC-related resources.

Remote management #

WS-Management (WS-MAN) traffic is permitted on the network. It will be enabled by default on nodes that have PowerShell version 5 installed, but you must ensure it’s not being blocked by firewalls or other network elements. Read further for more information.

Communication with our backend #

In order to communicate with our backend, the following ports need to be open: https://api.xoap.io on port 443.

Proxy configuration for nodes #

To force PowerShell DSC nodes to use a proxy server to communicate with the cloud-hosted backend, some adjustments to the node configuration must be made before registering the node. DSC does not communicate in a user context and therefore uses the SYSTEM context.

For DSC to connect successfully and register the node, adjust the following lines inside the machine.config in your .NET installation directory.

You should find the file in these locations:

32-bit
**%windir%\Microsoft.NET\Framework\[version]\config\machine.config**
64-bit
**%windir%\Microsoft.NET\Framework64\[version]\config\machine.config**
[version] should be equal to v1.0.3705, v1.1.4322, v2.0.50727 or v4.0.30319. v3.0 and v3.5 just contain additional assemblies to v2.0.50727 so there should be no config\machine.config. v4.5.x and v4.6.x are stored inside v4.0.30319.
Then add the following lines:
<defaultProxy>  <proxy autoDetect="false" bypassonlocal="false" proxyaddress="http://127.0.0.1:8888" /> </defaultProxy></system.net>

Firewalls #

SSL decryption can get you into trouble when clients inside your corporate network try to communicate with the cloud backend.

DEP #

We’ve seen some Virus Scanners with DEP enabled to prevent users from logging into the cloud backend successfully.

TLS #

Enable TLS 1.2 wherever possible. Not doing so will keep Configurations Management from working successfully.

Set it via PowerShell:

Set-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\.NetFramework\v4.0.30319' -Name 'SchUseStrongCrypto' -Value '1' -Type DWordSet-ItemProperty -Path 'HKLM:\SOFTWARE\Wow6432Node\Microsoft\.NetFramework\v4.0.30319' -Name 'SchUseStrongCrypto' -Value '1' -Type DWordSet-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\.NetFramework\v2.0.50727' -Name 'SchUseStrongCrypto' -Value '1' -Type DWord[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12

Application Management #

To use Application Management you need to have network access to api.xoap.io over port 443 and custom packages must be provided as a ZIP archive prior to upload.

Within your XOAP workspace, you can already find a wide selection of:

Applications
Application Groups
Application Roles

This means you’re ready to begin installing applications immediately.

Creating packages #

XOAP’s Application Management supports PSADT packages in both v3 and v4 formats. Our current Package Wizard supports package creation in v3 format. If you plan to create your own application packages, we recommend installing it on your packaging machine. The easiest way to do this is directly from your XOAP Workspace.

Navigate to Application Management → Application Roles
Locate the Role: PSADT Packaging Baseline
Open the three-dot menu next to the role and choose Copy installation command
On the machine where you want to install the wizard, open PowerShell as Administrator. Paste and execute the copied command.

Alternatively, you can download the installation script or copy the installation command, copy it manually to the target system, and then run it through PowerShell as Administrator.

Once completed, the Package Wizard will be fully installed and configured. You can find the shortcut on your desktop.

Platform Management #

There are no deployed agents required to use Platform Management — the logic runs directly on XOAP’s cloud runners or through your established infrastructure connections.

Within the Scripted Actions library, you can already find a selection of:

Template scripts: pre-built scripts for common tasks (like AVD management or Azure automation)
Resources: a library where your custom scripts are stored

This means you can start automating immediately using existing templates.

Supported formats #

Platform Management supports standard PowerShell (.ps1), Azure CLI, Google CLI and AWS CLI scripts. The only prerequisite for using your own automation is that the script file must be uploaded to the Resources area or imported directly during action creation.

Establishing connections #

To execute any script, the platform requires a valid Connection to your infrastructure. It is recommended setting up your Connections to cloud providers (Azure, AWS, Google) or on-premises systems (VMware, Nutanix) before creating complex workflows.

You can easily set this up from your XOAP workspace:

Navigate to Connections (in the main menu)
Click + New connection
Select your provider (Azure, AWS, Google, or other) and follow the authentication prompts

Note: The Scripted Action wizard also allows you to add a new connection during the Target selection step.

Still stuck? How can we help?

Updated on January 20, 2026