#Microsoft.Identity.Web.CertificatelessEnable confidential client flows in Microsoft Entra ID (Azure AD)**without managing X.509 certificates or static client secrets**.`Microsoft.Identity.Web.Certificateless` adds a pluggable client assertion provider that uses a trusted workload identity (Managed Identity, Azure AD Workload Identity for Kubernetes, etc.) to generate ephemeral JWT client assertions instead of loading a certificate specified in`AzureAd:ClientCredentials`.>Conceptual background:[Certificateless overview](https://aka.ms/ms-id-web/certificateless)---##Table of contents1. Motivation2. How it fits with existing credential configuration3. Configuration building blocks4. Common configuration patterns5. Hybrid (fallback) examples6. Kubernetes / Workload Identity7. Runtime precedence & decision logic8. Migration guidance9. Troubleshooting & diagnostics10. Security considerations11. FAQ12. Appendix: CredentialDescription SourceType quick reference---##1. MotivationTraditional confidential client setups require either secrets (discouraged) or certificates (which you must provision, secure, rotate). In Azure hosting environments you already*have* an identity (Managed Identity or a federated workload identity) whose lifecycle and key rotation are handled by the platform. Certificateless mode leverages that identity to build a valid OAuth2 client assertion (JWT bearer) per token request—no certificate objects, no Key Vault retrieval for signing material, no rotation tasks.---##2. How it fits with existing credential configuration`Microsoft.Identity.Web` normally discovers credentials via`AzureAd:ClientCredentials` (array of`CredentialDescription` objects). Each entry declares a`SourceType` describing where a certificate or pre-signed assertion comes from (KeyVault, StoreWithThumbprint, Path, Base64Encoded, SignedAssertionFilePath, etc.).When`Certificateless:IsEnabled` is`true`, the certificateless assertion provider takes precedence. All`AzureAd:ClientCredentials` entries are ignored for client assertion generation. If`IsEnabled` is`false` (or absent), the existing`ClientCredentials` resolution logic applies unchanged.This lets you keep certificate configuration as a fallback or for local development while enabling certificateless in production.---##3. Configuration building blocks###3.1 Certificateless options (from`CertificatelessOptions`)-`IsEnabled` (bool, default`false`): Activates certificateless mode.-`ManagedIdentityClientId` (string?): Required only for*user-assigned* Managed Identity. Omit for system-assigned.###3.2 Existing credential descriptions (fallback surface)Example (retained for rollback):```jsonc"AzureAd": {"TenantId":"TENANT_ID","ClientId":"APP_CLIENT_ID","ClientCredentials": [    {"SourceType":"KeyVault","KeyVaultUrl":"https://myvault.vault.azure.net/","KeyVaultCertificateName":"my-app-cert"    }  ]}```While certificateless is enabled these entries are not used.---##4. Common configuration patterns###A. Pure certificateless (system-assigned Managed Identity)```jsonc{"AzureAd": {"Instance":"https://login.microsoftonline.com/","TenantId":"YOUR_TENANT_ID","ClientId":"YOUR_APP_REGISTRATION_CLIENT_ID"  },"Certificateless": {"IsEnabled":true }}```###B. User-assigned Managed Identity```jsonc"Certificateless": {"IsEnabled":true,"ManagedIdentityClientId":"USER_ASSIGNED_MI_CLIENT_ID"}```###C. Hybrid with certificate fallback (prod prefers certificateless)`appsettings.json` (shared):```jsonc{"AzureAd": {"TenantId":"TENANT_ID","ClientId":"APP_ID","ClientCredentials": [      {"SourceType":"KeyVault","KeyVaultUrl":"https:...</details>*This pull request was created as a result of the following prompt from Copilot chat.*> Add developer conceptual documentation for the certificateless feature by introducing a new Markdown file: src/Microsoft.Identity.Web.Certificateless/README-certificateless.md.>> Purpose:> Provide a thorough explanation of how to enable and use the certificateless client assertion capability in Microsoft.Identity.Web, how it coexists with existing AzureAd:ClientCredentials (CredentialDescription SourceType entries), migration guidance, troubleshooting, security considerations, and Kubernetes/Workload Identity guidance.>> Acceptance Criteria:> - New file src/Microsoft.Identity.Web.Certificateless/README-certificateless.md added.> - Content includes: motivation, configuration patterns (including IsEnabled flag and ManagedIdentityClientId), precedence vs existing credential descriptions, hybrid fallback examples, Kubernetes workload identity notes, migration steps, troubleshooting table, FAQ, and appendix summarizing CredentialDescription SourceType values ignored when certificateless is enabled.> - Links use HTTPS and friendly link text (e.g., reference to https://aka.ms/ms-id-web/certificateless).> - No code changes beyond adding the documentation file.>> File Content (proposed):>> ````markdown> # Microsoft.Identity.Web.Certificateless>> Enable confidential client flows in Microsoft Entra ID (Azure AD) **without managing X.509 certificates or static client secrets**.> `Microsoft.Identity.Web.Certificateless` adds a pluggable client assertion provider that uses a trusted workload identity (Managed Identity, Azure AD Workload Identity for Kubernetes, etc.) to generate ephemeral JWT client assertions instead of loading a certificate specified in `AzureAd:ClientCredentials`.>> > Conceptual background: [Certificateless overview](https://aka.ms/ms-id-web/certificateless)>> ---> ## Table of contents> 1. Motivation> 2. How it fits with existing credential configuration> 3. Configuration building blocks> 4. Common configuration patterns> 5. Hybrid (fallback) examples> 6. Kubernetes / Workload Identity> 7. Runtime precedence & decision logic> 8. Migration guidance> 9. Troubleshooting & diagnostics> 10. Security considerations> 11. FAQ> 12. Appendix: CredentialDescription SourceType quick reference>> ---> ## 1. Motivation> Traditional confidential client setups require either secrets (discouraged) or certificates (which you must provision, secure, rotate). In Azure hosting environments you already *have* an identity (Managed Identity or a federated workload identity) whose lifecycle and key rotation are handled by the platform. Certificateless mode leverages that identity to build a valid OAuth2 client assertion (JWT bearer) per token request—no certificate objects, no Key Vault retrieval for signing material, no rotation tasks.>> ---> ## 2. How it fits with existing credential configuration> `Microsoft.Identity.Web` normally discovers credentials via `AzureAd:ClientCredentials` (array of `CredentialDescription` objects). Each entry declares a `SourceType` describing where a certificate or pre-signed assertion comes from (KeyVault, StoreWithThumbprint, Path, Base64Encoded, SignedAssertionFilePath, etc.).>> When `Certificateless:IsEnabled` is `true`, the certificateless assertion provider takes precedence. All `AzureAd:ClientCredentials` entries are ignored for client assertion generation. If `IsEnabled` is `false` (or absent), the existing `ClientCredentials` resolution logic applies unchanged.>> This lets you keep certificate configuration as a fallback or for local development while enabling certificateless in production.>> ---> ## 3. Configuration building blocks> ### 3.1 Certificateless options (from `CertificatelessOptions`)> - `IsEnabled` (bool, default `false`): Activates certificateless mode.> - `ManagedIdentityClientId` (string?): Required only for *user-assigned* Managed Identity. Omit for system-assigned.>> ### 3.2 Existing credential descriptions (fallback surface)> Example (retained for rollback):> ```jsonc>"AzureAd": {>"TenantId":"TENANT_ID",>"ClientId":"APP_CLIENT_ID",>"ClientCredentials": [>     {>"SourceType":"KeyVault",>"KeyVaultUrl":"https://myvault.vault.azure.net/",>"KeyVaultCertificateName":"my-app-cert">     }>   ]> }>```> While certificateless is enabled these entries are not used.>> ---> ## 4. Common configuration patterns> ### A. Pure certificateless (system-assigned Managed Identity)>```jsonc> {>"AzureAd": {>"Instance":"https://login.microsoftonline.com/",>"TenantId":"YOUR_TENANT_ID",>"ClientId":"YOUR_APP_REGISTRATION_CLIENT_ID">   },>"Certificateless": {"IsEnabled":true }> }>```> ### B. User-assigned Managed Identity>```jsonc>"Certificateless": {>"IsEnabled":true,>"ManagedIdentityClientId":"USER_ASSIGNED_MI_CLIENT_ID"> }>```> ### C. Hybrid with certificate fallback (prod prefers certificateless)>`appsettings.json` (shared):>```jsonc> {>"AzureAd": {>"TenantId":"TENANT_ID",>"ClientId":"APP_ID",>"ClientCredentials": [>       {"SourceType":"KeyVault","KeyVaultUrl":"https://myvault.vault.azure.net/","KeyVaultCertificateName":"legacy-fallback-cert" }>     ]>   },>"Certificateless": {"IsEnabled":false }> }>```>`appsettings.Production.json`:>```jsonc> {"Certificateless": {"IsEnabled":true } }>```> ### D. Environment variable enablement>```bash>exportCertificateless__IsEnabled=true> # Onlyif user-assignedMI:>exportCertificateless__ManagedIdentityClientId=00000000-0000-0000-0000-000000000000>```> ### E. Fallback to a pre-signed assertion file (rare) kept as DR> Include a`SignedAssertionFilePath` entry but leave`IsEnabled:true` for normal operation.>> ---> ## 5. Hybrid (fallback) examples> Keep your original certificate config. Toggle`IsEnabled` off to revert immediately—no code changes required.>> ---> ## 6. Kubernetes / Azure AD Workload Identity> 1. Configure a federated identity credential on the app registration matching the AKS OIDC issuer + ServiceAccount subject.> 2. Deploy with the annotated ServiceAccount (projected token provided automatically).> 3. Set`Certificateless:IsEnabled:true`.> 4. Provide`ManagedIdentityClientId` only if targeting a separate user-assigned Managed Identity.> Logs (Information/Debug) trace assertion generation; a Kubernetes-specific provider type is used internally.>> ---> ## 7. Runtime precedence & decision logic (simplified)> 1. Read`Certificateless:IsEnabled`.> 2. If`true`: use certificateless provider; ignore`AzureAd:ClientCredentials`.> 3. Else: iterate credential descriptions by order; first resolvable credential wins (existing behavior).>> ---> ## 8. Migration guidance> | Step | Action | Notes |> |------|--------|-------|> | 1 | Enable Managed or Workload Identity | Grant required roles/permissions |> | 2 | Add package reference`Microsoft.Identity.Web.Certificateless` | Keep existing`Microsoft.Identity.Web` |> | 3 | Add`Certificateless` section with`IsEnabled:false` | Safe dark launch |> | 4 | Deploy & verify baseline | Still using certificate |> | 5 | Flip`IsEnabled:true` in target env | Certificateless now active |> | 6 | Monitor logs, token acquisition | Watch for 401/invalid_client |> | 7 | Retire old certificate artifacts (optional) | Keep for DR if desired |>> Rollback = set`IsEnabled:false`.>> ---> ## 9. Troubleshooting & diagnostics> | Symptom | Likely cause | Resolution |> |---------|--------------|-----------|> | 401 invalid_client | MI / federated identity missing | Ensure identity assigned & federated mapping correct |> | 400 AADSTS7000215 |`IsEnabled` false and no valid credential entries | Enable certificateless or supply certificate |> | Timeout contacting IMDS | Running locally without MI | Disable certificateless locally |> | Ambiguous identity | User-assigned MI not specified | Set`ManagedIdentityClientId` |> | Works locally, fails in prod | Prod config not applied or no MI there | Verify deployment slot identity & config |>> Enable console logging:>```csharp>builder.Logging.AddConsole().SetMinimumLevel(LogLevel.Information);>```> Look for messages about assertion acquisition and Managed Identity token retrieval.>> ---> ## 10. Security considerations> - Removes static certificates/private keys from your operational surface.> - Assertions are ephemeral, reducing replay risk.> - Platform handles key rotation (Managed Identity / federated identity).> - Maintain least privilege on assigned roles.>> ---> ## 11. FAQ> **Do I still need`AzureAd:ClientId`?** Yes—the logical application registration still applies.> **Can I keep a certificate fallback?** Yes; leave`ClientCredentials` in place and toggle`IsEnabled`.> **Is this the same as Azure SDK Managed Identity usage?** Similar trust anchor, but here it yields an OAuth2 client assertion for confidential client flows.> **Do I need`ManagedIdentityClientId` for system-assigned MI?** No.> **How do I revert?** Set`IsEnabled:false`.>> ---> ## 12. Appendix: CredentialDescription SourceType quick reference> (Existing values ignored while certificateless is active.)>> | SourceType | Description |> |------------|-------------|> | KeyVault | Certificate retrieved from Azure Key Vault |> | StoreWithThumbprint | Certificate from local cert store by thumbprint |> | StoreWithDistinguishedName | Certificate from local store by DN |> | Path | Certificate file on disk |> | Base64Encoded | Base64 certificate payload (optionally password) |> | Certificate | Already-instantiated certificate (in code) |> | SignedAssertionFilePath | Pre-signed static client assertion from file |> | SignedAssertionFromVault | Pre-signed assertion/secret from Key Vault |>> ---> ## Summary>`Microsoft.Identity.Web.Certificateless` replaces manual certificate management with platform-managed workload identities. Enable it with a single configuration flag while retaining seamless fallback. This reduces operational overhead, improves secret hygiene, and simplifies rotation.>> Happy coding!>````>> Please add only this new file; no other source changes are required.<!-- START COPILOT CODING AGENT TIPS -->---💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click [here](https://survey3.medallia.com/?EAHeSx-AP01bZqG0Ld9QLQ) to start the survey.