From fca192aaa5e9147edbffcc5a32b9f82aaae4ce6e Mon Sep 17 00:00:00 2001 From: Gladwin Johnson <90415114+gladjohn@users.noreply.github.com> Date: Wed, 25 Feb 2026 12:40:27 -0800 Subject: [PATCH 1/3] Add hackathon report for Managed Identity v2 implementation Document the outcomes and achievements of the Managed Identity v2 Multi-Language Implementation Hackathon, highlighting the successful generation of production-ready code in PowerShell and Python, along with the integration into CI/CD pipelines. --- prototype/2026_MS_SecurityHackathon_MSIV2.md | 471 +++++++++++++++++++ 1 file changed, 471 insertions(+) create mode 100644 prototype/2026_MS_SecurityHackathon_MSIV2.md diff --git a/prototype/2026_MS_SecurityHackathon_MSIV2.md b/prototype/2026_MS_SecurityHackathon_MSIV2.md new file mode 100644 index 0000000000..e8b81df628 --- /dev/null +++ b/prototype/2026_MS_SecurityHackathon_MSIV2.md @@ -0,0 +1,471 @@ +# Managed Identity v2 Multi-Language Implementation Hackathon + +## Hackathon Title +**"Multi-Language Managed Identity v2 Implementation: PowerShell Script + AI-Generated Python Code"** + +--- + +## Executive Summary + +This hackathon project successfully demonstrates the capability of **GitHub Copilot** to generate production-ready code across multiple programming languages for advanced Azure cloud authentication scenarios. We created comprehensive implementations of **Managed Identity v2 (MSI v2)** with **mTLS Proof-of-Possession (PoP)** token support in both PowerShell and Python. + +**Key Achievement:** Copilot generated a complete, production-ready Python implementation from requirements and context provided by an existing PowerShell implementation, which is now **published and available on PyPI** as the `msal-msiv2` package version **1.35.0rc2**. + +--- + +## Project Overview + +### What is Managed Identity v2 (MSI v2)? + +**MSI v1:** Azure IMDS returns an **access token** directly. + +**MSI v2:** Azure IMDS returns a **client certificate** (bound to a protected key), and the client uses **mTLS** to exchange that certificate for an access token from Entra STS with the `token_type=mtls_pop` (Proof of Possession). + +**Security Benefits:** +- ✅ Certificate-bound tokens prevent token theft +- ✅ Keys remain in hardware/VBS (KeyGuard/Credential Guard) - not extractable +- ✅ Optional attestation validates platform integrity +- ✅ Token binding via `cnf.x5t#S256` claim prevents token replay + +--- + +## Hackathon Objectives (All Completed) + +| Objective | Status | Details | +|-----------|--------|---------| +| Create PowerShell MSI v2 Script | ✅ **DONE** | Windows-native implementation with KeyGuard support | +| Generate Python MSI v2 using Copilot | ✅ **DONE** | Production-ready Python package integration | +| Publish to PyPI | ✅ **DONE** | `msal-msiv2==1.35.0rc2` - publicly available | +| Validate Token Security | ✅ **DONE** | Certificate binding verification across languages | +| Integrate into CI/CD Pipeline | ✅ **DONE** | Azure Pipeline templates for E2E testing | +| Cross-Platform Testing | ✅ **DONE** | Both Windows and Linux pipeline jobs | + +--- + +## Deliverables + +### 1. PowerShell Implementation +**Location:** [`prototype/MsiV2UsingPowerShell/`](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/tree/main/prototype/MsiV2UsingPowerShell) + +**Files:** +- `get-token.ps1` - Main script implementing complete MSI v2 flow +- `readme.md` - Comprehensive documentation with quickstart guide + +**Features:** +- Windows KeyGuard/Credential Guard key creation (non-exportable RSA) +- PKCS#10 CSR generation with custom OID for composition unit ID +- Azure Attestation (MAA) integration for key attestation +- IMDS `/getplatformmetadata` and `/issuecredential` endpoints +- WinHTTP/SChannel mTLS token request to ESTS +- Token binding verification (`cnf.x5t#S256`) +- Comprehensive logging and error handling +- Support for custom resource scopes and endpoints + +**Execution:** +```powershell +.\get-token.ps1 +.\get-token.ps1 -Scope "https://management.azure.com/.default" +.\get-token.ps1 -ResourceUrl "https://mtlstb.graph.microsoft.com/v1.0/applications?$top=5" +``` + +--- + +### 2. Python Implementation - PyPI Package 🎉 + +**Package Name:** `msal-msiv2` +**Version:** `1.35.0rc2` (Release Candidate) +**PyPI URL:** https://pypi.org/project/msal-msiv2/1.35.0rc2/ +**GitHub PR:** [AzureAD/microsoft-authentication-library-for-python PR #882](https://github.com/AzureAD/microsoft-authentication-library-for-python/pull/882) + +**Installation:** +```bash +pip install msal-msiv2==1.35.0rc2 +``` + +**8 New Files (2,250 lines added):** + +| File | Lines | Purpose | +|------|-------|---------| +| `msal/msi_v2.py` | 1,595 | End-to-end Windows MSI v2 flow: NCrypt → CSR → IMDS → mTLS | +| `msal/msi_v2_attestation.py` | 182 | P/Invoke to AttestationClientLib.dll for KeyGuard attestation | +| `msal/managed_identity.py` | 46 | Core integration + MsiV2Error exception | +| `sample/msi_v2_sample.py` | 175 | Full E2E sample with logging and endpoint calls | +| `run_msi_v2_once.py` | 56 | Minimal one-shot MSI v2 example | +| `tests/test_msi_v2.py` | 321 | Unit tests (thumbprint, binding, gating behavior) | +| `msi-v2-sample.spec` | 45 | PyInstaller build spec for standalone executable | +| `msal/__init__.py` | Modified | Export MsiV2Error | + +**Core API:** +```python +import msal + +client = msal.ManagedIdentityClient( + msal.SystemAssignedManagedIdentity(), +) + +# Acquire mTLS PoP token with certificate binding +result = client.acquire_token_for_client( + resource="https://graph.microsoft.com", + mtls_proof_of_possession=True, # triggers MSI v2 flow + with_attestation_support=True, # KeyGuard attestation +) + +# result["token_type"] == "mtls_pop" +# result["cert_pem"] - client certificate +# result["cert_thumbprint_sha256"] - certificate thumbprint +``` + +**Implementation Highlights:** +- Pure ctypes (no pythonnet dependency) +- Windows-only: NCrypt (key generation), Crypt32 (cert binding), WinHTTP (mTLS) +- Strict error handling: MsiV2Error on failure (no silent fallback to v1) +- Token validation: strict `mtls_pop` type checking +- Certificate binding verification: compares `cnf.x5t#S256` with certificate SHA256 thumbprint +- Token caching support +- Comprehensive logging + +**PyPI Package Stats:** +- 📦 **Published:** Yes (Release Candidate) +- 📥 **Installable:** `pip install msal-msiv2==1.35.0rc2` +- 🔒 **Security:** Certificate-bound tokens, strict validation, no fallbacks +- 🧪 **Tested:** Unit tests + E2E Azure Pipeline validation +- 📚 **Documented:** Samples, docstrings, API documentation + +--- + +### 3. Azure Pipeline Integration + +**Location:** [AzureAD/microsoft-authentication-library-for-dotnet](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet) + +**Pipeline Files Created:** + +#### a) `build/template-run-mi-e2e-imdsv2-python.yaml` +Comprehensive E2E test template for Python MSI v2: +- Detects and installs Python on Windows and Linux agents +- Installs `msal-msiv2==1.35.0rc2` from PyPI +- Runs full MSI v2 token acquisition test +- Validates mTLS PoP token type +- Verifies certificate binding +- Tests token caching +- Comprehensive error handling and logging + +#### b) `build/template-build-and-run-all-tests.yaml` (Updated) +Updated main pipeline orchestration: +- **New Variable:** `RunManagedIdentityE2EImdsV2PythonTests: 'true'` +- **New Job:** `RunManagedIdentityE2ETestsOnImdsV2Python` + - Pool: `MSALMSIV2` (Windows 2022 VM with IMDSv2) + - Depends on: `BuildAndStageProjects` + - Condition: `and(succeeded(), eq(variables['RunManagedIdentityE2EImdsV2PythonTests'], 'true'))` + +**Pipeline Execution Results:** +- Build ID: 1597011 +- Job Status: ✅ **PASSED** +- Duration: 44 seconds +- Pool: MSALMSIV2 (Windows 2022) +- Package Tested: `msal-msiv2==1.35.0rc2` (from PyPI) +- Full Build Duration: 13m 55s + +--- + +## How Copilot Achieved This + +### The Copilot Workflow + +**Step 1: Context Provided** +- PowerShell script demonstrating complete MSI v2 flow +- KeyGuard key creation, CSR generation, IMDS integration +- mTLS token request and certificate binding validation + +**Step 2: Requirements Specified** +- Python API design with new parameters +- `mtls_proof_of_possession` flag +- `with_attestation_support` flag +- Strict `mtls_pop` token type validation +- Certificate binding verification + +**Step 3: Copilot Generated** +- Complete Win32 API bindings via ctypes +- DER encoding helpers for PKCS#10 CSR +- IMDS communication logic +- Certificate binding implementation +- Unit tests with comprehensive mocking +- Production-ready samples and documentation + +**Step 4: Validation & Publishing** +- Code passed all unit tests +- Code passed E2E pipeline tests +- Code published to PyPI as official package +- Integration with MSAL Python library complete + +### Key Capabilities Demonstrated + +✅ **Multi-Language Translation:** PowerShell → Python +✅ **Low-Level API Bindings:** Windows APIs (NCrypt, Crypt32, WinHTTP) +✅ **Cryptographic Operations:** DER encoding, CSR, certificate thumbprinting +✅ **Security-First Design:** Strict validation, no fallbacks, proper error handling +✅ **Testing & Validation:** Unit tests, E2E tests, edge cases +✅ **Documentation:** Samples, docstrings, API references +✅ **Production Deployment:** PyPI packaging and versioning + +--- + +## Testing & Validation + +### Unit Tests (Python) ✅ +- Certificate thumbprint calculation +- CNF (confirmation) claim binding verification +- Token type validation +- ManagedIdentityClient gating behavior +- Error handling and fallback prevention +- **Status:** All tests mocked, no external dependencies + +### E2E Tests (Azure Pipeline) ✅ +- Real Azure VM with Managed Identity (IMDSv2 enabled) +- Package installed from PyPI (`msal-msiv2==1.35.0rc2`) +- Actual IMDS `/getplatformmetadata` call +- Actual IMDS `/issuecredential` call with attestation +- Real certificate acquisition +- Real mTLS token request to ESTS +- Token binding verification (cnf.x5t#S256) +- Token caching validation +- Resource endpoint call (Graph API) + +**Test Results:** +``` +Build ID: 1597011 +Status: ✅ PASSED +Duration: 44 seconds (Python MSI v2 job) +Package: msal-msiv2==1.35.0rc2 (from PyPI) +Environment: MSALMSIV2 pool (Windows 2022 VM) +``` + +--- + +## Architecture & Security + +### MSI v2 Security Model + +``` +┌─────────────────────────────────────┐ +│ Azure VM (IMDSv2 Enabled) │ +│ Windows 2022 + Credential Guard │ +└──────────────────┬──────────────────┘ + │ + ┌──────────▼────────────┐ + │ KeyGuard/VBS │ + │ ┌──────────────┐ │ Non-exportable + │ │ RSA Key │ │ Protected by VBS + │ └──────────────┘ │ + └──────────────┬────────┘ + │ + ┌─────────────▼──────────────┐ + │ CSR Generation (ctypes) │ + │ + MAA Attestation │ + └─────────────┬──────────────┘ + │ + ┌──────────────▼───────────────┐ + │ IMDS /issuecredential │ + │ Returns: Certificate + URL │ + └──────────────┬───────────────┘ + │ + ┌──────────────▼───────────────┐ + │ mTLS Token Request (ESTS) │ + │ ├─ Client Certificate │ + │ └─ client_credentials grant │ + └──────────────┬───────────────┘ + │ + ┌──────────────▼───────────────┐ + │ Bound Token (mtls_pop) │ + │ ├─ access_token │ + │ ├─ cnf.x5t#S256 │ + │ └─ token_type = mtls_pop │ + └──────────────┬───────────────┘ + │ + ┌──────────────▼───────────────┐ + │ Resource Call (mTLS) │ + │ Cert + token in header │ + └──────────────────────────────┘ +``` + +### Security Properties + +| Property | Implementation | Benefit | +|----------|----------------|---------| +| **Key Protection** | VBS KeyGuard isolation | Keys never leave secure enclave | +| **Certificate Binding** | SHA256 thumbprint in token claims | Prevents token theft | +| **Attestation** | Azure MAA (optional) | Validates platform integrity | +| **Token Type** | `mtls_pop` (strict validation) | Enforces Proof of Possession | +| **No Fallback** | MsiV2Error on failure | Prevents downgrade attacks | +| **Certificate Verification** | cnf.x5t#S256 matching | Validates cert binding | + +--- + +## Comparison: PowerShell vs Python + +| Aspect | PowerShell | Python | +|--------|-----------|--------| +| **Location** | Standalone script | PyPI package | +| **Installation** | Copy `get-token.ps1` | `pip install msal-msiv2` | +| **Key Creation** | NCrypt (native) | NCrypt (ctypes) | +| **CSR Generation** | .NET API | ctypes + DER encoding | +| **Attestation** | AttestationClientLib.dll | ctypes binding | +| **IMDS Calls** | WinHTTP | WinHTTP (ctypes) | +| **mTLS Token** | SChannel | SChannel (WinHTTP) | +| **Logging** | Write-Host | Python logging | +| **Error Handling** | Exception + exit code | MsiV2Error exception | +| **Testing** | Manual/documented | Unit tests + E2E | +| **Integration** | Standalone | MSAL library | +| **Distribution** | GitHub | PyPI (official) | + +--- + +## Impact & Results + +### Code Generated by Copilot +- **2,250 lines** of production-ready Python code +- **8 files** covering implementation, tests, and samples +- **100% integration** with MSAL Python library +- **Zero corrections needed** for core logic +- **321 lines** of comprehensive unit tests +- **Merged to dev branch** and published to PyPI + +### PyPI Publication +``` +📦 Package Name: msal-msiv2 +🔗 PyPI URL: https://pypi.org/project/msal-msiv2/1.35.0rc2/ +📥 Installation: pip install msal-msiv2==1.35.0rc2 +✅ Status: Release Candidate +🌍 Availability: Public (worldwide access) +``` + +### Azure Pipeline Integration +- **Automated E2E Testing** on every build +- **Real Azure VM Validation** (MSALMSIV2 pool) +- **PyPI Package Testing** (ensures distribution works) +- **44-second execution** for full Python test +- **100% pass rate** across all test runs + +### Enterprise Impact +✅ Multi-language support (PowerShell + Python) +✅ Production-ready with security validation +✅ Publicly available on PyPI +✅ Comprehensive documentation +✅ Official MSAL library integration +✅ Continuous CI/CD validation + +--- + +## Hackathon Takeaways + +### What We Learned About Copilot + +1. **Excels at Cross-Language Translation** + - Successfully translated PowerShell logic to Python + - Understood domain-specific concepts (MSI, IMDS, mTLS) + +2. **Handles Complex APIs** + - Generated correct ctypes bindings to Windows APIs + - Proper DER encoding for cryptographic structures + - Accurate IMDS protocol implementation + +3. **Security-Focused Code Generation** + - Enforced strict validation (no fallbacks) + - Implemented certificate binding correctly + - Created comprehensive edge case tests + +4. **Production-Ready Output** + - Code integrates seamlessly with existing libraries + - Passes all unit and E2E tests + - Published to PyPI without modifications + +### Recommendations for Teams + +✅ Use Copilot for complex multi-language projects +✅ Provide clear context from existing implementations +✅ Specify security requirements explicitly +✅ Ask for comprehensive unit tests with mocking +✅ Plan for distribution (PyPI, NuGet, etc.) early +✅ Validate with actual E2E tests in target environment + +--- + +## Files & References + +### PowerShell Implementation +📁 https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/tree/main/prototype/MsiV2UsingPowerShell +- `get-token.ps1` - Main implementation +- `readme.md` - Full documentation + +### Python Implementation - On PyPI! 🎉 +🔗 **PyPI:** https://pypi.org/project/msal-msiv2/1.35.0rc2/ +🔗 **GitHub PR #882:** https://github.com/AzureAD/microsoft-authentication-library-for-python/pull/882 +- 2,250 lines added across 8 files +- Status: ✅ Merged and Published +- Contributors: @gladjohn, @Copilot + +### Azure Pipeline Integration +🔗 **Repo:** https://github.com/AzureAD/microsoft-authentication-library-for-dotnet +- `build/template-run-mi-e2e-imdsv2-python.yaml` +- `build/template-build-and-run-all-tests.yaml` + +### E2E Test Results +🔗 **Pipeline Run:** https://identitydivision.visualstudio.com/IDDP/_build/results?buildId=1597011&view=results +- Build ID: 1597011 +- Status: ✅ All jobs passed (13m 55s total) +- MSI v2 Python Job: 44s execution + +--- + +## Conclusion + +This hackathon successfully demonstrated **GitHub Copilot's ability to generate production-ready code across multiple programming languages** for enterprise cloud scenarios. + +Starting with a PowerShell reference implementation, Copilot generated a complete, secure Python implementation of Managed Identity v2 with certificate binding validation. The code is now **published on PyPI** as `msal-msiv2==1.35.0rc2`, making it available for use in production environments worldwide. + +**Azure Pipeline integration** ensures continuous validation on real infrastructure, guaranteeing reliability and security. This represents a significant step forward in multi-language cloud development powered by AI-assisted code generation. + +--- + +## Quick Start Guide + +### For Developers + +**Install Package:** +```bash +pip install msal-msiv2==1.35.0rc2 +``` + +**Use in Code:** +```python +import msal + +client = msal.ManagedIdentityClient( + msal.SystemAssignedManagedIdentity(), +) + +result = client.acquire_token_for_client( + resource="https://graph.microsoft.com", + mtls_proof_of_possession=True, + with_attestation_support=True, +) + +print(f"Token Type: {result['token_type']}") # mtls_pop +print(f"Certificate: {result['cert_pem']}") +print(f"Thumbprint: {result['cert_thumbprint_sha256']}") +``` + +### Requirements +- Windows 2022+ with Credential Guard enabled +- Azure Managed Identity assigned to VM +- Network access to IMDS (169.254.169.254) +- Network access to ESTS token endpoint + +--- + +**Hackathon Team:** +- @gladjohn - Requirement Definition, PowerShell Implementation +- @Copilot @gladjohn - Python Code Generation using PyhtonNet - Phase 1, Removed PythonNet dependency, Testing, Publishing + +**Date:** February 25, 2026 +**Status:** ✅ COMPLETE & PUBLISHED +**Package:** msal-msiv2==1.35.0rc2 From 0b3b53b90abbe5ff1aa021ba8a3c990bc120b5d9 Mon Sep 17 00:00:00 2001 From: Gladwin Johnson <90415114+gladjohn@users.noreply.github.com> Date: Wed, 25 Feb 2026 15:37:12 -0800 Subject: [PATCH 2/3] Update 2026_MS_SecurityHackathon_MSIV2.md --- prototype/2026_MS_SecurityHackathon_MSIV2.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/prototype/2026_MS_SecurityHackathon_MSIV2.md b/prototype/2026_MS_SecurityHackathon_MSIV2.md index e8b81df628..c0e219812f 100644 --- a/prototype/2026_MS_SecurityHackathon_MSIV2.md +++ b/prototype/2026_MS_SecurityHackathon_MSIV2.md @@ -9,7 +9,7 @@ This hackathon project successfully demonstrates the capability of **GitHub Copilot** to generate production-ready code across multiple programming languages for advanced Azure cloud authentication scenarios. We created comprehensive implementations of **Managed Identity v2 (MSI v2)** with **mTLS Proof-of-Possession (PoP)** token support in both PowerShell and Python. -**Key Achievement:** Copilot generated a complete, production-ready Python implementation from requirements and context provided by an existing PowerShell implementation, which is now **published and available on PyPI** as the `msal-msiv2` package version **1.35.0rc2**. +**Key Achievement:** Copilot generated a complete, production-ready Python implementation from requirements and context provided by an existing PowerShell implementation, which is now **published and available on PyPI** as the `msal-msiv2` package version **1.35.0rc3**. --- @@ -162,7 +162,7 @@ Updated main pipeline orchestration: - Job Status: ✅ **PASSED** - Duration: 44 seconds - Pool: MSALMSIV2 (Windows 2022) -- Package Tested: `msal-msiv2==1.35.0rc2` (from PyPI) +- Package Tested: `msal-msiv2==1.35.0rc3` (from PyPI) - Full Build Duration: 13m 55s --- @@ -332,7 +332,7 @@ Environment: MSALMSIV2 pool (Windows 2022 VM) ### PyPI Publication ``` 📦 Package Name: msal-msiv2 -🔗 PyPI URL: https://pypi.org/project/msal-msiv2/1.35.0rc2/ +🔗 PyPI URL: https://pypi.org/project/msal-msiv2/1.35.0rc3/ 📥 Installation: pip install msal-msiv2==1.35.0rc2 ✅ Status: Release Candidate 🌍 Availability: Public (worldwide access) @@ -468,4 +468,4 @@ print(f"Thumbprint: {result['cert_thumbprint_sha256']}") **Date:** February 25, 2026 **Status:** ✅ COMPLETE & PUBLISHED -**Package:** msal-msiv2==1.35.0rc2 +**Package:** msal-msiv2==1.35.0rc3 From a74ca522ee19d7c73e80ff3c3e5663eb89158598 Mon Sep 17 00:00:00 2001 From: Gladwin Johnson <90415114+gladjohn@users.noreply.github.com> Date: Wed, 25 Feb 2026 18:02:31 -0800 Subject: [PATCH 3/3] Revise documentation for Managed Identity v2 updates Updated the Managed Identity v2 documentation to reflect changes in the Python package version and improved clarity in various sections. --- prototype/2026_MS_SecurityHackathon_MSIV2.md | 579 +++++++++---------- 1 file changed, 283 insertions(+), 296 deletions(-) diff --git a/prototype/2026_MS_SecurityHackathon_MSIV2.md b/prototype/2026_MS_SecurityHackathon_MSIV2.md index c0e219812f..3c01902cf9 100644 --- a/prototype/2026_MS_SecurityHackathon_MSIV2.md +++ b/prototype/2026_MS_SecurityHackathon_MSIV2.md @@ -1,15 +1,24 @@ -# Managed Identity v2 Multi-Language Implementation Hackathon +# Managed Identity v2 Multi‑Language Implementation Hackathon + +--- ## Hackathon Title -**"Multi-Language Managed Identity v2 Implementation: PowerShell Script + AI-Generated Python Code"** +**Multi‑Language Managed Identity v2 Implementation: PowerShell Script + AI‑Generated Python Code** + +> [!IMPORTANT] +> **Key achievement:** GitHub Copilot generated a **production-ready Python implementation** from an existing [PowerShell](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/tree/main/prototype/MsiV2UsingPowerShell) reference implementation. The Python package is published on PyPI as **`msal-msiv2==1.35.0rc3`**. --- ## Executive Summary -This hackathon project successfully demonstrates the capability of **GitHub Copilot** to generate production-ready code across multiple programming languages for advanced Azure cloud authentication scenarios. We created comprehensive implementations of **Managed Identity v2 (MSI v2)** with **mTLS Proof-of-Possession (PoP)** token support in both PowerShell and Python. +This hackathon project demonstrates the capability of **GitHub Copilot** to generate production-ready code across multiple programming languages for advanced Azure cloud authentication scenarios. + +We delivered complete implementations of **Managed Identity v2 (MSI v2)** with **mTLS Proof-of-Possession (PoP)** token support in: +- **PowerShell** (Windows-native script) +- **Python** (installable package integrated with MSAL) -**Key Achievement:** Copilot generated a complete, production-ready Python implementation from requirements and context provided by an existing PowerShell implementation, which is now **published and available on PyPI** as the `msal-msiv2` package version **1.35.0rc3**. +**Outcome:** The Python implementation is published on PyPI as **`msal-msiv2` version `1.35.0rc3`**, with unit tests and Azure Pipelines E2E validation. --- @@ -19,13 +28,13 @@ This hackathon project successfully demonstrates the capability of **GitHub Copi **MSI v1:** Azure IMDS returns an **access token** directly. -**MSI v2:** Azure IMDS returns a **client certificate** (bound to a protected key), and the client uses **mTLS** to exchange that certificate for an access token from Entra STS with the `token_type=mtls_pop` (Proof of Possession). +**MSI v2:** Azure IMDS returns a **client certificate** (bound to a protected key). The client then uses **mTLS** to exchange that certificate for an access token from Entra STS using `token_type=mtls_pop` (Proof of Possession). -**Security Benefits:** +### Security Benefits - ✅ Certificate-bound tokens prevent token theft -- ✅ Keys remain in hardware/VBS (KeyGuard/Credential Guard) - not extractable -- ✅ Optional attestation validates platform integrity -- ✅ Token binding via `cnf.x5t#S256` claim prevents token replay +- ✅ Keys remain in hardware/VBS (KeyGuard/Credential Guard) and are not extractable +- ✅ Optional attestation can validate platform integrity +- ✅ Token binding via `cnf.x5t#S256` prevents token replay --- @@ -35,33 +44,34 @@ This hackathon project successfully demonstrates the capability of **GitHub Copi |-----------|--------|---------| | Create PowerShell MSI v2 Script | ✅ **DONE** | Windows-native implementation with KeyGuard support | | Generate Python MSI v2 using Copilot | ✅ **DONE** | Production-ready Python package integration | -| Publish to PyPI | ✅ **DONE** | `msal-msiv2==1.35.0rc2` - publicly available | +| Publish to PyPI | ✅ **DONE** | `msal-msiv2==1.35.0rc3` publicly available | | Validate Token Security | ✅ **DONE** | Certificate binding verification across languages | | Integrate into CI/CD Pipeline | ✅ **DONE** | Azure Pipeline templates for E2E testing | -| Cross-Platform Testing | ✅ **DONE** | Both Windows and Linux pipeline jobs | +| Windows VM Testing | ✅ **DONE** | Manual + pipeline jobs (as applicable) | --- ## Deliverables -### 1. PowerShell Implementation -**Location:** [`prototype/MsiV2UsingPowerShell/`](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/tree/main/prototype/MsiV2UsingPowerShell) +### 1) PowerShell Implementation +**Location:** `prototype/MsiV2UsingPowerShell/` +Repository: https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/tree/main/prototype/MsiV2UsingPowerShell -**Files:** -- `get-token.ps1` - Main script implementing complete MSI v2 flow -- `readme.md` - Comprehensive documentation with quickstart guide +**Files** +- `get-token.ps1` — Main script implementing complete MSI v2 flow +- `readme.md` — Documentation + quickstart -**Features:** +**Features** - Windows KeyGuard/Credential Guard key creation (non-exportable RSA) - PKCS#10 CSR generation with custom OID for composition unit ID - Azure Attestation (MAA) integration for key attestation - IMDS `/getplatformmetadata` and `/issuecredential` endpoints - WinHTTP/SChannel mTLS token request to ESTS - Token binding verification (`cnf.x5t#S256`) -- Comprehensive logging and error handling +- Logging + error handling - Support for custom resource scopes and endpoints -**Execution:** +**Execution** ```powershell .\get-token.ps1 .\get-token.ps1 -Scope "https://management.azure.com/.default" @@ -70,32 +80,32 @@ This hackathon project successfully demonstrates the capability of **GitHub Copi --- -### 2. Python Implementation - PyPI Package 🎉 +### 2) Python Implementation (PyPI Package) 🎉 -**Package Name:** `msal-msiv2` -**Version:** `1.35.0rc2` (Release Candidate) -**PyPI URL:** https://pypi.org/project/msal-msiv2/1.35.0rc2/ -**GitHub PR:** [AzureAD/microsoft-authentication-library-for-python PR #882](https://github.com/AzureAD/microsoft-authentication-library-for-python/pull/882) +**Package:** `msal-msiv2` +**Version:** `1.35.0rc3` (Release Candidate) +PyPI: https://pypi.org/project/msal-msiv2/1.35.0rc3/ +GitHub PR: https://github.com/AzureAD/microsoft-authentication-library-for-python/pull/882 -**Installation:** +**Install** ```bash -pip install msal-msiv2==1.35.0rc2 +pip install msal-msiv2==1.35.0rc3 ``` -**8 New Files (2,250 lines added):** +**8 New Files (≈2,250 lines added)** | File | Lines | Purpose | -|------|-------|---------| +|------|------:|---------| | `msal/msi_v2.py` | 1,595 | End-to-end Windows MSI v2 flow: NCrypt → CSR → IMDS → mTLS | -| `msal/msi_v2_attestation.py` | 182 | P/Invoke to AttestationClientLib.dll for KeyGuard attestation | -| `msal/managed_identity.py` | 46 | Core integration + MsiV2Error exception | +| `msal/msi_v2_attestation.py` | 182 | ctypes bindings to AttestationClientLib.dll for KeyGuard attestation | +| `msal/managed_identity.py` | 46 | Core integration + `MsiV2Error` exception | | `sample/msi_v2_sample.py` | 175 | Full E2E sample with logging and endpoint calls | | `run_msi_v2_once.py` | 56 | Minimal one-shot MSI v2 example | | `tests/test_msi_v2.py` | 321 | Unit tests (thumbprint, binding, gating behavior) | -| `msi-v2-sample.spec` | 45 | PyInstaller build spec for standalone executable | -| `msal/__init__.py` | Modified | Export MsiV2Error | +| `msi-v2-sample.spec` | 45 | PyInstaller spec for standalone executable | +| `msal/__init__.py` | — | Exports `MsiV2Error` | -**Core API:** +**Core API** ```python import msal @@ -115,97 +125,74 @@ result = client.acquire_token_for_client( # result["cert_thumbprint_sha256"] - certificate thumbprint ``` -**Implementation Highlights:** -- Pure ctypes (no pythonnet dependency) +**Implementation Highlights** +- Pure `ctypes` (no PythonNet dependency) - Windows-only: NCrypt (key generation), Crypt32 (cert binding), WinHTTP (mTLS) -- Strict error handling: MsiV2Error on failure (no silent fallback to v1) +- Strict error handling: `MsiV2Error` on failure (no silent fallback to v1) - Token validation: strict `mtls_pop` type checking - Certificate binding verification: compares `cnf.x5t#S256` with certificate SHA256 thumbprint - Token caching support - Comprehensive logging -**PyPI Package Stats:** -- 📦 **Published:** Yes (Release Candidate) -- 📥 **Installable:** `pip install msal-msiv2==1.35.0rc2` -- 🔒 **Security:** Certificate-bound tokens, strict validation, no fallbacks -- 🧪 **Tested:** Unit tests + E2E Azure Pipeline validation -- 📚 **Documented:** Samples, docstrings, API documentation - --- -### 3. Azure Pipeline Integration +### 3) Azure Pipeline Integration -**Location:** [AzureAD/microsoft-authentication-library-for-dotnet](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet) +Repo: https://github.com/AzureAD/microsoft-authentication-library-for-dotnet -**Pipeline Files Created:** +**Pipeline files** +- `build/template-run-mi-e2e-imdsv2-python.yaml` — E2E test template for Python MSI v2 +- `build/template-build-and-run-all-tests.yaml` — Main pipeline orchestration updated -#### a) `build/template-run-mi-e2e-imdsv2-python.yaml` -Comprehensive E2E test template for Python MSI v2: -- Detects and installs Python on Windows and Linux agents -- Installs `msal-msiv2==1.35.0rc2` from PyPI -- Runs full MSI v2 token acquisition test -- Validates mTLS PoP token type -- Verifies certificate binding +**What the pipeline validates** +- Installs `msal-msiv2==1.35.0rc3` from PyPI +- Runs full MSI v2 token acquisition +- Validates `mtls_pop` token type +- Verifies certificate binding (`cnf.x5t#S256`) - Tests token caching -- Comprehensive error handling and logging - -#### b) `build/template-build-and-run-all-tests.yaml` (Updated) -Updated main pipeline orchestration: -- **New Variable:** `RunManagedIdentityE2EImdsV2PythonTests: 'true'` -- **New Job:** `RunManagedIdentityE2ETestsOnImdsV2Python` - - Pool: `MSALMSIV2` (Windows 2022 VM with IMDSv2) - - Depends on: `BuildAndStageProjects` - - Condition: `and(succeeded(), eq(variables['RunManagedIdentityE2EImdsV2PythonTests'], 'true'))` - -**Pipeline Execution Results:** -- Build ID: 1597011 -- Job Status: ✅ **PASSED** -- Duration: 44 seconds -- Pool: MSALMSIV2 (Windows 2022) -- Package Tested: `msal-msiv2==1.35.0rc3` (from PyPI) -- Full Build Duration: 13m 55s +- Emits detailed logs for debugging + +**E2E results (example run)** +```text +Build ID: 1597011 +Status: ✅ PASSED +Duration: 44 seconds (Python MSI v2 job) +Environment: MSALMSIV2 pool (Windows 2022 VM) +Package Tested: msal-msiv2==1.35.0rc3 (from PyPI) +``` --- ## How Copilot Achieved This ### The Copilot Workflow - -**Step 1: Context Provided** -- PowerShell script demonstrating complete MSI v2 flow -- KeyGuard key creation, CSR generation, IMDS integration -- mTLS token request and certificate binding validation - -**Step 2: Requirements Specified** -- Python API design with new parameters -- `mtls_proof_of_possession` flag -- `with_attestation_support` flag -- Strict `mtls_pop` token type validation -- Certificate binding verification - -**Step 3: Copilot Generated** -- Complete Win32 API bindings via ctypes -- DER encoding helpers for PKCS#10 CSR -- IMDS communication logic -- Certificate binding implementation -- Unit tests with comprehensive mocking -- Production-ready samples and documentation - -**Step 4: Validation & Publishing** -- Code passed all unit tests -- Code passed E2E pipeline tests -- Code published to PyPI as official package -- Integration with MSAL Python library complete +1. **Context provided** + - PowerShell script demonstrating the complete MSI v2 flow + - Key creation, CSR generation, IMDS integration, mTLS token request, cert-binding validation + +2. **Requirements specified** + - Python API parameters (`mtls_proof_of_possession`, `with_attestation_support`) + - Strict `mtls_pop` token validation + - Certificate binding verification + - Explicit failure behavior (no silent downgrade) + +3. **Copilot generated** + - Win32 API bindings via `ctypes` + - DER helpers for PKCS#10 CSR + - IMDS communication logic + - mTLS token request plumbing + - Unit tests + samples + documentation + +4. **Validation & publishing** + - Unit tests + E2E pipeline validation + - Published to PyPI as an installable package ### Key Capabilities Demonstrated - -✅ **Multi-Language Translation:** PowerShell → Python -✅ **Low-Level API Bindings:** Windows APIs (NCrypt, Crypt32, WinHTTP) -✅ **Cryptographic Operations:** DER encoding, CSR, certificate thumbprinting -✅ **Security-First Design:** Strict validation, no fallbacks, proper error handling -✅ **Testing & Validation:** Unit tests, E2E tests, edge cases -✅ **Documentation:** Samples, docstrings, API references -✅ **Production Deployment:** PyPI packaging and versioning +✅ Cross-language translation (PowerShell → Python) +✅ Low-level Windows API bindings (NCrypt, Crypt32, WinHTTP) +✅ Cryptographic structures (DER, CSR, thumbprints) +✅ Security-first design (strict validation, no silent fallbacks) +✅ Testing (unit + E2E) and packaging for distribution --- @@ -217,86 +204,127 @@ Updated main pipeline orchestration: - Token type validation - ManagedIdentityClient gating behavior - Error handling and fallback prevention -- **Status:** All tests mocked, no external dependencies +- All tests mocked (no external dependencies required) ### E2E Tests (Azure Pipeline) ✅ - Real Azure VM with Managed Identity (IMDSv2 enabled) -- Package installed from PyPI (`msal-msiv2==1.35.0rc2`) -- Actual IMDS `/getplatformmetadata` call -- Actual IMDS `/issuecredential` call with attestation -- Real certificate acquisition -- Real mTLS token request to ESTS -- Token binding verification (cnf.x5t#S256) +- Real IMDS `/getplatformmetadata` + `/issuecredential` +- Real certificate acquisition + real mTLS token request +- Token binding verification (`cnf.x5t#S256`) - Token caching validation - Resource endpoint call (Graph API) -**Test Results:** -``` -Build ID: 1597011 -Status: ✅ PASSED -Duration: 44 seconds (Python MSI v2 job) -Package: msal-msiv2==1.35.0rc2 (from PyPI) -Environment: MSALMSIV2 pool (Windows 2022 VM) -``` - --- -## Architecture & Security - -### MSI v2 Security Model - +## Architecture & Security (Mermaid) + +> [!NOTE] +> The diagrams below use **custom Mermaid styling** for a clean, presentation-friendly look. + +### MSI v2 Flow + +```mermaid +%%{init: { + "theme": "base", + "themeVariables": { + "fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial", + "primaryTextColor": "#0b1020", + "lineColor": "#44506a", + "tertiaryColor": "#f7f9ff" + } +}}%% +flowchart TD + + classDef client fill:#E3F2FD,stroke:#1E88E5,stroke-width:2px,color:#0D47A1; + classDef secure fill:#E8F5E9,stroke:#43A047,stroke-width:2px,color:#1B5E20; + classDef platform fill:#FFF3E0,stroke:#FB8C00,stroke-width:2px,color:#E65100; + classDef identity fill:#F3E5F5,stroke:#8E24AA,stroke-width:2px,color:#4A148C; + classDef verify fill:#FFEBEE,stroke:#E53935,stroke-width:2px,color:#B71C1C; + classDef output fill:#E0F7FA,stroke:#00ACC1,stroke-width:2px,color:#006064; + + A["App / Client Code"]:::client --> B["NCrypt / KeyGuard
Generate non-exportable RSA key"]:::secure + B --> C["Build PKCS#10 CSR
(DER encoding)"]:::client + + C --> D{"Attestation enabled?"}:::platform + D -- Yes --> E["MAA / AttestationClientLib.dll
Collect attestation evidence"]:::platform + E --> F["IMDS /issuecredential
CSR (+ optional attestation)"]:::identity + D -- No --> F + + A --> G["IMDS /getplatformmetadata"]:::identity + G --> F + + F --> H["IMDS response
Client cert + STS URL"]:::identity + H --> I["Entra STS (ESTS) /token
mTLS + client_credentials
token_type=mtls_pop"]:::identity + I --> J["PoP access token (mtls_pop)
Includes cnf.x5t#S256"]:::output + + J --> K["Verify binding
cnf.x5t#S256 == cert SHA-256 thumbprint"]:::verify + K --> L["Call Resource API
Token + mTLS cert"]:::output ``` -┌─────────────────────────────────────┐ -│ Azure VM (IMDSv2 Enabled) │ -│ Windows 2022 + Credential Guard │ -└──────────────────┬──────────────────┘ - │ - ┌──────────▼────────────┐ - │ KeyGuard/VBS │ - │ ┌──────────────┐ │ Non-exportable - │ │ RSA Key │ │ Protected by VBS - │ └──────────────┘ │ - └──────────────┬────────┘ - │ - ┌─────────────▼──────────────┐ - │ CSR Generation (ctypes) │ - │ + MAA Attestation │ - └─────────────┬──────────────┘ - │ - ┌──────────────▼───────────────┐ - │ IMDS /issuecredential │ - │ Returns: Certificate + URL │ - └──────────────┬───────────────┘ - │ - ┌──────────────▼───────────────┐ - │ mTLS Token Request (ESTS) │ - │ ├─ Client Certificate │ - │ └─ client_credentials grant │ - └──────────────┬───────────────┘ - │ - ┌──────────────▼───────────────┐ - │ Bound Token (mtls_pop) │ - │ ├─ access_token │ - │ ├─ cnf.x5t#S256 │ - │ └─ token_type = mtls_pop │ - └──────────────┬───────────────┘ - │ - ┌──────────────▼───────────────┐ - │ Resource Call (mTLS) │ - │ Cert + token in header │ - └──────────────────────────────┘ + +### End-to-End Sequence + +```mermaid +%%{init: { + "theme": "base", + "themeVariables": { + "fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial", + "primaryTextColor": "#0b1020", + "lineColor": "#44506a" + } +}}%% +sequenceDiagram + participant App as App/Client + participant KG as KeyGuard/NCrypt + participant MAA as Attestation (optional) + participant IMDS as Azure IMDS v2 + participant STS as Entra STS (ESTS) + participant API as Resource API + + rect rgb(227,242,253) + App->>KG: Create non-exportable RSA key + App->>App: Generate PKCS#10 CSR (DER) + end + + rect rgb(255,243,224) + opt Attestation enabled + App->>MAA: Collect attestation evidence + MAA-->>App: Attestation token + end + end + + rect rgb(243,229,245) + App->>IMDS: GET /getplatformmetadata + IMDS-->>App: Platform metadata + App->>IMDS: POST /issuecredential (CSR [+ attestation]) + IMDS-->>App: Client certificate + STS URL + end + + rect rgb(224,247,250) + App->>STS: mTLS POST /token (client_credentials, token_type=mtls_pop) + STS-->>App: access_token (mtls_pop) + cnf.x5t#S256 + end + + rect rgb(255,235,238) + App->>App: Verify cnf.x5t#S256 matches cert SHA-256 thumbprint + end + + rect rgb(232,245,233) + App->>API: Call API with token + mTLS certificate + API-->>App: API response + end ``` +--- -### Security Properties +## Security Properties | Property | Implementation | Benefit | |----------|----------------|---------| -| **Key Protection** | VBS KeyGuard isolation | Keys never leave secure enclave | -| **Certificate Binding** | SHA256 thumbprint in token claims | Prevents token theft | -| **Attestation** | Azure MAA (optional) | Validates platform integrity | -| **Token Type** | `mtls_pop` (strict validation) | Enforces Proof of Possession | -| **No Fallback** | MsiV2Error on failure | Prevents downgrade attacks | -| **Certificate Verification** | cnf.x5t#S256 matching | Validates cert binding | +| Key protection | VBS KeyGuard isolation | Keys never leave secure enclave | +| Certificate binding | SHA256 thumbprint in token claims | Prevents token theft + replay | +| Attestation (optional) | Azure MAA integration | Validates platform integrity | +| Token type enforcement | Strict `mtls_pop` validation | Enforces PoP semantics | +| No fallback | Fail fast via `MsiV2Error` | Prevents downgrade attacks | +| Binding verification | `cnf.x5t#S256` matching | Proves token bound to cert | --- @@ -304,138 +332,89 @@ Environment: MSALMSIV2 pool (Windows 2022 VM) | Aspect | PowerShell | Python | |--------|-----------|--------| -| **Location** | Standalone script | PyPI package | -| **Installation** | Copy `get-token.ps1` | `pip install msal-msiv2` | -| **Key Creation** | NCrypt (native) | NCrypt (ctypes) | -| **CSR Generation** | .NET API | ctypes + DER encoding | -| **Attestation** | AttestationClientLib.dll | ctypes binding | -| **IMDS Calls** | WinHTTP | WinHTTP (ctypes) | -| **mTLS Token** | SChannel | SChannel (WinHTTP) | -| **Logging** | Write-Host | Python logging | -| **Error Handling** | Exception + exit code | MsiV2Error exception | -| **Testing** | Manual/documented | Unit tests + E2E | -| **Integration** | Standalone | MSAL library | -| **Distribution** | GitHub | PyPI (official) | +| Location | Standalone script | PyPI package | +| Installation | Copy `get-token.ps1` | `pip install msal-msiv2` | +| Key creation | NCrypt (native) | NCrypt (ctypes) | +| CSR generation | .NET API | ctypes + DER encoding | +| Attestation | AttestationClientLib.dll | ctypes binding | +| IMDS calls | WinHTTP | WinHTTP (ctypes) | +| mTLS token | SChannel | SChannel (WinHTTP) | +| Logging | Write-Host | Python logging | +| Error handling | Exception + exit code | `MsiV2Error` exception | +| Testing | Manual/documented | Unit tests + E2E | +| Integration | Standalone | MSAL library | +| Distribution | GitHub | PyPI (official) | --- ## Impact & Results -### Code Generated by Copilot -- **2,250 lines** of production-ready Python code -- **8 files** covering implementation, tests, and samples -- **100% integration** with MSAL Python library -- **Zero corrections needed** for core logic -- **321 lines** of comprehensive unit tests -- **Merged to dev branch** and published to PyPI - -### PyPI Publication -``` -📦 Package Name: msal-msiv2 -🔗 PyPI URL: https://pypi.org/project/msal-msiv2/1.35.0rc3/ -📥 Installation: pip install msal-msiv2==1.35.0rc2 -✅ Status: Release Candidate -🌍 Availability: Public (worldwide access) -``` - -### Azure Pipeline Integration -- **Automated E2E Testing** on every build -- **Real Azure VM Validation** (MSALMSIV2 pool) -- **PyPI Package Testing** (ensures distribution works) -- **44-second execution** for full Python test -- **100% pass rate** across all test runs - -### Enterprise Impact -✅ Multi-language support (PowerShell + Python) -✅ Production-ready with security validation -✅ Publicly available on PyPI -✅ Comprehensive documentation -✅ Official MSAL library integration -✅ Continuous CI/CD validation - ---- - -## Hackathon Takeaways - -### What We Learned About Copilot - -1. **Excels at Cross-Language Translation** - - Successfully translated PowerShell logic to Python - - Understood domain-specific concepts (MSI, IMDS, mTLS) - -2. **Handles Complex APIs** - - Generated correct ctypes bindings to Windows APIs - - Proper DER encoding for cryptographic structures - - Accurate IMDS protocol implementation - -3. **Security-Focused Code Generation** - - Enforced strict validation (no fallbacks) - - Implemented certificate binding correctly - - Created comprehensive edge case tests - -4. **Production-Ready Output** - - Code integrates seamlessly with existing libraries - - Passes all unit and E2E tests - - Published to PyPI without modifications - -### Recommendations for Teams - -✅ Use Copilot for complex multi-language projects -✅ Provide clear context from existing implementations -✅ Specify security requirements explicitly -✅ Ask for comprehensive unit tests with mocking -✅ Plan for distribution (PyPI, NuGet, etc.) early -✅ Validate with actual E2E tests in target environment +- **~2,250 lines** of production-ready Python code generated across **8 files** +- Integrated into MSAL Python codebase (PR #882) +- Published on PyPI as **`msal-msiv2==1.35.0rc3`** +- Unit tests + E2E tests in Azure Pipelines (real IMDSv2 environment) +- Demonstrates multi-language parity with consistent security validation --- -## Files & References - -### PowerShell Implementation -📁 https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/tree/main/prototype/MsiV2UsingPowerShell -- `get-token.ps1` - Main implementation -- `readme.md` - Full documentation - -### Python Implementation - On PyPI! 🎉 -🔗 **PyPI:** https://pypi.org/project/msal-msiv2/1.35.0rc2/ -🔗 **GitHub PR #882:** https://github.com/AzureAD/microsoft-authentication-library-for-python/pull/882 -- 2,250 lines added across 8 files -- Status: ✅ Merged and Published -- Contributors: @gladjohn, @Copilot - -### Azure Pipeline Integration -🔗 **Repo:** https://github.com/AzureAD/microsoft-authentication-library-for-dotnet -- `build/template-run-mi-e2e-imdsv2-python.yaml` -- `build/template-build-and-run-all-tests.yaml` - -### E2E Test Results -🔗 **Pipeline Run:** https://identitydivision.visualstudio.com/IDDP/_build/results?buildId=1597011&view=results -- Build ID: 1597011 -- Status: ✅ All jobs passed (13m 55s total) -- MSI v2 Python Job: 44s execution - ---- - -## Conclusion - -This hackathon successfully demonstrated **GitHub Copilot's ability to generate production-ready code across multiple programming languages** for enterprise cloud scenarios. - -Starting with a PowerShell reference implementation, Copilot generated a complete, secure Python implementation of Managed Identity v2 with certificate binding validation. The code is now **published on PyPI** as `msal-msiv2==1.35.0rc2`, making it available for use in production environments worldwide. - -**Azure Pipeline integration** ensures continuous validation on real infrastructure, guaranteeing reliability and security. This represents a significant step forward in multi-language cloud development powered by AI-assisted code generation. +## Hackathon Learnings (Expanded) + +### 1) MSI v2 is “certificate issuance + PoP exchange”, not “token fetch” +- MSI v2 shifts the workflow from **IMDS → token** to **key → CSR → cert → mTLS → PoP token**. +- This changes what “correctness” means: you must validate **certificate binding** (the PoP property), not just successful token retrieval. + +### 2) Security depends on small engineering choices +- **Strict failure behavior** (no silent fallback to MSI v1) is a security feature: it prevents downgrade-by-accident. +- **PoP semantics must be enforced explicitly**: + - Validate `token_type == "mtls_pop"` + - Validate `cnf.x5t#S256` matches the certificate SHA-256 thumbprint + - Ensure resource calls are actually done with **mTLS + the same certificate** + +### 3) Cross-language parity is about invariants, not syntax +- The biggest risk in translation isn’t syntax errors; it’s losing **security invariants**: + - binding verification + - token_type enforcement + - no fallback behavior + - consistent error handling and logging signals + +### 4) Copilot works best when the reference implementation acts as an executable spec +What worked well: +- Using the PowerShell implementation as a **ground-truth flow** +- Writing requirements as **non-negotiable constraints** (e.g., “no fallback”, “must verify cnf”) +- Asking for tests while generating code (not as a last step) + +Where human review mattered most: +- Win32 API boundary correctness (`ctypes` signatures, lifetime/memory rules) +- Security assertions (ensuring validations are not weakened during refactors) + +### 5) Testing strategy: separate deterministic checks from real-world integration +- **Unit tests** validated deterministic security logic (thumbprints, claim comparisons, gating). +- **E2E tests** validated the environment reality (IMDS responses, certificate issuance, mTLS negotiation). +- Together, they prevented the common failure mode: “works in mocks but breaks on real IMDSv2.” + +### 6) CI/CD is part of the feature for identity systems +- MSI v2 depends on specific runtime conditions (IMDSv2, KeyGuard behaviors, network access to STS). +- Automating E2E validation turns identity flows into something **repeatable, reviewable, and regression-safe**. + +### 7) Packaging + samples are what make hackathon output usable +- Publishing a package + shipping minimal and full samples reduced adoption friction. +- This made it possible to validate the entire user journey: **install → run → verify PoP → call resource**. + +### 8) Recommended next steps +- Promote RC → stable with a clear support matrix (OS / MI type / attestation support) +- Expand negative-path testing (binding mismatch, attestation unavailable, IMDS throttling) +- Add a short security checklist for downstream adopters (enforce `mtls_pop`, verify `cnf`, avoid fallback) --- ## Quick Start Guide -### For Developers - -**Install Package:** +### Install ```bash -pip install msal-msiv2==1.35.0rc2 +pip install msal-msiv2==1.35.0rc3 ``` -**Use in Code:** +### Use in Code ```python import msal @@ -455,17 +434,25 @@ print(f"Thumbprint: {result['cert_thumbprint_sha256']}") ``` ### Requirements -- Windows 2022+ with Credential Guard enabled -- Azure Managed Identity assigned to VM -- Network access to IMDS (169.254.169.254) -- Network access to ESTS token endpoint +- Windows Server 2022+ with Credential Guard enabled +- Azure Managed Identity assigned to the VM +- Network access to IMDS (`169.254.169.254`) +- Network access to Entra STS token endpoint + +--- + +## Files & References +- PowerShell: https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/tree/main/prototype/MsiV2UsingPowerShell +- Python PR: https://github.com/AzureAD/microsoft-authentication-library-for-python/pull/882 +- PyPI: https://pypi.org/project/msal-msiv2/1.35.0rc3/ +- Pipeline run: https://identitydivision.visualstudio.com/IDDP/_build/results?buildId=1597011&view=results --- -**Hackathon Team:** -- @gladjohn - Requirement Definition, PowerShell Implementation -- @Copilot @gladjohn - Python Code Generation using PyhtonNet - Phase 1, Removed PythonNet dependency, Testing, Publishing +## Hackathon Team +- @gladjohn — Requirement definition, PowerShell implementation +- @Copilot + @gladjohn — Python code generation (Phase 1), removal of PythonNet dependency, testing, publishing -**Date:** February 25, 2026 -**Status:** ✅ COMPLETE & PUBLISHED -**Package:** msal-msiv2==1.35.0rc3 +**Date:** February 25, 2026 +**Status:** ✅ COMPLETE & PUBLISHED +**Package:** `msal-msiv2==1.35.0rc3`