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

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 as the IsolationSessionUser struct:

pub struct IsolationSessionUser {
    pub upn: String,        // e.g. "[email protected]"
    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 (lines 80–84):

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):

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:[email protected]). 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 (lines 40–44). The start method mirrors the provision logic, calling start_session_v2 when credentials are present (lines 41–43):

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 to remove the OS-side cloud-agent user and unregister the client, completing the lifecycle.

Implementation Examples

Provisioning an Entra-Backed Sandbox

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

let request = ExecutionRequest::default();
let user = IsolationSessionUser {
    upn: "[email protected]".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, where the WAM token is passed to provision_agent_user_v2.

Starting the Bound Session

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

let start_cfg = IsolationSessionConfig {
    user: Some(IsolationSessionUser {
        upn: "[email protected]".to_string(),
        wam_token: "eyJhbGci...".to_string(),
    }),
    ..Default::default()
};

let start_res = runner.start("iso:[email protected]", &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

let err = runner
    .validate_start("iso:[email protected]", &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.
• Provisioning routes to provision_agent_user_v2 in 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., [email protected]) 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.

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

Before starting a session, the validate_start logic in 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), 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. These methods accept WAM tokens directly and are distinct from the legacy v1 APIs that do not support Entra identity binding.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}