GitHub
Sign in
Start for free
View Categories

Connections

Quick guide #

XOAP Connections store the credentials and endpoints XOAP needs to integrate with external systems (for example, cloud providers and on-prem virtualization platforms). These connections are then referenced by other XOAP features.

Create a new Connection #

  1. Go to Connections and click + New Connection.
  2. In Select connection type, choose: Cloud provider, On-Premises, or API key.
  3. Fill in the required fields for the selected type (see examples below).
  4. (Optional) Add Description and Tags.
  5. Click Test Connection (when available) to validate the credentials and connectivity.
  6. Click Confirm (or Save) to create the connection.

Edit a Connection #

  1. In the Connections table, click the Action menu (⋮) for the connection.
  2. Select Edit.
  3. Update fields as needed.
  4. Click Test Connection (recommended) and Save/Confirm.

Delete a Connection #

  1. In the Connections table, click the Action menu (⋮) for the connection.
  2. Select Delete.
  3. Confirm the deletion.

Additional useful information #

Use least-privilege credentials #

Create separate identities/credentials per connection and only grant permissions required for the XOAP feature you’re using (for example, Image Management vs inventory-only).

Credential lifecycle #

Rotate secrets regularly (especially cloud app secrets) and update the XOAP connection to match it. Prefer non-expiring/managed approaches where your environment allows it.

Tags help at scale #

Tag connections by purpose (e.g., ImageManagement, Inventory, Prod, PoC) to make them easier to find and govern.

Test Connections early #

If Test Connection fails, validate network reachability (proxy/firewall/DNS), identity permissions, and correct tenant/subscription context before troubleshooting XOAP features that depend on the connection.

Technical documentation #

Connections define how XOAP authenticates to external platforms and APIs. They are used by XOAP features that need access to your infrastructure (cloud or on-prem) or by the XOAP Connector during enrollment.

In XOAP you can create three connection categories:

  • Cloud Providers (Azure, AWS, Google Cloud)
  • On-Premises (vSphere, Nutanix) (Preview)
  • API Keys (Preview)

Assignment scope: A connection can be assigned only to Images / Image Management and Scripted Actions (it is not used elsewhere).

Permissions: Minimum required permissions per provider are documented in XOAP prerequisites.

Connection types and fields #

1) Cloud provider connections #

Azure (Service Principal / Secret) #

Fields you provide:

  • Connection name – Friendly name used in XOAP to reference this connection.
  • Client ID – The Application (client) ID of the Azure AD app registration (Service Principal).
  • Client secret – The secret value used by the Service Principal to authenticate (treat as a password).
  • Subscription ID – The Azure subscription identifier where XOAP will manage/read resources.
  • Tenant ID – The Entra ID directory (tenant) identifier where the app/service principal exists.
  • Description (optional) – Free-text note to document purpose/owner of the connection.
  • Tags (optional) – Labels to help you find, filter, and govern connections (max 5 per object).

Test Connection: Available (verifies credentials/permissions against Azure).

Notes:

  • Use a dedicated Service Principal with least-privilege permissions as per XOAP prerequisites.
  • Rotate secrets regularly; treat them like privileged credentials.
AWS – Access Key #

Fields you provide:

  • Connection name – Friendly name used in XOAP to reference this connection.
  • AWS account ID – The 12-digit AWS account identifier that owns the target resources.
  • Access key ID – The public identifier part of an IAM access key.
  • Access key secret – The private secret part of the IAM access key (treat as a password).
  • Description (optional) – Free-text note to document purpose/owner of the connection.
  • Tags (optional) – Labels to help you find, filter, and govern connections (max 5 per object).

Test Connection: Available (verifies credentials/permissions against AWS).

Note: Use a dedicated IAM user/role and least-privilege policy as per XOAP prerequisites.

AWS – Assume Role #

Fields you provide:

  • Connection name – Friendly name used in XOAP to reference this connection.
  • Role ARN – The full Amazon Resource Name of the IAM role XOAP will assume for permissions.
  • Description (optional) – Free-text note to document purpose/owner of the connection.
  • Tags (optional) – Labels to help you find, filter, and govern connections (max 5 per object).

Test Connection: Available. (verifies credentials/permissions against AWS).

AWS – Assume Role (Cross-Account) #

Fields you provide:

  • Connection name – Friendly name used in XOAP to reference this connection.
  • Role ARN – The IAM role ARN in the target account that XOAP will assume.
  • External ID – A shared “secret” string required by the role trust policy to prevent confused-deputy access.
  • Description (optional) – Free-text note to document purpose/owner of the connection.
  • Tags (optional) – Labels to help you find, filter, and govern connections (max 5 per object).

