Uno Authentication
Uno.Extensions.Authentication owns the whole session: a provider signs the user in, the tokens are stored in the platform's secure storage, an HTTP handler adds the access token to API calls and refreshes it on a 401, and IAuthenticationService.LoggedOut reports when the session ends. Generic agents write their own IAuthService, keep tokens in settings or a singleton, and set Authorization headers by hand; each of those breaks refresh, restart, or logout. This skill routes you to the provider and the flow.
Workflow
- Pick the provider. A new app gets it from the template:
dotnet new unoapp -preset recommended -auth <custom|msal|oidc|Web>, alongside the flags theuno-build-appskill gives. Then fix the template gaps listed in the critical rules. - Read the provider's reference and
references/flow.md; addreferences/http.mdwhen the app calls an API. - Ground details in the official docs: call
uno_platform_docs_search(...), thenuno_platform_docs_fetch(sourcePath="…")with thesourcePathfrom a result (a relative.mdpath). Never pass a URL,.htmllink, or hand-built path. - Identity-provider values (client IDs, authorities, tenants, redirect URIs registered with the provider) are the developer's. Never invent them: use placeholders and report sign-in as not configured.
Topic map
| Task | Read | Key APIs |
|---|---|---|
| Username/password or API-key login against the app's own backend, or a local prototype check | references/custom.md |
AddCustom, AddCustom<TService>, Login/Refresh/Logout callbacks |
| Sign in with Microsoft Entra ID, Microsoft accounts, or Azure AD B2C | references/msal.md |
AddMsal(window), Scopes, Builder, InteractiveBuilder |
MSAL redirect URIs, Android activity, iOS URL scheme and keychain, WebAssembly spa registration |
references/msal-platforms.md |
BrowserTabActivity, AuthenticationContinuationHelper, keychain-access-groups |
| Any OpenID Connect provider (IdentityServer, Keycloak, Auth0, Okta) | references/oidc.md |
AddOidc, OidcClientOptions, AutoRedirectUriFromWebAuthenticationBroker |
OIDC redirect per head: Android activity scheme, iOS CFBundleURLTypes, WebAssembly callback |
references/oidc-platforms.md |
WebAuthenticationBrokerActivityBase, CFBundleURLTypes, AutoRedirectUriFromWebAuthenticationBroker |
| OIDC or Web sign-in on the Skia desktop head: which Uno.Extensions version has the loopback broker, how to opt in, the loopback redirect URI, the pre-dev.135 workaround | references/oidc-desktop.md |
DesktopWebAuthenticationBrokerProvider, UnoExtensionsVersion, DefaultReturnUri, AddInMemoryCollection |
| A backend that redirects back with tokens in the URL (custom OAuth, social login) | references/web.md |
AddWeb, LoginStartUri, LogoutStartUri, PostLogin |
| Start page by sign-in state, login page, logout, expired session, optional sign-in | references/flow.md |
RefreshAsync, LoggedOut, Qualifiers.ClearBackStack, initialNavigate |
| Access token on Refit/Kiota calls, 401 refresh, cookies, reading tokens and claims | references/http.md |
AddRefitClient, AddKiotaClient, Headers.NoRefresh, ITokenCache |
Critical rules
- Use
IAuthenticationServiceandITokenCache; build no session layer of your own. InjectIAuthenticationServiceinto Models; never createIAuthService, a token store, a "current user" singleton, or anAuthorizationheader by hand. - Features:
Authentication(custom and web providers),AuthenticationMsal, orAuthenticationOidcin<UnoFeatures>. API clients needHttpRefitorHttpKiota;Httpalone adds neither Refit nor Kiota. - Register in the host:
.UseAuthentication(auth => auth.AddCustom(...))insideConfigure. For MSAL, OIDC and Web, the provider'snameargument is also its configuration section (defaultMsal,Oidc,Web; the template usesMsalAuthentication,OidcAuthentication,WebAuthentication).AddCustomreads no section.AddMsaltakes theWindow:.Configure((host, window) => ...). - The user is signed in while any token is stored. A custom
Loginreturns a new dictionary holding only tokens (TokenCacheExtensions.AccessTokenKey, ...), ornullto fail. The template returns thecredentialsdictionary, which stores the password: replace that. - Pass the dispatcher:
LoginAsync(Dispatcher, credentials). The MSAL provider throws without one; injectIDispatcherinto the login Model. - Subscribe to
LoggedOutonce, at app lifetime, and navigate to login withQualifiers.ClearBackStackthere. It fires on logout, on a failed refresh, and on an API 401 that a refresh could not fix. The recommended template does not subscribe, so logout leaves the user on the signed-in page. AfterLogoutAsync, do not navigate again. - Only Uno-registered clients carry the token:
AddRefitClient,AddKiotaClientorAddClientinsideUseHttp.AddHttpClientandnew HttpClient()send no token. Mark the token-refresh endpoint[Headers(Uno.Extensions.Authentication.Headers.NoRefresh)]. - Provider traps:
AddWebwithoutLogoutStartUricannot sign out (LogoutAsyncreturnsfalse). OIDC needs theoffline_accessscope, or the session ends at every restart. On the Skia desktop head, OIDC and Web sign-in need Uno.Extensions 8.0.0-dev.135 or later plus a loopbackhttp://localhost:<port>/...redirect URI: from that versionAddOidcandAddWebregister a loopbackWebAuthenticationBroker; Uno.Sdk 7.0.0-dev.95 and later pin such a version; on an older Sdk Uno's broker throwsNotImplementedExceptionthere and the app must opt in or bring its own browser (references/oidc-desktop.md). The desktop listener takes any local request, soAddWebapps must check astate(references/web.md). OIDC'sLogoutAsyncclears the tokens whatever the browser returned; before dev.135 it sent noid_token_hint, so identity providers did not redirect back and the call waited up to 300 s. The template's redirect schememyprotocolis a placeholder in the Android activities, iOSInfo.plist(where it is also misplaced),Package.appxmanifestandappsettings.development.json; for OIDC and Web, replace it everywhere. For MSAL, the Android activity takesmsal<client-id>andInfo.plisttakesmsauth.<bundle-id>underCFBundleURLTypes, but delete theRedirectUrikey from both appsettings files rather than filling it: a configured value replaces the per-platform redirect URIs on every head, somsal<client-id>://auththere breaks iOS, WebAssembly and desktop (references/msal-platforms.md). The template'sKeychainSecurityGroupkey is read by nothing. Tokens live in Keychain on iOS, so the app needs keychain entitlements there.
Verified against Uno.Extensions 8.0.0-dev.85 (pinned by Uno.Sdk 7.0.0-dev.77), 8.0.0-dev.135 (the first with desktop sign-in) and 8.0.0-dev.150 (Uno.Sdk 7.0.0-dev.115), with Uno.Templates 7.0.0-dev.77 and 7.0.0-dev.115. On other versions, check the template output and the docs.
Related skills
uno-navigationfor routes,initialNavigate, andQualifiers.ClearBackStack(references/qualifiers.md).uno-mvuxfor the login Model's states and commands.uno-kiotafor generating, registering and calling the Kiota client the token is added to.uno-testingto exercise sign-in, logout, and the expired-session path in the running app.