maui-auth-secure-storage

name

maui-auth-secure-storage

description

Implement .NET MAUI authentication and secure storage flows with WebAuthenticator, MSAL.NET, platform callback URIs, token caches, brokers, SecureStorage, logout cleanup, and Blazor Hybrid auth handoff. USE FOR: login/logout, OAuth/OIDC redirects, Entra ID, CallbackUrl, WebAuthenticatorCallbackActivity, Android intent filters, CFBundleURLTypes, MSAL redirect URI/BrokerRedirectUri, AcquireTokenSilent, RemoveAsync/GetAccountsAsync token cache cleanup, secure token storage, and native-to-Blazor auth state. DO NOT USE FOR: architecture, API retries/offline behavior, or UI debugging.

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

builder.Services.AddSingleton<IAuthService, MsalAuthService>();

For MSAL:

• Configure redirect URIs in the Entra app registration and the platform app.
• Build the public client with an explicit redirect URI, for example .WithRedirectUri("msal{client-id}://auth") when using the default MAUI MSAL public-client redirect pattern. Broker-capable apps must use the broker redirect URI expected by the platform and app registration, often referred to as the BrokerRedirectUri in MSAL setup guidance.
• Prefer AcquireTokenSilent before interactive auth.
• Use MSAL's platform token cache for MAUI mobile targets and verify persistence on each target platform. Add custom token-cache serialization only for desktop, unsupported, or intentionally custom cache scenarios.
• Use interactive auth only when there is no cached account, consent is needed, or silent acquisition returns a UI-required result.
• Inspect MsalUiRequiredException.Classification, error codes, and claims before blindly retrying interactive auth. Conditional Access, compliant-device, or Intune protection-policy failures may require compliance UX or Intune MAM integration, not another generic prompt.
• Opt into brokers only when the app registration, redirect URI, and platform setup are broker-ready.
• Store account identifiers or display names if needed; do not duplicate MSAL access or refresh tokens into Preferences.
• On logout, call GetAccountsAsync() and RemoveAsync(account) for cached MSAL accounts before clearing app-owned auth state, so the next AcquireTokenSilent cannot return the signed-out user's tokens.

Platform Redirect Checklist

Platform	Check
Android	For WebAuthenticator, add an Android activity subclass that inherits Microsoft.Maui.Authentication.WebAuthenticatorCallbackActivity and has an IntentFilter for the callback scheme/host. Use MAUI namespaces, not Xamarin.Auth or Xamarin.Essentials callback types. For MSAL broker flows, use the broker-compatible redirect URI and signature hash expected by the app registration.
iOS/Mac Catalyst	Add CFBundleURLTypes for the callback scheme. For MSAL broker flows, add LSApplicationQueriesSchemes entries such as msauthv2 and msauthv3 so MSAL can detect the broker, and match the redirect URI scheme configured in the app registration.
Windows	Register the custom protocol in the package manifest or app identity configuration used by the target.

SecureStorage Guardrails

• Use SecureStorage.Default.GetAsync, SetAsync, and Remove for small secrets only.
• Treat missing values as normal after reinstall, backup restore, device lock changes, or secure store reset.
• On Mac Catalyst, configure Keychain Sharing in Platforms/MacCatalyst/Entitlements.plist; secure storage calls fail without the required keychain entitlement.
• On iOS and Mac Catalyst, app extensions cannot read the host app's secure values unless a shared keychain access group is configured in both host and extension entitlements.
• Store expiration metadata with app-owned tokens and refresh before use.
• Prefer a backend token exchange when a provider requires confidential client secrets.
• Never log tokens, authorization codes, id_token values, refresh tokens, or full callback URLs.

Blazor Hybrid Auth Handoff

• Register the native auth/session service in MAUI DI and consume it from Razor components through DI.
• Implement a custom AuthenticationStateProvider when Razor components need [Authorize] or AuthorizeView.
• Attach bearer tokens through a typed HttpClient handler that asks the native auth service for a fresh access token.
• Clear MSAL accounts with RemoveAsync, app-owned SecureStorage values, and Blazor auth state on logout.

Validation Checklist

• Redirect URI values match across provider registration and platform files.
• Auth flows use PKCE or MSAL public-client patterns and contain no client secrets.
• Silent token acquisition is attempted before interactive MSAL prompts.
• Logout clears MSAL cached accounts with RemoveAsync and invalidates Blazor auth state when used.
• Secure values are stored only in SecureStorage or the library-owned cache.
• Blazor Hybrid components receive auth state through DI, not browser-only storage.