Test Connection: Available (verifies credentials/permissions against AWS).

Note: Cross-account setups typically require a role trust policy + External ID pattern. XOAP’s prerequisites page lists the minimum permissions and guidance.

Google Cloud #

Fields you provide:

  • Connection name – Friendly name used in XOAP to reference this connection.
  • Project ID – The Google Cloud project identifier where XOAP will manage/read resources.
  • File (Service Account key JSON) – The uploaded JSON key file used to authenticate as a service account.
  • Description (optional) – Free-text note to document purpose/owner of the connection.
  • Tags (optional) – Labels to help you find, filter, and govern connections (max 5 per object).

Test Connection: Available. (verifies credentials/permissions against Google Cloud).

Note: The uploaded JSON key should belong to a service account with least-privilege roles required for your use case (Images vs Scripted Actions).

2) On-Premises connections (Preview) #

vSphere #

Fields you provide:

  • Connection name – Friendly name used in XOAP to reference this connection.
  • vCenter Server – The vCenter hostname or IP address XOAP will connect to.
  • Username – The vCenter user (or SSO identity) used for authentication.
  • Password – The password for the specified vCenter user.
  • Datacenter – The vSphere Datacenter inventory object that contains the clusters/hosts/datastores you want to target.
  • Cluster – The vSphere cluster under the selected datacenter that groups hosts and provides shared resource management (DRS/HA if enabled).
  • Host – A specific ESXi host to target (often used when selecting an exact host instead of scheduling via cluster/rules).
  • Resource pool – The resource pool within the cluster/host that defines CPU/RAM shares/limits/reservations for deployed VMs.
  • Datastore – The storage location where VM files (VMDKs/config) will be placed.
  • Folder – The vCenter VM folder used to organize where the VM object appears in the inventory.
  • Insecure (toggle) – Allows connecting without strict TLS validation (use only when required in lab/PoC scenarios).
  • Description (optional) – Free-text note to document purpose/owner of the connection.
  • Tags (optional) – Labels to help you find, filter, and govern connections (max 5 per object).

Test Connection: Currently not available for on-premises.

Important behavior:

  • Case-sensitive fields: vCenter inventory object names (Datacenter/Cluster/Host/Resource pool/Datastore/Folder) are case sensitive. Enter them exactly as defined in vCenter.
Nutanix #

Fields you provide:

  • Connection name – Friendly name used in XOAP to reference this connection.
  • Nutanix Username – The account XOAP uses to authenticate to Nutanix (typically Prism).
  • Nutanix Password – The password for the Nutanix account.
  • Endpoint – The Prism endpoint (hostname/IP + port if applicable) that XOAP connects to.
  • Cluster name – The Nutanix cluster identifier/name within Prism where operations will be performed.
  • Insecure (toggle) – Allows connecting without strict TLS validation (use only when required in lab/PoC scenarios).
  • Description (optional) – Free-text note to document purpose/owner of the connection.
  • Tags (optional) – Labels to help you find, filter, and govern connections (max 5 per object).

Test Connection: Currently not available for on-premises.

3) API key connections (Preview) #

Used for authenticating the XOAP Connector installation / enrollment flow (selecting an API key when generating install commands).

Fields you provide:

  • Connection name
  • API Token type (currently “Admin” and “XOAP Connector” have the same permissions — ignore the difference for now)
  • Optional: Description, Tags
Security notes #
  • Treat API keys as secrets: restrict access, rotate when needed, and avoid embedding them in plain text documentation.
  • If an API key is rotated, endpoints that rely on it (e.g., connector enrollment processes) must be updated accordingly.

Operational notes and best practices #

  • Least privilege first: Start from the minimum permissions documented in XOAP prerequisites, then expand only if a specific feature requires more.
  • Separate by purpose: Use different connections for Image Management vs Scripted Actions if you want strict separation of privileges.
  • Naming convention: Include provider + purpose + environment in the name (e.g., azure-im-prod, aws-sa-dev, vsphere-im-lab).
  • Tagging: Add tags for ownership, environment, customer/project, and purpose (e.g., prod, lab, im, sa).
  • Rotation & lifecycle: Plan a rotation process (especially for Azure Client Secret, AWS Access Keys, Google JSON keys, API keys).
  • Assignment awareness: Before deleting a connection, verify it’s not assigned to any Images or Scripted Actions.

Powered by BetterDocs

Scroll to Top