# About Network Identity Attestation

> Learn about Network Identity Attestation (NIA), a security component that provides cryptographically verifiable identity for workloads in virtualized environments

**Network Identity Attestor** is an

Aembit Edge Component. It provides strong, cryptographically verifiable identity for workloads running in VMware vSphere environments. Network Identity Attestation acts as a bridge between your VMware infrastructure and Aembit. It enables secure, identity-based workload authentication and authorization.

## The problem Network Identity Attestor solves

In cloud environments, workloads (like VMs or containers) can use cloud-native metadata services to prove their identity. VMware vSphere doesn’t natively provide a similar, secure attestation mechanism for VMs.

Network Identity Attestor fills this gap by allowing workloads to prove they’re legitimate VMs running in your vSphere environment.

## How Network Identity Attestor works

Deploy the Network Identity Attestor Edge Component as a dedicated VM within your vSphere environment. Deploy **at least one instance per L2 network segment**. Its main responsibilities are:

1. **Listening for Attestation Requests** - The service exposes a secure HTTPS endpoint on the network. Workload VMs (running the Aembit Agent Proxy) send attestation requests to this endpoint.

2. **Validating the Request** - When the service receives a request, it:

   * Extracts the MAC address of the requesting VM from the network connection.
   * Uses the vCenter API to look up the VM associated with that MAC address.
   * Retrieves relevant VM metadata (such as VM name, UUID, etc.).

3. **Generating an Attestation Document** - The service constructs a signed document containing:

   * VM metadata (name, `biosUuid`, `instanceUuid`, MAC address)
   * Timestamps (issuedAt, expiresAt)
   * A digital signature using a customer-managed signing certificate

4. **Returning the Attestation Document** - The service returns the signed document to the requesting workload VM. The Aembit Agent Proxy includes this document in its authentication flow with

   Aembit Cloud.

   Aembit Cloud uses this document for Trust Provider attestation (Access Policy enforcement).

5. **Verification in Aembit Cloud** - Aembit Cloud uses the public key from your signing certificate. Register this certificate in a **[Certificate Signed Attestation Trust Provider](/user-guide/access-policies/trust-providers/certificate-signed-attestation-trust-provider)** configured in your Access Policy. Aembit Cloud verifies the authenticity and integrity of the attestation document. If valid, Aembit Cloud authorizes the workload for access based on the Access Policy configuration.

## Security model

* **Cryptographic Assurance** - A private key that you manage signs the attestation document. Only services with access to this key can generate valid documents.
* **Network Isolation** - Deploy the service on the same L2 segment as the workloads it attests. This ensures MAC address integrity and prevents spoofing.
* **Minimal Metadata Exposure** - The attestation document includes only essential VM metadata. This minimizes information exposure.
* **Certificate Management** - You control the lifecycle of the signing certificate. You can rotate or revoke it as needed.

### `systemd-creds` Usage

The Network Identity Attestation installer uses `systemd-creds` to securely store sensitive values. These values include vCenter API credentials, attestation signing certificates, and private keys. During installation, the installer encrypts these secrets and embeds them into a `systemd` drop-in configuration file. At runtime, systemd decrypts the credentials and provides them only to the Network Identity Attestation service process.

This approach encrypts secrets at rest and restricts access to the service only. It uses encryption keys protected by the system Trusted Platform Module (TPM) 2.0-compatible vTPM device when available.

> **Delete original credential files**
>
> Once the installer completes successfully, delete the original credential files you used during installation. Systemd retains secure, encrypted copies that the service accesses at runtime.

## Deployment topology

* **One Service per L2 Segment** - MAC addresses are only unique and visible within a single L2 network. Each segment requires its own Network Identity Attestation instance.
* **Integration with vCenter** - The service requires read access to the vCenter API to look up VM details. Provide credentials via a secure file using the `AEMBIT_VCENTER_CREDENTIALS_FILE` environment variable, or omit the variable and the installer prompts for credentials during installation.
* **Customer-managed TLS required** - Network Identity Attestor doesn’t support Aembit Managed TLS. You must provide customer-managed TLS certificates for Agent Controller, Network Identity Attestor, and Agent Proxy communication.

The following diagram shows Network Identity Attestation network topology:

![Network Identity Attestation topology with VMware and Aembit components](/d2/docs/user-guide/deploy-install/virtual-envs/about-network-identity-attestation-0.svg)

### Example attestation flow

1. A workload VM boots and starts the Aembit Agent Proxy.
2. The Agent Proxy sends an attestation request to the Network Identity Attestation service.
3. The service verifies the VM’s identity with vCenter API and signs a document.
4. The Agent Proxy presents the signed document to Aembit Cloud.
5. Aembit Cloud verifies the signature and VM metadata, then evaluates the Access Policy.

