Merge branch 'main' into ping-identity-home-account-refresh

Author: yowl

.github/copilot-instructions.md

@@ -1,3 +1,67 @@
+# Code Review Rules
+
+These rules apply to Copilot code review. Read all rules before commenting.
+
+## Review scope
+
+- Only comment on lines added or modified in the PR diff
+- Do not comment on pre-existing code unless the PR directly introduces the issue
+- Do not comment on style, formatting, or indentation
+- Focus exclusively on: bugs, security issues, logic errors, API contract violations
+- If unsure whether something is a bug, do not comment
+- Prefer no comment over a speculative comment
+- Do not re-post a comment already made on an earlier commit in the same PR
+
+## Repo-specific patterns — do NOT flag these
+
+These patterns are correct in this repo. Do not suggest changes:
+
+- `[RunOn]` inherits from `TestMethodAttribute`. Do not flag as missing `[TestMethod]`
+- `Client.AppConfig.X` resolves via parent namespace `Microsoft.Identity`. Do not flag as unresolved namespace
+- `Assert.IsTrue(bool?)` is a valid MSTest overload. Do not flag nullable bool as a type mismatch
+- `Assert.DoesNotContain(substring, value)` — MSTest v4 signature is substring first, value second
+- `ConfigureAwait(false)` is intentional in library code. Do not suggest removal
+
+## ConcurrentDictionary.GetOrAdd — always use factory delegate
+
+`GetOrAdd(key, value)` eagerly evaluates the value arg. Flag any call where the second argument is not a delegate/lambda/method group:
+
+- Bad: `pool.GetOrAdd(key, new ExpensiveObject());`
+- Good: `pool.GetOrAdd(key, _ => new ExpensiveObject());`
+
+## C# coding standards
+
+- Use `is null` / `is not null` instead of `== null` / `!= null`
+- No reflection in product code (`/src`). Acceptable in tests
+- Static fields: `s_camelCase` (e.g., `s_knownHosts`)
+- Ordinal string comparisons for protocol values, identifiers, cache keys
+- Validate inputs at method boundaries (fail fast with specific exception types)
+- Do not include secrets/tokens/PII in exception messages or logs
+- Use `nameof` instead of string literals for member names
+
+## Testing standards
+
+- MSTest SDK v4 with NSubstitute for mocking
+- Use `// Arrange`, `// Act`, `// Assert` comments
+- Prefer deterministic tests (no timing flakiness)
+
+## Public API changes
+
+- Update `PublicAPI.Unshipped.txt` for any public API additions/removals
+- XML doc comments required on all public APIs
+- Maintain backward compatibility
+
+## MSAL-specific rules
+
+- Use certificate-based auth over client secrets when possible
+- Use async APIs consistently
+- Keep dependencies minimal and well-justified
+
+---
+
+<!-- Everything below this line is for Copilot Chat and Copilot Agent only. -->
+<!-- Copilot code review reads only the first 4,000 characters of this file. -->
+
 Carefully review all markdown documents in the ../.clinerules folder. Those are your custom instructions.
 
 ---
@@ -45,18 +109,24 @@ Copilot will automatically reference and describe:
 - `@msal-mtls-pop-guidance` - Foundational concepts
 - `@msal-mtls-pop-vanilla` - Direct token acquisition
 - `@msal-mtls-pop-fic-two-leg` - Token exchange patterns
+- `@msal-auth-code-flow` - Authorization Code Flow
+- `@msal-client-credentials` - Client Credentials Flow
+- `@msal-obo-flow` - On-Behalf-Of Flow
 
 ---
 
 ## 📚 Available Skills Overview
 
-This repository contains **three GitHub Agent Skills** for mTLS Proof-of-Possession (PoP) authentication:
+This repository contains **six GitHub Agent Skills** for MSAL.NET authentication:
 
 | Skill | Purpose | Best For |
 |-------|---------|----------|
 | **@msal-mtls-pop-guidance** | Foundational concepts, terminology, decision frameworks | Learning the fundamentals, comparing approaches |
 | **@msal-mtls-pop-vanilla** | Direct single-step token acquisition with complete code | Quick implementation with MSI or Confidential Client |
 | **@msal-mtls-pop-fic-two-leg** | Two-step token exchange patterns | Complex scenarios requiring token exchange |
