maui-auth-secure-storage

MAUI Auth and Secure Storage

Use this skill when a MAUI app needs sign-in, token handling, secure local secrets, or auth state shared between native pages and Blazor Hybrid UI.

Workflow

1. Inspect target frameworks, package references, MauiProgram.cs, platform manifests/plists, and existing auth abstractions.
2. Choose the auth primitive:
   • Use WebAuthenticator for provider-neutral OAuth/OIDC browser redirects.
   • Use MSAL.NET for Microsoft Entra ID, account selection, silent token acquisition, and broker integration.
3. Register redirect URIs in both the identity provider and platform app configuration. The scheme/host must match exactly.
4. Keep auth behind an injected service such as IAuthService; do not put token acquisition logic directly in pages or ViewModels.
5. Let MSAL own its token cache when using MSAL. Use SecureStorage for app-owned secrets, small encrypted values, and non-MSAL providers only when the provider requires app-managed refresh token storage.
6. Handle cancellation, denied consent, and expired sessions as first-class UI states instead of treating all auth failures as crashes.
7. For Blazor Hybrid, hand native auth state into scoped services or an AuthenticationStateProvider; do not rely on browser cookies or local storage as the source of truth.

WebAuthenticator Pattern

var result = await WebAuthenticator.Default.AuthenticateAsync(
    new WebAuthenticatorOptions
    {
        Url = authorizeUri,
        CallbackUrl = new Uri("myapp://auth")
    });

if (result.Properties.TryGetValue("error", out var error))
{
    throw new InvalidOperationException($"Authentication failed: {error}");
}

result.Properties.TryGetValue("code", out var code);

Build the authorize URI with PKCE when the provider supports it. Exchange the authorization code through a secure backend or a provider-supported public client flow; do not embed client secrets in the app package.

MSAL.NET Pattern