![Network Identity Attestation flow showing request, verification, and authorization steps](/d2/docs/user-guide/deploy-install/virtual-envs/about-network-identity-attestation-1.svg)

## Benefits

* **Automated, Secure Workload Onboarding** - No manual secret distribution or static credential management.
* **Strong Identity Assurance** - Tied directly to your vSphere infrastructure and cryptographically verifiable.
* **Seamless Integration** - Works with Aembit’s Agent Proxy and Trust Provider model for end-to-end workload identity.

## Limitations

* **Requires vCenter API Access** - The service must be able to query vCenter for VM metadata.
* **L2 Network Boundaries** - Each L2 segment needs its own service instance due to MAC address scoping.
* **Certificate Management** - You are responsible for securely managing and rotating the signing and TLS certificates.

> **Don’t deploy HTTP reverse proxies or load balancers in front of Network Identity Attestor**
>
> Never deploy a traditional HTTP reverse proxy or load balancer that proxies requests to a Network Identity Attestor. This is a critical security risk. Network Identity Attestor identifies workloads by the MAC address of the requesting connection. If a proxy sits between the Client Workload and Network Identity Attestor, every request appears to come from the proxy’s MAC address. This allows any workload VM to obtain the identity document of the proxy/load balancer VM instead of its own identity.

## Additional constraints for Network Identity Attestor

1. **One Network Identity Attestor instance per L2 network segment**

   * Deploy Network Identity Attestor on the same Layer 2 (L2) network segment as the workloads it attests.
   * MAC address visibility and integrity are only guaranteed within an L2 segment.
   * Deployments with multiple L2 segments require multiple Network Identity Attestor instances.

2. **vCenter API access required**

   * Network Identity Attestor requires credentials with read access to the vCenter API to validate VM identity and retrieve metadata.
   * Attestation fails if vCenter is unavailable or credential configuration is incorrect.

3. **Support for only VMware environments**

   * Network Identity Attestor supports VMware vSphere environments specifically.
   * It doesn’t support attestation for workloads running on other hypervisors or bare metal.

4. **Performance and Rate Limiting**

   * The performance of Network Identity Attestor is dependent on vCenter API responsiveness and rate limits.
   * vCenter may throttle or delay high-frequency attestation requests if under load.

5. **MAC Spoofing Protection Required**

   * The security model assumes that the network segment enforces MAC spoofing protection.
   * If MAC spoofing is possible, an attacker could impersonate another VM.

6. **Limited Metadata in Attestation Document**

   * The attestation document includes only essential VM metadata (name, UUID, MAC address).
   * Additional custom attributes aren’t supported.

7. **VM identifiers only unique within a vCenter cluster**

   * The `instanceUuid` and `biosUuid` identifiers are only unique within a single vCenter cluster.
   * If you have multiple vCenter clusters, configure **one Trust Provider per cluster** to prevent ID collisions.
   * Using a single Trust Provider with Network Identity Attestor certificates from multiple vCenter clusters can result in workloads being incorrectly identified.
   * The `instanceUuid` is the most reliable identifier for matching VMs, as `biosUuid` is not guaranteed to be unique.

8. **Private Release / Limited Availability**
   * Network Identity Attestor is a private release for select customers and not publicly available.

9. **Manual Registration in Aembit Cloud**
   * Manually register the public key from the signing certificate in the Aembit Cloud Trust Provider configuration.

10. **No Automatic Certificate Renewal**

    * Network Identity Attestor doesn’t automatically renew its signing or TLS certificates.
    * Use the `rotate-signing-credentials` subcommand to rotate the attestation signing certificate. See [Rotating NIA Credentials](/user-guide/deploy-install/virtual-envs/rotate-nia-credentials).
    * TLS certificate and vCenter API credential rotation requires re-running the NIA installer. See [Rotating NIA Credentials](/user-guide/deploy-install/virtual-envs/rotate-nia-credentials).

11. **No pre-built monitoring dashboards**

    * Network Identity Attestor exposes a `/health` endpoint and optional Prometheus-compatible `/metrics` endpoint, but doesn’t include pre-built dashboards or alerting rules.
    * For details on configuring monitoring, see [Monitor Network Identity Attestor](/user-guide/deploy-install/virtual-envs/monitor-network-identity-attestor).

12. **No Support for Dynamic Network Topologies**

    * Network Identity Attestor assumes static network topology.
    * Dynamic changes (for example, VM migration across segments) may require manual reconfiguration.