+| **@msal-auth-code-flow** | Authorization Code Flow for web apps | User sign-in with server-side backend |
+| **@msal-client-credentials** | Client Credentials Flow for daemons | Service-to-service, no user context |
+| **@msal-obo-flow** | On-Behalf-Of Flow for multi-tier APIs | Propagating user identity through API chain |
 
 ---
 

.github/instructions/src.instructions.md

@@ -0,0 +1,37 @@
+# Source code review rules
+
+Applies to: src/**/*.cs
+
+These rules apply when reviewing production source code in this repository.
+
+## Namespace resolution — do NOT flag
+
+- `Client.AppConfig.X`, `Client.Internal.X`, and similar short namespace references resolve via parent namespace `Microsoft.Identity`. Do not flag as unresolved.
+
+## ConcurrentDictionary.GetOrAdd
+
+`GetOrAdd(key, value)` eagerly evaluates the value argument. Flag any call where the second argument is not a delegate/lambda/method group:
+
+- Bad: `pool.GetOrAdd(key, new ExpensiveObject());`
+- Good: `pool.GetOrAdd(key, _ => new ExpensiveObject());`
+
+## `ConfigureAwait(false)`
+
+`ConfigureAwait(false)` is intentional in library code. Do not suggest removal.
+
+## Public API changes
+
+- Any public API additions or removals must be reflected in `PublicAPI.Unshipped.txt`
+- XML doc comments are required on all public APIs
+- Maintain backward compatibility — breaking changes require explicit justification
+
+## MSAL-specific
+
+- Keep dependencies minimal and well-justified
+
+## Scope
+
+- Only comment on source code added or modified in the PR diff
+- Do not comment on pre-existing code unless the PR directly introduces the issue
+- Do not comment on style or formatting — coding standards are enforced via .editorconfig
+- Focus on: bugs, security issues, logic errors, API contract violations

.github/instructions/tests.instructions.md

@@ -0,0 +1,25 @@
+# Test file review rules
+
+Applies to: tests/**/*.cs
+
+These rules apply when reviewing test files in this repository.
+
+## Test framework patterns — do NOT flag
+
+- `[RunOn]` inherits from `TestMethodAttribute` (see `tests/Microsoft.Identity.Test.Integration.netcore/Infrastructure/TargetFramework.cs` line 15). Tests decorated with `[RunOn]` WILL be discovered by MSTest. Do not flag as missing `[TestMethod]`.
+- `Assert.IsTrue(bool?)` is a valid MSTest overload. Do not flag nullable bool arguments as type mismatches.
+- `Assert.DoesNotContain(substring, value)` — in MSTest v4, the first argument is the substring and the second is the value to search. Do not suggest swapping arguments.
+- `Assert.HasCount(expected, collection)` — valid MSTest v4 assertion. Do not suggest `Assert.AreEqual` for count checks.
+
+## Test conventions
+
+- Use MSTest SDK v4 with NSubstitute for mocking
+- Use `// Arrange`, `// Act`, `// Assert` comments
+- Prefer deterministic tests: avoid `Thread.Sleep`, timing dependencies, or environment-specific behavior
+- Copy existing style in nearby files for test method names
+
+## Scope
+
+- Only comment on test code that is added or modified in the PR diff
+- Do not comment on pre-existing test patterns or style
+- Do not re-post comments already made on earlier commits

.github/skills/README.md

@@ -13,15 +13,15 @@ GitHub Copilot Agent Skills are specialized knowledge modules that help Copilot
 
 ## Available Skills
 
-### 1. Confidential Client Authentication (`msal-confidential-auth/`)
+### 1. Confidential Client Authentication
 
-A comprehensive skill set for confidential client authentication patterns in MSAL.NET, covering three core flows with granularized, reusable credential setup patterns.
+Three individual skills for confidential client authentication patterns in MSAL.NET, with reusable credential setup patterns in `msal-shared/`.
 
 #### Authentication Flows
 
-- **[Authorization Code Flow](msal-confidential-auth/auth-code-flow/SKILL.md)** - Web applications with user sign-in
-- **[On-Behalf-Of (OBO) Flow](msal-confidential-auth/obo-flow/SKILL.md)** - Multi-tier services acting on behalf of users  
-- **[Client Credentials Flow](msal-confidential-auth/client-credentials/SKILL.md)** - Service-to-service daemon applications
+- **[Authorization Code Flow](msal-auth-code-flow/SKILL.md)** - Web applications with user sign-in
+- **[On-Behalf-Of (OBO) Flow](msal-obo-flow/SKILL.md)** - Multi-tier services acting on behalf of users  
+- **[Client Credentials Flow](msal-client-credentials/SKILL.md)** - Service-to-service daemon applications
 
 #### Shared Resources (DRY Principle)
 
