Index of every page on this site: llms.txt
All skills
davidortinau avatar

/maui-authentication

@79bb4bf
Run it yourself

Add authentication to .NET MAUI apps. Covers WebAuthenticator for generic OAuth 2.0 / social login, and MSAL.NET for Microsoft Entra ID (Azure AD) with broker support (Microsoft Authenticator), token caching, Conditional Access, platform-specific setup (Android, iOS, Windows), DelegatingHandler for bearer token API calls, and Blazor Hybrid integration. USE FOR: "add authentication", "OAuth login", "MSAL.NET", "social login", "WebAuthenticator", "Entra ID MAUI", "Azure AD login", "Google login MAUI", "Apple login MAUI", "token caching", "bearer token", "sign in". DO NOT USE FOR: secure local storage of tokens (use maui-secure-storage), Aspire-specific auth setup (use maui-aspire), or server-side Entra ID provisioning (use entra-id-aspire-provisioning).

Use this Skill: https://skilld.dev/gh/davidortinau/maui-skills/maui-authentication

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈196 tokens for metadata: the name and description. ≈1.3k when used: this file. ≈4.3k more on demand in 1 file.

Description uses 9.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈783 characters, or 9.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

.NET MAUI Authentication

Security: Never Embed Secrets

❌ Never embed client secrets, API keys, or signing keys in a mobile app binary. They can be extracted trivially via decompilation.

The correct pattern:

  1. App calls WebAuthenticator pointing to your server endpoint
  2. Server initiates the OAuth flow with the identity provider (holds the client secret)
  3. Provider redirects back to your server with an auth code
  4. Server exchanges the code for tokens and returns them to the app via the callback URI

WebAuthenticator Gotchas

⚠️ Windows WebAuthenticator is broken

Windows WebAuthenticator is currently broken. See dotnet/maui#2702. Use MSAL or a WinUI-specific workaround for Windows auth flows.

⚠️ Apple Sign In returns name/email only once

Apple only returns the user's name and email on the first sign-in. Cache them immediately — subsequent sign-ins won't include them.

⚠️ PrefersEphemeralWebBrowserSession

Set to true on iOS 13+ to force a fresh login prompt. When false (default), the auth session shares cookies with Safari — the user may be auto-logged in, which can confuse logout/switch-account flows.

⚠️ Callback URI mismatches

The most common auth failure is a URI scheme mismatch. The CallbackUrl in code must exactly match:

  • Android: DataScheme + DataHost in the IntentFilter
  • iOS: CFBundleURLSchemes in Info.plist
  • Windows: Protocol Name in Package.appxmanifest

WebAuthenticator Checklist

  • Callback URI scheme matches across all platform configs and CallbackUrl
  • Android has WebAuthenticatorCallbackActivity with correct IntentFilter
  • Android 11+ has <queries> for Custom Tabs in the manifest
  • iOS/Mac Catalyst has CFBundleURLTypes in Info.plist
  • Client secrets are on the server, not in the app
  • Tokens stored with SecureStorage, cleared on logout
  • TaskCanceledException handled gracefully in UI

Choosing Between WebAuthenticator and MSAL.NET

Criteria WebAuthenticator MSAL.NET
Identity provider Any OAuth 2.0 / OIDC Microsoft Entra ID
Broker support (SSO) ❌ No ✅ Microsoft Authenticator, Company Portal
Conditional Access / MFA ❌ Manual ✅ Built-in
Token cache & refresh ❌ Manual (SecureStorage) ✅ Automatic
Complexity Simple More setup
Use when Google, Apple, generic OIDC Entra ID / Azure AD, Microsoft Graph

MSAL.NET Gotchas

⚠️ Android: OnActivityResult is required

Forgetting AuthenticationContinuationHelper.SetAuthenticationContinuationEventArgs in MainActivity.OnActivityResult causes auth to hang silently after the browser returns.

⚠️ iOS: Keychain sharing is required

Without Entitlements.plist containing keychain group com.microsoft.adalcache, token caching fails silently and users are prompted to sign in every time.

⚠️ Handle MsalUiRequiredException

When AcquireTokenSilent throws MsalUiRequiredException, the cached token is expired and interaction is needed. Always fall back to AcquireTokenInteractive.

// ❌ Ignoring MsalUiRequiredException — user gets a crash
var result = await _pca.AcquireTokenSilent(scopes, account).ExecuteAsync(ct);

// ✅ Fall back to interactive when silent fails
try
{
    result = await _pca.AcquireTokenSilent(scopes, account).ExecuteAsync(ct);
}
catch (MsalUiRequiredException)
{
    result = await _pca.AcquireTokenInteractive(scopes).ExecuteAsync(ct);
}

⚠️ Handle user cancellation gracefully

// ✅ Don't treat cancellation as an error
catch (MsalClientException ex) when (ex.ErrorCode == "authentication_canceled")
{
    return null;  // User cancelled — not an error
}

⚠️ Blazor Hybrid: Auth happens at the MAUI layer

In MAUI Blazor Hybrid apps, authentication must happen at the MAUI layer (MSAL.NET), not in the Blazor WebView. Don't use AddMicrosoftIdentityWebApp or server-side OIDC patterns. Instead:

  1. MAUI handles sign-in via IAuthService (MSAL.NET)
  2. A custom MsalAuthenticationStateProvider exposes auth state to Blazor
  3. HttpClient with DelegatingHandler attaches bearer tokens automatically

MSAL.NET Checklist

  • Microsoft.Identity.Client NuGet package added
  • App registration created in Entra ID with correct redirect URIs
  • AuthConfig / appsettings.json has ClientId, TenantId, Scopes
  • Android: AndroidManifest.xml has <queries> for broker and browsers
  • Android: MainActivity.OnActivityResult calls AuthenticationContinuationHelper
  • iOS: Info.plist has CFBundleURLSchemes with msauth.{BundleId}
  • iOS: Entitlements.plist has keychain group com.microsoft.adalcache
  • iOS: AppDelegate.OpenUrl calls AuthenticationContinuationHelper
  • IAuthService registered as singleton in DI
  • DelegatingHandler attached to HttpClient for API calls
  • Login/logout UI wired up
  • MsalUiRequiredException handled (triggers interactive sign-in)
  • MsalClientException with authentication_canceled handled gracefully

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert2mo4 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The skill is a comprehensive documentation resource for .NET MAUI authentication workflows. It includes standard implementation patterns for MSAL.NET and WebAuthenticator. The skill suggests downloading setup scripts from a trusted service provider and provides natural language templates that influence subsequent agent actions.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer8mo

    1/1 file flagged

Signed by skilld at 79bb4bf. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 8 months ago

README badge

README badge for davidortinau/maui-skills/maui-authentication