# How the Isolation Session Backend Uses Entra Cloud-Agent Credentials in Microsoft MXC

> Learn how the Isolation Session backend uses Entra cloud-agent credentials with Microsoft MXC. Discover how UPN and WAM tokens provision identity-specific users for isolated sessions.

- Repository: [Microsoft/mxc](https://github.com/microsoft/mxc)
- Tags: how-to-guide
- Published: 2026-06-07

---

**The Isolation Session backend consumes Entra user bundles containing a UPN and WAM token to provision identity-specific cloud-agent users and start isolated sessions via the Windows AI IsolationSession v2 APIs.**

The Microsoft MXC (Multiplatform eXecution Container) repository implements a stateful sandbox backend that integrates with Entra ID to create isolated execution environments bound to specific user identities. When callers supply an **Entra user bundle** in provision or start requests, the backend validates and forwards these credentials to the underlying Windows AI IsolationSession OS service, creating a first-class identity-bound sandbox managed entirely by the OS.

## Entra Credential Bundle Structure

The credential data is defined in [`src/core/wxc_common/src/models.rs`](https://github.com/microsoft/mxc/blob/main/src/core/wxc_common/src/models.rs) as the `IsolationSessionUser` struct:

```rust
pub struct IsolationSessionUser {
    pub upn: String,        // e.g. "alice@contoso.com"
    pub wam_token: String, // token passed straight to the OS service
}

```

This bundle is embedded in both `IsolationSessionProvisionConfig` and `IsolationSessionConfig`, allowing callers to specify the identity context for sandbox operations.

## Provisioning Cloud-Agent Users via V2 APIs

During the provision phase, the backend extracts the user bundle in [`src/backends/isolation_session/common/src/state_aware.rs`](https://github.com/microsoft/mxc/blob/main/src/backends/isolation_session/common/src/state_aware.rs) (lines 80–84):

```rust
let user = config.and_then(|c| c.user);
let provision_id = match &user {
    Some(u) => u.upn.clone(),
    None => format!("wxc-{}", mint_random_token()),
};

```

If a user bundle is present, the code routes to the **v2 provisioning API** by calling `IsolationSessionManager::provision_agent_user_v2` (lines 90–94):

```rust
let provision_result = match &user {
    Some(u) => manager.provision_agent_user_v2(&u.wam_token),
    None => manager.provision_agent_user(),
};

```

According to the microsoft/mxc source code, the OS creates a **cloud-agent user** whose UPN becomes the sandbox’s provision ID (formatted as `iso:alice@contoso.com`). The provisioned user's OS account name is stored as `agent_user_name` for diagnostics.

## Starting Sessions with Identity Binding

When starting a sandbox, the backend checks for the Entra user bundle in [`state_aware.rs`](https://github.com/microsoft/mxc/blob/main/state_aware.rs) (lines 40–44). The `start` method mirrors the provision logic, calling `start_session_v2` when credentials are present (lines 41–43):

```rust
let start_result = match cfg.user {
    Some(u) => manager.start_session_v2(configuration_id, &u.wam_token),
    None => manager.start_session(configuration_id),
};

```

The `configuration_id` comes from the user-supplied `IsolationSessionConfig`. The OS service launches a session bound to the previously created cloud-agent user, ensuring all process execution occurs within that identity context.

## Validation and Security Enforcement

Before any OS calls occur, the backend validates the credential bundle to prevent mismatches. The `validate_isolation_session_user` function checks for well-formed UPN syntax and non-empty WAM tokens (lines 90–92).

During start validation (lines 102–110), the backend enforces that **Entra sandboxes must provide a user bundle**, and that the UPN exactly matches the sandbox ID (case-insensitive). If validation fails, the backend returns `MxcError::MalformedRequest` or `PolicyValidation` errors, preventing unauthorized session starts against provisioned identities.

## Deprovisioning and Cleanup

When tearing down the sandbox, no credential data is required. The backend calls `IsolationSessionManager::deprovision_agent_user` (lines 71–74) in [`state_aware.rs`](https://github.com/microsoft/mxc/blob/main/state_aware.rs) to remove the OS-side cloud-agent user and unregister the client, completing the lifecycle.

## Implementation Examples

### Provisioning an Entra-Backed Sandbox

```rust
use wxc_common::models::{ExecutionRequest, IsolationSessionProvisionConfig, IsolationSessionUser};

let request = ExecutionRequest::default();
let user = IsolationSessionUser {
    upn: "alice@contoso.com".to_string(),
    wam_token: "eyJhbGci...".to_string(),
};

let provision_cfg = IsolationSessionProvisionConfig {
    user: Some(user),
    ..Default::default()
};

let runner = IsolationSessionRunner::new();
let provision_res = runner.provision(&request, Some(provision_cfg))?;
println!("Sandbox ID: {}", provision_res.sandbox_id);

```

This corresponds to the provision logic at lines 80–94 in [`state_aware.rs`](https://github.com/microsoft/mxc/blob/main/state_aware.rs), where the WAM token is passed to `provision_agent_user_v2`.

### Starting the Bound Session

```rust
use wxc_common::models::{IsolationSessionConfig, IsolationSessionUser};

let start_cfg = IsolationSessionConfig {
    user: Some(IsolationSessionUser {
        upn: "alice@contoso.com".to_string(),
        wam_token: "eyJhbGci...".to_string(),
    }),
    ..Default::default()
};

let start_res = runner.start("iso:alice@contoso.com", &request, Some(start_cfg))?;

```

This invokes `start_session_v2` as implemented at lines 41–43, routing the WAM token to the OS service to bind the session to the provisioned cloud-agent user.

### Validation Error Handling

```rust
let err = runner
    .validate_start("iso:alice@contoso.com", &request, None)
    .unwrap_err();

assert_eq!(err.code, MxcErrorCode::MalformedRequest);
// Error: "Entra sandbox requires user"

```

This demonstrates the validation branch at lines 102–110 that enforces credential presence for Entra-bound sandboxes.

## Summary

- The Isolation Session backend accepts **Entra user bundles** (`upn` + `wamToken`) via `IsolationSessionUser` defined in [`src/core/wxc_common/src/models.rs`](https://github.com/microsoft/mxc/blob/main/src/core/wxc_common/src/models.rs).
- Provisioning routes to `provision_agent_user_v2` in [`state_aware.rs`](https://github.com/microsoft/mxc/blob/main/state_aware.rs) (lines 90–94), creating an OS cloud-agent user identified by the UPN.
- Starting sessions requires matching credentials passed to `start_session_v2` (lines 41–43), binding execution to the provisioned identity.
- Validation logic at lines 90–92 and 102–110 prevents mismatches between sandbox IDs and user identities.
- Deprovisioning cleans up the cloud-agent user via `deprovision_agent_user` (lines 71–74) without requiring credential re-submission.

## Frequently Asked Questions

### What fields are required in the Entra credential bundle?

The `IsolationSessionUser` struct requires two fields: `upn` (the User Principal Name, e.g., `alice@contoso.com`) and `wam_token` (the Windows Authentication Manager token). Both are mandatory when provisioning or starting an Entra-backed sandbox, as validated by `validate_isolation_session_user` in [`state_aware.rs`](https://github.com/microsoft/mxc/blob/main/state_aware.rs).

### How does the backend prevent sandbox ID and user identity mismatches?

Before starting a session, the `validate_start` logic in [`state_aware.rs`](https://github.com/microsoft/mxc/blob/main/state_aware.rs) (lines 102–110) performs a case-insensitive comparison between the sandbox ID and the supplied UPN. If they do not match, or if the user bundle is missing for an Entra sandbox, the backend returns `MxcError::MalformedRequest`, ensuring the session can only be started by the identity that provisioned it.

### What happens to the cloud-agent user when the sandbox is deprovisioned?

During deprovisioning, the backend calls `IsolationSessionManager::deprovision_agent_user` (lines 71–74 in [`state_aware.rs`](https://github.com/microsoft/mxc/blob/main/state_aware.rs)), which removes the OS-side cloud-agent user and unregisters the client. No credential data is required for this cleanup phase, as the OS manages the user lifecycle based on the provision ID.

### Which Windows AI IsolationSession API version handles Entra credentials?

The backend uses the **v2** APIs specifically: `provision_agent_user_v2` and `start_session_v2` from [`src/backends/isolation_session/common/src/manager.rs`](https://github.com/microsoft/mxc/blob/main/src/backends/isolation_session/common/src/manager.rs). These methods accept WAM tokens directly and are distinct from the legacy v1 APIs that do not support Entra identity binding.