@@ -141,9 +141,9 @@ Specialized skills for mTLS PoP authentication with Managed Identity and Confide
 
 | Scenario | Skill to Use |
 |----------|--------------|
-| Web app with user sign-in | [Authorization Code Flow](msal-confidential-auth/auth-code-flow/SKILL.md) |
-| API acting on behalf of user | [On-Behalf-Of Flow](msal-confidential-auth/obo-flow/SKILL.md) |
-| Daemon/background service | [Client Credentials Flow](msal-confidential-auth/client-credentials/SKILL.md) |
+| Web app with user sign-in | [Authorization Code Flow](msal-auth-code-flow/SKILL.md) |
+| API acting on behalf of user | [On-Behalf-Of Flow](msal-obo-flow/SKILL.md) |
+| Daemon/background service | [Client Credentials Flow](msal-client-credentials/SKILL.md) |
 | Direct mTLS PoP token (MSI/SNI) | [Vanilla mTLS PoP](msal-mtls-pop-vanilla/SKILL.md) |
 | FIC token exchange with mTLS PoP | [FIC Two-Leg mTLS PoP](msal-mtls-pop-fic-two-leg/SKILL.md) |
 
@@ -235,11 +235,12 @@ skill-name/
 │   ├── code-examples/            # Copy-paste code snippets
 │   ├── credential-setup/         # Setup guides by credential type
 │   └── patterns/                 # Common patterns, troubleshooting
-├── skill-set-name/
-│   ├── flow1/
-│   │   └── SKILL.md              # Flow-specific documentation
-│   └── flow2/
-│       └── SKILL.md
+├── msal-auth-code-flow/
+│   └── SKILL.md                  # Auth Code Flow skill
+├── msal-client-credentials/
+│   └── SKILL.md                  # Client Credentials Flow skill
+├── msal-obo-flow/
+│   └── SKILL.md                  # OBO Flow skill
 └── individual-skill-name/
     ├── SKILL.md                  # Main documentation with YAML frontmatter
     └── HelperClass.cs            # Optional production helper class

…onfidential-auth/auth-code-flow/SKILL.md …thub/skills/msal-auth-code-flow/SKILL.md.github/skills/msal-confidential-auth/auth-code-flow/SKILL.md renamed to .github/skills/msal-auth-code-flow/SKILL.md .github/skills/msal-confidential-auth/auth-code-flow/SKILL.md renamed to .github/skills/msal-auth-code-flow/SKILL.md

@@ -1,3 +1,17 @@
+---
+name: msal-auth-code-flow
+description: Authorization Code Flow for web applications using MSAL.NET confidential client to sign in users and access APIs on their behalf
+tags:
+  - msal
+  - auth-code
+  - authorization-code
+  - web-app
+  - confidential-client
+  - user-sign-in
+  - redirect
+  - consent
+---
+
 # Authorization Code Flow Skill
 
 ## Overview
@@ -20,15 +34,15 @@ Authorization Code Flow is used by web applications to authenticate users and ob
 
 ### Generate Code Snippet
 Agent can show code snippets for each credential type:
-- Standard Certificate: [with-certificate.cs](../../msal-shared/code-examples/with-certificate.cs)
-- Certificate with SNI: [with-certificate-sni.cs](../../msal-shared/code-examples/with-certificate-sni.cs)
-- Federated Identity Credentials: [with-federated-identity-credentials.cs](../../msal-shared/code-examples/with-federated-identity-credentials.cs)
+- Standard Certificate: [with-certificate.cs](../msal-shared/code-examples/with-certificate.cs)
+- Certificate with SNI: [with-certificate-sni.cs](../msal-shared/code-examples/with-certificate-sni.cs)
+- Federated Identity Credentials: [with-federated-identity-credentials.cs](../msal-shared/code-examples/with-federated-identity-credentials.cs)
 
 ### Setup Guidance
 Reference appropriate credential setup:
