Auth0 WPF Integration

Auth0.OidcClient.WPF

Agent instruction: Before providing SDK setup instructions, fetch the latest release version by running:

bash

gh api repos/auth0/auth0-oidc-client-net/releases --jq '[.[] | select(.tag_name | startswith("wpf-")) | .tag_name | ltrimstr("wpf-")] | .[0]'

Use the returned version in all dependency lines instead of any hardcoded version below.

Prerequisites

• .NET 6.0 SDK or later (WPF requires Windows)
• Visual Studio 2022 or JetBrains Rider with .NET desktop development workload
• Windows 10 or later
• Microsoft Edge WebView2 Runtime (included with Windows 11, installable on Windows 10)
• Auth0 account with a Native application configured
• Node.js 20+ (for Auth0 CLI automated setup)

When NOT to Use

auth0-maui

auth0-winforms

auth0-aspnetcore-authentication

auth0-aspnetcore-api

auth0-swift

auth0-android

Quick Start Workflow

Agent instruction: Before starting, examine the user's project:

1. Identify the .NET version from the

   .csproj

   file (

   TargetFramework

   )
2. Check if there is already an existing authentication provider in the codebase — search for existing

   Auth0Client

   or

   WebViewBrowser

   usage and reuse if found
3. Note the project's namespace and directory conventions

1. Install SDK:

   dotnet add package Auth0.OidcClient.WPF

2. Configure Auth0: See Setup Guide for automatic or manual configuration.
3. Integrate authentication: Add

   Auth0Client

   initialization and wire login/logout to XAML button click handlers.
4. Build and verify:

   dotnet build

Agent instruction: When writing the Auth0Client configuration:

• Use the exact code patterns from this skill's integration guide.
• The SDK uses WebView2 to show the login page in a popup window — no custom browser setup needed.
• The default callback URL is

  https://{yourDomain}/mobile

  — this must be added to Auth0 Dashboard Allowed Callback URLs and Allowed Logout URLs.
• Unlike native mobile SDKs that use

  https://{domain}/ios/{bundleId}/callback

  or similar platform-specific patterns, WPF uses the simpler

  https://{domain}/mobile

  callback format.

After writing configuration and code, verify the build succeeds:

bash

dotnet build

If the build fails, attempt to fix the issue. After 5-6 failed attempts, ask the user for help.

Callback URL Configuration

https://{yourDomain}/mobile

• Mobile SDKs use platform-specific callbacks like

  https://{domain}/ios/{bundleId}/callback

  or

  https://{domain}/android/{packageName}/callback

• WPF/WinForms use the generic

  https://{yourDomain}/mobile

  callback

NavigationStarting

• Allowed Callback URLs:

  https://{yourDomain}/mobile

• Allowed Logout URLs:

  https://{yourDomain}/mobile

Done When

• Auth0.OidcClient.WPF

  package installed

• Auth0Client

  configured with Domain and ClientId
• Login/logout flow working (WebView2 popup opens for authentication)
• User profile claims accessible after login
• Callback URL

  https://{yourDomain}/mobile

  registered in Auth0 Dashboard
• Build succeeds with no errors
• Tested on real device (physical Windows machine, not just remote desktop)

Detailed Documentation

• Setup Guide — Auth0 tenant configuration, SDK installation, callback URL setup
• Integration Patterns — Login/logout flows, token refresh, user profile, error handling
• API Reference & Testing — Full

  Auth0ClientOptions

  reference, claims, testing checklist, troubleshooting

Common Mistakes

https://{yourDomain}/mobile

https://

tenant.auth0.com

https://tenant.auth0.com

offline_access

offline_access

Scope

Auth0ClientOptions

Testing Notes

Agent instruction: Remind the user to test on a physical device. Some WebView2 behaviors (popup windows, certificate handling) may differ in remote desktop or virtual machine environments vs. physical Windows machines. Test the full login → WebView2 → callback → token flow on real hardware before shipping.

