Cline rules

1# MSAL.NET Guidelines
2 
3## Overview
4 
5Microsoft Authentication Library (MSAL) for .NET is a highly scalable authentication library that enables applications to authenticate with the Microsoft identity platform. For confidential client scenarios (server-side applications), the library provides:
6 
7- Token acquisition for service-to-service calls
8- Flexible token caching with distributed cache support
9- Managed identity integration for Azure workloads
10- On-behalf-of flow for service-to-service delegated access
11 
12Through its comprehensive feature set and proven reliability, MSAL.NET simplifies the implementation of secure authentication in server-side applications while maintaining optimal performance and security.
13 
14## Repository Structure
15 
16### Core Directories
17- `/src/client/Microsoft.Identity.Client` - Core MSAL functionality
18  - `ConfidentialClientApplication.cs` - Primary confidential client implementation
19  - `ApiConfig/` - API configuration and builders
20  - `Cache/` - Token cache implementations
21  - `ManagedIdentity/` - Azure managed identity support 
22  - `OAuth2/` - OAuth protocol implementations
23  - `Internal/` - Internal components and utilities
24- `/tests` - Unit tests and integration tests
25- `/benchmark` - Performance benchmarking infrastructure
26- `/tools` - Development and configuration tools
27 
28## Core Components
29 
30### Confidential Client Features
31- Microsoft.Identity.Client - Main MSAL library with confidential client support
32- Token cache implementations with extensible serialization
33- Managed identity integration for Azure environments
34 
35### Authentication Components
36- IConfidentialClientApplication - Primary interface for confidential clients
37- Token cache providers and serialization extensibility
38- Client credential builders and configurations
39- Custom assertion providers (certificates, managed identity)
40 
41## Development Guidelines
42 
43### Core Development Principles
44- Follow .editorconfig rules strictly
45- Maintain backward compatibility due to widespread usage
46- Implement proper error handling and retry logic
47- Keep dependencies minimal and well-justified
48- Document security considerations thoroughly
49- Do not use reflection in source code and tests.
50 
51### Authentication Best Practices
52- Use certificate-based authentication over client secrets when possible
53- Implement token caching for optimal performance
54- Handle token expiration and refresh scenarios
55- Configure appropriate token lifetimes
56- Use managed identities in Azure environments when available
57 
58### Performance Requirements
59- Implement distributed token caching for scale-out scenarios
60- Optimize token acquisition patterns
61- Use asynchronous APIs consistently
62- Configure appropriate retry policies
63- Benchmark token operations in high-throughput scenarios
64 
65### Security Guidelines
66- Secure storage of client secrets and certificates
67- Implement proper token validation
68- Follow least-privilege principle for scopes
69- Handle sensitive data appropriately
70- Implement proper logging (avoiding sensitive data)
71 
72### Testing Requirements
73- Maintain comprehensive test coverage
74- Include integration tests with actual identity endpoints
75- Test token cache implementations thoroughly
76- Verify managed identity scenarios
77- Include performance benchmarks for token operations
78 
79### Public API Changes
80- The project uses Microsoft.CodeAnalysis.PublicApiAnalyzers
81- For any public API changes:
82  1. Update PublicAPI.Unshipped.txt in the package directory
83  2. Include complete API signatures
84  3. Consider backward compatibility impacts
85  4. Document breaking changes clearly
86 
87Example format:
88```diff
89// Adding new API
90+Microsoft.Identity.Client.ConfidentialClientApplication.AcquireTokenForClient() -> Task<AuthenticationResult>
91+Microsoft.Identity.Client.IConfidentialClientApplication.GetAccounts() -> Task<IEnumerable<IAccount>>
92 
93// Removing API (requires careful consideration)
94-Microsoft.Identity.Client.ConfidentialClientApplication.ObsoleteMethod() -> void
95```
96 
97The analyzer enforces documentation of all public API changes in PublicAPI.Unshipped.txt and will fail the build if changes are not properly reflected.
98