> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xloud.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Source Credentials

> Design, store, rotate, and scope credentials for VMware sources registered to XMS — including the recommended least-privilege vSphere role.

## Overview

Every source environment registered to XMS has a stored credential that XMS
uses for discovery, preflight, and migration. The credential is shared across
every job against that source. This page covers how operators should design
those credentials — scoping, least privilege, storage, and rotation.

***

## Principles

<CardGroup cols={2}>
  <Card title="One service account per source" icon="user-cog" color="#197560">
    Do not reuse a personal operator account for XMS. Create a dedicated
    service account in the source directory service and use it only for
    XMS — this keeps the audit trail clean and lets you rotate without
    impacting humans.
  </Card>

  <Card title="Scope to the datacenter you migrate" icon="target" color="#197560">
    Assign the XMS role at the datacenter you are actually migrating — not
    at the vCenter root. This keeps blast radius small and prevents XMS
    from accidentally touching inventory in datacenters it should not see.
  </Card>

  <Card title="Separate read-only vs migration scope" icon="split" color="#197560">
    For cautious rollouts, register the source with a read-only account for
    discovery and preflight first. Swap to the migration-capable account
    only when you are ready to run migrations.
  </Card>

  <Card title="Rotate credentials regularly" icon="refresh-cw" color="#197560">
    XMS stores source credentials securely and allows in-place rotation from
    the Dashboard or CLI. Build credential rotation into your standard
    operational cadence.
  </Card>
</CardGroup>

***

## Recommended vSphere Role

Create a dedicated role on the source vCenter and assign it to the XMS
service account at the datacenter scope.

| Category                         | Privileges                                     | Used For                                                                         |
| -------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------- |
| **System**                       | System.Anonymous, System.Read, System.View     | Session establishment, inventory read                                            |
| **Virtual Machine Config**       | DiskLease, ChangeTracking, Settings            | Enable CBT, read disk configuration                                              |
| **Virtual Machine Interact**     | PowerOff, PowerOn, Reset                       | Cold migration source power control                                              |
| **Virtual Machine State**        | CreateSnapshot, RemoveSnapshot, RevertSnapshot | Warm migration CBT anchor snapshots                                              |
| **Virtual Machine Provisioning** | DiskRandomAccess, DiskRandomRead               | Disk export over vSphere API                                                     |
| **Resource**                     | AssignVMToPool                                 | Optional — only required for cross-cluster source preparation                    |
| **Global**                       | DisableMethods, EnableMethods                  | Optional — only required to guard against concurrent modification during cutover |

<Tip>
  For discovery and preflight only, a read-only account with the **System**
  privileges above is sufficient. Add the Virtual Machine privileges only
  when you are ready to migrate.
</Tip>

***

## Credential Storage

XMS stores source credentials in the platform secret store. Credentials are:

* Encrypted at rest using the platform-managed encryption key
* Never displayed after save — the Dashboard shows a placeholder on edit
* Accessible only to the XMS control plane, which uses them to open vSphere
  API sessions on behalf of jobs

Operators cannot extract stored credentials in clear text from the platform.

***

## Credential Rotation

<Tabs>
  <Tab title="Dashboard" icon="gauge">
    <Steps titleSize="h3">
      <Step title="Open the source details drawer" icon="folder">
        Navigate to **Migration → Environments**, select the source, and
        click **Edit**.
      </Step>

      <Step title="Update credentials" icon="key">
        Enter the new username or password (or both) and click **Test
        Connection** to confirm the new credentials work against the source.
      </Step>

      <Step title="Save" icon="save">
        Click **Save**. XMS re-encrypts the credential and closes any open
        session that was using the old credential.

        <Check>Next discovery run uses the new credential.</Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash theme={null}
    # Rotate password only — read new password from stdin
    xms source update prod-vcenter --password-stdin

    # Rotate both username and password
    xms source update prod-vcenter \
      --username 'xms-service@vsphere.local' \
      --password-stdin

    # Test the updated connection without registering anything new
    xms source test prod-vcenter
    ```
  </Tab>
</Tabs>

<Warning>
  Changing the username or password of an active source invalidates any
  in-flight discovery session. Re-run discovery after rotation so the
  inventory cache refreshes against the new credential.
</Warning>

***

## Deleting a Source

Delete a source only when no active migration jobs reference it. XMS blocks
deletion of a source that is the parent of any running job. After all jobs
complete or fail, you can delete the source from the Dashboard or CLI, which
also removes the stored credential.

***

## Audit Trail

Source credential creation, update, and deletion events are captured in the
platform audit log. Operators investigating an incident can trace which
identity made credential changes and when, using the standard Xloud audit
tooling.

***

## Next Steps

<CardGroup cols={3}>
  <Card title="Prerequisites" href="/services/migration/admin-guide/prerequisites" color="#197560">
    Platform and project prerequisites for onboarding a source
  </Card>

  <Card title="Network Ports" href="/services/migration/admin-guide/network-ports" color="#197560">
    Which ports must be reachable between XMS and source
  </Card>

  <Card title="Register Source" href="/services/migration/user-guide/register-source" color="#197560">
    End-user steps for registering a source once credentials are ready
  </Card>
</CardGroup>