• Login flow: Click login → WebView2 popup opens → authenticate → popup closes → user info displayed
• Logout flow: Click logout → WebView2 popup opens → session cleared → popup closes
• Token refresh:

  RefreshTokenAsync

  with stored refresh token works
• Cancel: User closes WebView2 window → app handles

  UserCancel

  gracefully
• Physical device: Test on a real Windows machine (not just virtual environment)
• Multiple logins: Verify login works after logout (no stale state)

Related Skills

• auth0-winforms — Windows Forms desktop apps
• auth0-maui — .NET MAUI cross-platform apps
• auth0-aspnetcore-authentication — ASP.NET Core server-side web apps
• auth0-aspnetcore-api — ASP.NET Core Web API with JWT validation

Quick Reference

using Auth0.OidcClient;
using System.Diagnostics;

// Initialize client
var client = new Auth0Client(new Auth0ClientOptions
{
    Domain = "{yourDomain}",
    ClientId = "{yourClientId}",
    Scope = "openid profile email offline_access"
});

// Login — opens WebView2 popup window (WebAuth flow with PKCE)
var loginResult = await client.LoginAsync();
if (!loginResult.IsError)
{
    var user = loginResult.User;
    var name = user.FindFirst(c => c.Type == "name")?.Value;
    var email = user.FindFirst(c => c.Type == "email")?.Value;
    var picture = user.FindFirst(c => c.Type == "picture")?.Value;

    Debug.WriteLine($"name: {name}");
    Debug.WriteLine($"email: {email}");

    foreach (var claim in loginResult.User.Claims)
    {
        Debug.WriteLine($"{claim.Type} = {claim.Value}");
    }
}

// Store the refresh token from login for later use
var refreshToken = loginResult.RefreshToken;

// Logout
await client.LogoutAsync();

// Refresh token (requires offline_access scope)
var refreshResult = await client.RefreshTokenAsync(refreshToken);
if (refreshResult.IsError == false)
{
    var newAccessToken = refreshResult.AccessToken;
}

MainWindow.xaml (WPF UI)

<Window x:Class="MyApp.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="Auth0 WPF App" Height="450" Width="800">
    <Grid>
        <StackPanel HorizontalAlignment="Center" VerticalAlignment="Center">
            <Button x:Name="LoginButton" Content="Login" Width="200" Height="40"
                    Margin="10" Click="LoginButton_Click" FontSize="16"/>
            <Button x:Name="LogoutButton" Content="Logout" Width="200" Height="40"
                    Margin="10" Click="LogoutButton_Click" FontSize="16"/>
        </StackPanel>
    </Grid>
</Window>

MainWindow.xaml.cs (WPF Code-Behind)

using Auth0.OidcClient;
using System.Diagnostics;

namespace MyApp;

public partial class MainWindow : Window
{
    private Auth0Client _client;

    public MainWindow()
    {
        InitializeComponent();

        _client = new Auth0Client(new Auth0ClientOptions
        {
            Domain = "{yourDomain}",
            ClientId = "{yourClientId}",
            Scope = "openid profile email offline_access"
        });
    }

    private async void LoginButton_Click(object sender, RoutedEventArgs e)
    {
        var loginResult = await _client.LoginAsync();

        if (loginResult.IsError)
        {
            Debug.WriteLine($"An error occurred during login: {loginResult.Error}");
            return;
        }

        var user = loginResult.User;
        var name = user.FindFirst(c => c.Type == "name")?.Value;
        var email = user.FindFirst(c => c.Type == "email")?.Value;
        var picture = user.FindFirst(c => c.Type == "picture")?.Value;

        Debug.WriteLine($"name: {name}");
        Debug.WriteLine($"email: {email}");

        foreach (var claim in loginResult.User.Claims)
        {
            Debug.WriteLine($"{claim.Type} = {claim.Value}");
        }
    }

    private async void LogoutButton_Click(object sender, RoutedEventArgs e)
    {
        await _client.LogoutAsync();
    }
}

References

• Auth0 WPF/WinForms Quickstart
• GitHub Repository
• NuGet Package
• SDK API Documentation
• Auth0 Native App Documentation