-- [Certificate Setup](../../msal-shared/credential-setup/certificate-setup.md)
-- [Certificate with SNI](../../msal-shared/credential-setup/certificate-sni-setup.md)
-- [Federated Identity Credentials](../../msal-shared/credential-setup/federated-identity-credentials.md)
+- [Certificate Setup](../msal-shared/credential-setup/certificate-setup.md)
+- [Certificate with SNI](../msal-shared/credential-setup/certificate-sni-setup.md)
+- [Federated Identity Credentials](../msal-shared/credential-setup/federated-identity-credentials.md)
 
 ### Example: Web Application with Certificate
 ```csharp
@@ -54,11 +68,11 @@ public async Task HandleCallback(string code, string state)
 ```
 
 ### Error Resolution
-Refer to [Troubleshooting Guide](../../msal-shared/patterns/troubleshooting.md)
+Refer to [Troubleshooting Guide](../msal-shared/patterns/troubleshooting.md)
 
 ### Best Practices
-- Use [Token Caching Strategies](../../msal-shared/patterns/token-caching-strategies.md) for optimal token acquisition
-- Implement [Error Handling Patterns](../../msal-shared/patterns/error-handling-patterns.md)
+- Use [Token Caching Strategies](../msal-shared/patterns/token-caching-strategies.md) for optimal token acquisition
+- Implement [Error Handling Patterns](../msal-shared/patterns/error-handling-patterns.md)
 - Store refresh tokens securely
 - Use PKCE for native clients
 - For advanced caching options including distributed caches for multi-instance deployments, see [Token cache serialization documentation](https://learn.microsoft.com/en-us/entra/msal/dotnet/how-to/token-cache-serialization?tabs=msal)

…dential-auth/client-credentials/SKILL.md …/skills/msal-client-credentials/SKILL.md.github/skills/msal-confidential-auth/client-credentials/SKILL.md renamed to .github/skills/msal-client-credentials/SKILL.md .github/skills/msal-confidential-auth/client-credentials/SKILL.md renamed to .github/skills/msal-client-credentials/SKILL.md

@@ -1,3 +1,16 @@
+---
+name: msal-client-credentials
+description: Client Credentials Flow for service-to-service (daemon) authentication in MSAL.NET without user involvement
+tags:
+  - msal
+  - client-credentials
+  - daemon
+  - service-to-service
+  - confidential-client
+  - background-service
+  - machine-to-machine
+---
+
 # Client Credentials Flow Skill
 
 ## Overview
@@ -20,15 +33,15 @@ Client Credentials Flow is used for service-to-service authentication without us
 
 ### Generate Code Snippet
 Agent can show code for each credential type:
-- Standard Certificate: [with-certificate.cs](../../msal-shared/code-examples/with-certificate.cs)
-- Certificate with SNI: [with-certificate-sni.cs](../../msal-shared/code-examples/with-certificate-sni.cs)
-- Federated Identity Credentials: [with-federated-identity-credentials.cs](../../msal-shared/code-examples/with-federated-identity-credentials.cs)
+- Standard Certificate: [with-certificate.cs](../msal-shared/code-examples/with-certificate.cs)
+- Certificate with SNI: [with-certificate-sni.cs](../msal-shared/code-examples/with-certificate-sni.cs)
+- Federated Identity Credentials: [with-federated-identity-credentials.cs](../msal-shared/code-examples/with-federated-identity-credentials.cs)
 
 ### Setup Guidance
 Reference appropriate credential setup:
-- [Certificate Setup](../../msal-shared/credential-setup/certificate-setup.md)
-- [Certificate with SNI](../../msal-shared/credential-setup/certificate-sni-setup.md)
-- [Federated Identity Credentials](../../msal-shared/credential-setup/federated-identity-credentials.md)
+- [Certificate Setup](../msal-shared/credential-setup/certificate-setup.md)
+- [Certificate with SNI](../msal-shared/credential-setup/certificate-sni-setup.md)
+- [Federated Identity Credentials](../msal-shared/credential-setup/federated-identity-credentials.md)
 
 ### Example: Service with Certificate
 ```csharp
@@ -60,11 +73,11 @@ public class TokenAcquisitionService
 ```
 
 ### Error Resolution
-Refer to [Troubleshooting Guide](../../msal-shared/patterns/troubleshooting.md)
+Refer to [Troubleshooting Guide](../msal-shared/patterns/troubleshooting.md)
 
 ### Best Practices
-- Use [Token Caching Strategies](../../msal-shared/patterns/token-caching-strategies.md) - enable static token caching with `.WithCacheOptions(CacheOptions.EnableSharedCacheOptions)` for optimal performance
-- Implement [Error Handling Patterns](../../msal-shared/patterns/error-handling-patterns.md) 
+- Use [Token Caching Strategies](../msal-shared/patterns/token-caching-strategies.md) - enable static token caching with `.WithCacheOptions(CacheOptions.EnableSharedCacheOptions)` for optimal performance
+- Implement [Error Handling Patterns](../msal-shared/patterns/error-handling-patterns.md) 
 - Monitor token acquisition using `AuthenticationResultMetadata` for cache hit ratios
 - Rotate certificates periodically (if using certificate-based auth)
 - Use Federated Identity Credentials with Managed Identity for keyless authentication

…msal-confidential-auth/obo-flow/SKILL.md .github/skills/msal-obo-flow/SKILL.md.github/skills/msal-confidential-auth/obo-flow/SKILL.md renamed to .github/skills/msal-obo-flow/SKILL.md .github/skills/msal-confidential-auth/obo-flow/SKILL.md renamed to .github/skills/msal-obo-flow/SKILL.md

@@ -1,3 +1,17 @@
+---
+name: msal-obo-flow
+description: On-Behalf-Of (OBO) Flow for web APIs to call downstream APIs while preserving user identity in MSAL.NET
+tags:
+  - msal
+  - obo
+  - on-behalf-of
+  - token-exchange
+  - confidential-client
+  - multi-tier
+  - downstream-api
+  - user-assertion
+---
+
 # On-Behalf-Of (OBO) Flow Skill
 
 ## Overview
@@ -23,15 +37,15 @@ ID tokens are for authentication; access tokens are for authorization and API ac
 
 ### Generate Code Snippet
 Agent can show code for each credential type:
-- Standard Certificate: [with-certificate.cs](../../msal-shared/code-examples/with-certificate.cs)
-- Certificate with SNI: [with-certificate-sni.cs](../../msal-shared/code-examples/with-certificate-sni.cs)
-- Federated Identity Credentials: [with-federated-identity-credentials.cs](../../msal-shared/code-examples/with-federated-identity-credentials.cs)
+- Standard Certificate: [with-certificate.cs](../msal-shared/code-examples/with-certificate.cs)
+- Certificate with SNI: [with-certificate-sni.cs](../msal-shared/code-examples/with-certificate-sni.cs)
+- Federated Identity Credentials: [with-federated-identity-credentials.cs](../msal-shared/code-examples/with-federated-identity-credentials.cs)
 
 ### Setup Guidance
 Reference appropriate credential setup:
-- [Certificate Setup](../../msal-shared/credential-setup/certificate-setup.md)
-- [Certificate with SNI](../../msal-shared/credential-setup/certificate-sni-setup.md)
-- [Federated Identity Credentials](../../msal-shared/credential-setup/federated-identity-credentials.md)
+- [Certificate Setup](../msal-shared/credential-setup/certificate-setup.md)
+- [Certificate with SNI](../msal-shared/credential-setup/certificate-sni-setup.md)
+- [Federated Identity Credentials](../msal-shared/credential-setup/federated-identity-credentials.md)
 
 ### Example: Web API with Certificate
 ```csharp
@@ -64,15 +78,15 @@ public async Task<IActionResult> GetData()
 ```
 
 ### Error Resolution
-Refer to [Troubleshooting Guide](../../msal-shared/patterns/troubleshooting.md)
+Refer to [Troubleshooting Guide](../msal-shared/patterns/troubleshooting.md)
 
 **Common OBO errors:**
 - `MsalUiRequiredException`: MFA or conditional access required—requires client re-authentication
 - Invalid token: Verify access token (not ID token) is passed
 
 ### Best Practices
-- Use [Token Caching Strategies](../../msal-shared/patterns/token-caching-strategies.md) for optimal session-based token caching
-- Implement [Error Handling Patterns](../../msal-shared/patterns/error-handling-patterns.md)
+- Use [Token Caching Strategies](../msal-shared/patterns/token-caching-strategies.md) for optimal session-based token caching
+- Implement [Error Handling Patterns](../msal-shared/patterns/error-handling-patterns.md)
 - Always validate incoming token before using in OBO
 - Extract `tid` claim from user token for guest user scenarios—use tenant-specific authority, not /common
 - For multi-instance deployments and advanced caching, see [Token cache serialization documentation](https://learn.microsoft.com/en-us/entra/msal/dotnet/how-to/token-cache-serialization?tabs=msal)