.NET MAUI — Authentication Skill

Purpose

This skill provides agents with secure, cross-platform patterns for implementing authentication in .NET MAUI applications. It covers OAuth2, OpenID Connect, JWT handling, secure storage, token refresh, and platform-specific login flows using WebAuthenticator.

The goal is to ensure that all authentication-related code is safe, maintainable, and aligned with modern security practices.

Core Principles

1. Security first
   Never store sensitive data in Preferences or plain text. Always use SecureStorage.
2. Use platform-native authentication flows
   • iOS/macOS: ASWebAuthenticationSession
   • Android: Chrome Custom Tabs
   • Windows: System browser
3. Token lifecycle management
   Always implement refresh token logic and expiration checks.
4. Abstraction
   Wrap authentication logic in services and interfaces to keep UI clean.
5. Least privilege
   Request only the scopes required for the app.

Supported Authentication Patterns

• OAuth2 Authorization Code Flow (recommended)
• OpenID Connect (OIDC)
• JWT-based APIs
• Custom backend authentication
• Social logins (Google, Microsoft, Apple)

Recommended Architecture

Services
└─ Auth
   ├─ Interfaces
   └─ Models

Agent Usage Guidelines

• When generating authentication code, always:
  • Use WebAuthenticator.Default.AuthenticateAsync for login.
  • Store tokens in SecureStorage.
  • Implement IAuthService and AuthService.
  • Provide IsLoggedIn, LoginAsync, LogoutAsync, and RefreshTokenAsync.
• When asked to “add login,” generate:
  • A LoginPage + LoginViewModel
  • AuthService + interface
  • Token models
  • SecureStorage helpers
• When asked to “secure an API call,” apply:
  • Bearer token injection
  • Expiration checks
  • Automatic refresh

Out of Scope

• UI styling (covered in maui-ui-best-practices)
• Backend implementation details
• Deployment configuration