From cacdd90786915bef5e34ba1984b646083a93bbda Mon Sep 17 00:00:00 2001
From: jeromydean <jeromydean@gmail.com>
Date: Fri, 20 Mar 2026 19:33:01 -0400
Subject: [PATCH] Implemented OAuth 2.0 server metadata discovery

Implemented PKCE helpers for WebAuthenticationBroker
---
 Avalonia.Controls.WebView.slnx                |   1 +
 .../App.axaml                                 |   8 +
 .../App.axaml.cs                              |  20 +++
 ...lonia.Controls.WebView.Samples.Oidc.csproj |  22 +++
 .../MainWindow.axaml                          |  39 +++++
 .../MainWindow.axaml.cs                       |  94 ++++++++++++
 .../Program.cs                                |  16 ++
 .../README.md                                 |   5 +
 .../app.manifest                              |   9 ++
 .../OAuth2/AuthorizationCallbackParser.cs     |  76 ++++++++++
 .../OAuth2/AuthorizationCodePkceSession.cs    | 138 ++++++++++++++++++
 .../OAuth2/AuthorizationServerMetadata.cs     |  33 +++++
 .../AuthorizationServerMetadataClient.cs      |  54 +++++++
 .../OAuth2/AuthorizationServerTokenClient.cs  |  65 +++++++++
 .../OAuth2/OAuth2JsonContext.cs               |   9 ++
 .../OAuth2/OAuth2TokenResponse.cs             |  33 +++++
 src/Avalonia.Controls.WebView/OAuth2/Pkce.cs  |  46 ++++++
 src/Avalonia.Controls.WebView/README.md       |   8 +-
 .../OAuth2Tests.cs                            |  99 +++++++++++++
 19 files changed, 774 insertions(+), 1 deletion(-)
 create mode 100644 samples/Avalonia.Controls.WebView.Samples.Oidc/App.axaml
 create mode 100644 samples/Avalonia.Controls.WebView.Samples.Oidc/App.axaml.cs
 create mode 100644 samples/Avalonia.Controls.WebView.Samples.Oidc/Avalonia.Controls.WebView.Samples.Oidc.csproj
 create mode 100644 samples/Avalonia.Controls.WebView.Samples.Oidc/MainWindow.axaml
 create mode 100644 samples/Avalonia.Controls.WebView.Samples.Oidc/MainWindow.axaml.cs
 create mode 100644 samples/Avalonia.Controls.WebView.Samples.Oidc/Program.cs
 create mode 100644 samples/Avalonia.Controls.WebView.Samples.Oidc/README.md
 create mode 100644 samples/Avalonia.Controls.WebView.Samples.Oidc/app.manifest
 create mode 100644 src/Avalonia.Controls.WebView/OAuth2/AuthorizationCallbackParser.cs
 create mode 100644 src/Avalonia.Controls.WebView/OAuth2/AuthorizationCodePkceSession.cs
 create mode 100644 src/Avalonia.Controls.WebView/OAuth2/AuthorizationServerMetadata.cs
 create mode 100644 src/Avalonia.Controls.WebView/OAuth2/AuthorizationServerMetadataClient.cs
 create mode 100644 src/Avalonia.Controls.WebView/OAuth2/AuthorizationServerTokenClient.cs
 create mode 100644 src/Avalonia.Controls.WebView/OAuth2/OAuth2JsonContext.cs
 create mode 100644 src/Avalonia.Controls.WebView/OAuth2/OAuth2TokenResponse.cs
 create mode 100644 src/Avalonia.Controls.WebView/OAuth2/Pkce.cs
 create mode 100644 tests/Avalonia.Controls.WebView.Tests/OAuth2Tests.cs

diff --git a/Avalonia.Controls.WebView.slnx b/Avalonia.Controls.WebView.slnx
index ab5330a..a3fcdf3 100644
--- a/Avalonia.Controls.WebView.slnx
+++ b/Avalonia.Controls.WebView.slnx
@@ -17,6 +17,7 @@
     </Project>
     <Project Path="samples/Avalonia.Controls.WebView.Samples.Browser/Avalonia.Controls.WebView.Samples.Browser.csproj" />
     <Project Path="samples/Avalonia.Controls.WebView.Samples.Desktop/Avalonia.Controls.WebView.Samples.Desktop.csproj" />
+    <Project Path="samples/Avalonia.Controls.WebView.Samples.Oidc/Avalonia.Controls.WebView.Samples.Oidc.csproj" />
     <Project Path="samples/Avalonia.Controls.WebView.Samples.iOS/Avalonia.Controls.WebView.Samples.iOS.csproj" />
     <Project Path="samples/Avalonia.Controls.WebView.Samples/Avalonia.Controls.WebView.Samples.csproj">
       <Platform Solution="*|x64" Project="x64" />
diff --git a/samples/Avalonia.Controls.WebView.Samples.Oidc/App.axaml b/samples/Avalonia.Controls.WebView.Samples.Oidc/App.axaml
new file mode 100644
index 0000000..8b34271
--- /dev/null
+++ b/samples/Avalonia.Controls.WebView.Samples.Oidc/App.axaml
@@ -0,0 +1,8 @@
+<Application xmlns="https://github.com/avaloniaui"
+             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+             x:Class="Avalonia.Controls.WebView.Samples.Oidc.App"
+             RequestedThemeVariant="Default">
+    <Application.Styles>
+        <FluentTheme />
+    </Application.Styles>
+</Application>
diff --git a/samples/Avalonia.Controls.WebView.Samples.Oidc/App.axaml.cs b/samples/Avalonia.Controls.WebView.Samples.Oidc/App.axaml.cs
new file mode 100644
index 0000000..b90bf05
--- /dev/null
+++ b/samples/Avalonia.Controls.WebView.Samples.Oidc/App.axaml.cs
@@ -0,0 +1,20 @@
+using Avalonia.Controls.ApplicationLifetimes;
+using Avalonia.Markup.Xaml;
+
+namespace Avalonia.Controls.WebView.Samples.Oidc;
+
+public class App : Application
+{
+    public override void Initialize()
+    {
+        AvaloniaXamlLoader.Load(this);
+    }
+
+    public override void OnFrameworkInitializationCompleted()
+    {
+        if (ApplicationLifetime is IClassicDesktopStyleApplicationLifetime desktop)
+            desktop.MainWindow = new MainWindow();
+
+        base.OnFrameworkInitializationCompleted();
+    }
+}
diff --git a/samples/Avalonia.Controls.WebView.Samples.Oidc/Avalonia.Controls.WebView.Samples.Oidc.csproj b/samples/Avalonia.Controls.WebView.Samples.Oidc/Avalonia.Controls.WebView.Samples.Oidc.csproj
new file mode 100644
index 0000000..96e3f7c
--- /dev/null
+++ b/samples/Avalonia.Controls.WebView.Samples.Oidc/Avalonia.Controls.WebView.Samples.Oidc.csproj
@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>WinExe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <RootNamespace>Avalonia.Controls.WebView.Samples.Oidc</RootNamespace>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <ApplicationManifest>app.manifest</ApplicationManifest>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Avalonia.Desktop" Version="$(AvaloniaSampleVersion)" />
+    <PackageReference Include="Avalonia.Themes.Fluent" Version="$(AvaloniaSampleVersion)" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Avalonia.Controls.WebView\Avalonia.Controls.WebView.csproj" />
+    <ProjectReference Include="..\..\src\Avalonia.Controls.WebView.Core\Avalonia.Controls.WebView.Core.csproj" />
+  </ItemGroup>
+</Project>
diff --git a/samples/Avalonia.Controls.WebView.Samples.Oidc/MainWindow.axaml b/samples/Avalonia.Controls.WebView.Samples.Oidc/MainWindow.axaml
new file mode 100644
index 0000000..e403c63
--- /dev/null
+++ b/samples/Avalonia.Controls.WebView.Samples.Oidc/MainWindow.axaml
@@ -0,0 +1,39 @@
+<Window xmlns="https://github.com/avaloniaui"
+        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+        x:Class="Avalonia.Controls.WebView.Samples.Oidc.MainWindow"
+        Title="OAuth 2.0 Authorization Server Metadata (RFC 8414) + PKCE"
+        Width="720"
+        Height="640">
+    <DockPanel Margin="12">
+        <StackPanel DockPanel.Dock="Top" Spacing="8">
+            <TextBlock TextWrapping="Wrap"
+                       Text="Uses /.well-known/oauth-authorization-server, then authorization code with PKCE (S256). Register the redirect URI with your identity provider." />
+            <TextBlock Text="Issuer (authorization server identifier URL)" FontWeight="SemiBold" />
+            <TextBox x:Name="IssuerBox"
+                     Text="https://login.microsoftonline.com/common/v2.0" />
+            <TextBlock Text="Client ID" FontWeight="SemiBold" />
+            <TextBox x:Name="ClientIdBox"
+                     PlaceholderText="Application (client) ID" />
+            <TextBlock Text="Redirect URI (must match app registration)" FontWeight="SemiBold" />
+            <TextBox x:Name="RedirectBox"
+                     Text="http://localhost" />
+            <TextBlock Text="Scope" FontWeight="SemiBold" />
+            <TextBox x:Name="ScopeBox"
+                     Text="openid profile offline_access" />
+            <Button HorizontalAlignment="Left"
+                    Content="Sign in (metadata → broker → token)"
+                    Click="SignIn_OnClick" />
+        </StackPanel>
+        <TextBlock DockPanel.Dock="Top"
+                   Margin="0,12,0,4"
+                   Text="Log"
+                   FontWeight="SemiBold" />
+        <ScrollViewer>
+            <TextBox x:Name="LogBox"
+                     AcceptsReturn="True"
+                     IsReadOnly="True"
+                     TextWrapping="Wrap"
+                     FontFamily="Consolas" />
+        </ScrollViewer>
+    </DockPanel>
+</Window>
diff --git a/samples/Avalonia.Controls.WebView.Samples.Oidc/MainWindow.axaml.cs b/samples/Avalonia.Controls.WebView.Samples.Oidc/MainWindow.axaml.cs
new file mode 100644
index 0000000..7807b38
--- /dev/null
+++ b/samples/Avalonia.Controls.WebView.Samples.Oidc/MainWindow.axaml.cs
@@ -0,0 +1,94 @@
+using System;
+using System.Text;
+using Avalonia.Controls;
+using Avalonia.Controls.OAuth2;
+using Avalonia.Interactivity;
+
+namespace Avalonia.Controls.WebView.Samples.Oidc;
+
+public partial class MainWindow : Window
+{
+    public MainWindow()
+    {
+        InitializeComponent();
+    }
+
+    async void SignIn_OnClick(object? sender, RoutedEventArgs e)
+    {
+        var issuer = IssuerBox.Text?.Trim() ?? "";
+        var clientId = ClientIdBox.Text?.Trim() ?? "";
+        var redirectText = RedirectBox.Text?.Trim() ?? "";
+        var scope = ScopeBox.Text?.Trim() ?? "";
+
+        if (issuer.Length == 0 || clientId.Length == 0 || redirectText.Length == 0 || scope.Length == 0)
+        {
+            AppendLog("Fill issuer, client ID, redirect URI, and scope.");
+            return;
+        }
+
+        try
+        {
+            AppendLog($"GET {AuthorizationServerMetadataClient.GetWellKnownMetadataUrl(issuer)}");
+            var metadata = await AuthorizationServerMetadataClient.GetAsync(issuer).ConfigureAwait(true);
+            if (metadata.AuthorizationEndpoint is { } ae)
+                AppendLog($"authorization_endpoint: {ae}");
+            if (metadata.TokenEndpoint is { } te)
+                AppendLog($"token_endpoint: {te}");
+
+            var session = AuthorizationCodePkceSession.Create(metadata, clientId, redirectText, scope);
+
+            var options = new WebAuthenticatorOptions(session.AuthorizationUri, session.RedirectUri)
+            {
+                PreferNativeWebDialog = true,
+            };
+
+            var topLevel = TopLevel.GetTopLevel(this);
+            if (topLevel is null)
+            {
+                AppendLog("TopLevel not found.");
+                return;
+            }
+
+            AppendLog("Opening WebAuthenticationBroker…");
+            var result = await WebAuthenticationBroker.AuthenticateAsync(topLevel, options).ConfigureAwait(true);
+
+            var parsed = AuthorizationCallbackParser.Parse(result.CallbackUri, session.State);
+            AppendLog("Authorization code received; exchanging at token_endpoint…");
+
+            var token = await AuthorizationServerTokenClient.ExchangeAuthorizationCodeAsync(
+                metadata,
+                clientId,
+                parsed.AuthorizationCode,
+                session.RedirectUriString,
+                session.CodeVerifier).ConfigureAwait(true);
+
+            var sb = new StringBuilder();
+            sb.AppendLine("Token response:");
+            sb.AppendLine($"  token_type: {token.TokenType}");
+            sb.AppendLine($"  expires_in: {token.ExpiresIn}");
+            sb.AppendLine($"  scope: {token.Scope}");
+            if (!string.IsNullOrEmpty(token.AccessToken))
+                sb.AppendLine($"  access_token: {Preview(token.AccessToken)}");
+            if (!string.IsNullOrEmpty(token.IdToken))
+                sb.AppendLine($"  id_token: {Preview(token.IdToken)}");
+            if (!string.IsNullOrEmpty(token.RefreshToken))
+                sb.AppendLine($"  refresh_token: {Preview(token.RefreshToken)}");
+            AppendLog(sb.ToString());
+        }
+        catch (Exception ex)
+        {
+            AppendLog(ex.ToString());
+        }
+    }
+
+    static string Preview(string value)
+    {
+        const int max = 48;
+        return value.Length <= max ? value : value[..max] + "…";
+    }
+
+    void AppendLog(string line)
+    {
+        LogBox.Text += line + Environment.NewLine;
+    }
+}
diff --git a/samples/Avalonia.Controls.WebView.Samples.Oidc/Program.cs b/samples/Avalonia.Controls.WebView.Samples.Oidc/Program.cs
new file mode 100644
index 0000000..ee7797a
--- /dev/null
+++ b/samples/Avalonia.Controls.WebView.Samples.Oidc/Program.cs
@@ -0,0 +1,16 @@
+using System;
+using Avalonia;
+
+namespace Avalonia.Controls.WebView.Samples.Oidc;
+
+internal static class Program
+{
+    [STAThread]
+    public static void Main(string[] args) => BuildAvaloniaApp()
+        .StartWithClassicDesktopLifetime(args);
+
+    public static AppBuilder BuildAvaloniaApp()
+        => AppBuilder.Configure<App>()
+            .UsePlatformDetect()
+            .LogToTrace();
+}
diff --git a/samples/Avalonia.Controls.WebView.Samples.Oidc/README.md b/samples/Avalonia.Controls.WebView.Samples.Oidc/README.md
new file mode 100644
index 0000000..f6b3956
--- /dev/null
+++ b/samples/Avalonia.Controls.WebView.Samples.Oidc/README.md
@@ -0,0 +1,5 @@
+# OAuth 2.0 + PKCE sample (RFC 8414)
+
+This app loads **Authorization Server Metadata** from `{issuer}/.well-known/oauth-authorization-server`, starts an **authorization code** request with **PKCE (S256)**, completes login via `WebAuthenticationBroker`, then **exchanges the code** at the metadata `token_endpoint`.
+
+Register a public client with your identity provider and add the redirect URI you use here (for example `http://localhost`). The issuer must publish RFC 8414 metadata; if only OpenID Connect discovery is available, use an issuer that exposes both or a server that implements RFC 8414.
diff --git a/samples/Avalonia.Controls.WebView.Samples.Oidc/app.manifest b/samples/Avalonia.Controls.WebView.Samples.Oidc/app.manifest
new file mode 100644
index 0000000..8bcc872
--- /dev/null
+++ b/samples/Avalonia.Controls.WebView.Samples.Oidc/app.manifest
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
+  <assemblyIdentity version="1.0.0.0" name="Avalonia.Controls.WebView.Samples.Oidc"/>
+  <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
+    <application>
+      <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}" />
+    </application>
+  </compatibility>
+</assembly>
diff --git a/src/Avalonia.Controls.WebView/OAuth2/AuthorizationCallbackParser.cs b/src/Avalonia.Controls.WebView/OAuth2/AuthorizationCallbackParser.cs
new file mode 100644
index 0000000..48d1482
--- /dev/null
+++ b/src/Avalonia.Controls.WebView/OAuth2/AuthorizationCallbackParser.cs
@@ -0,0 +1,76 @@
+using System;
+using System.Collections.Generic;
+
+namespace Avalonia.Controls.OAuth2;
+
+/// <summary>Parses the authorization response redirect (query string).</summary>
+public static class AuthorizationCallbackParser
+{
+    /// <summary>
+    /// Parses <paramref name="callbackUri"/> query for <c>code</c>, <c>state</c>, and OAuth <c>error</c> parameters.
+    /// </summary>
+    /// <param name="callbackUri">The redirect URI including query from the authorization server.</param>
+    /// <param name="expectedState">The <c>state</c> value from the authorization request.</param>
+    /// <returns>The parsed authorization code.</returns>
+    /// <exception cref="InvalidOperationException">Missing code, state mismatch, or error response.</exception>
+    public static AuthorizationCallbackResult Parse(Uri callbackUri, string expectedState)
+    {
+        var query = callbackUri.Query;
+        if (string.IsNullOrEmpty(query))
+            throw new InvalidOperationException("Callback URI has no query string.");
+
+        var coll = ParseQueryString(query);
+        if (coll.TryGetValue("error", out var error) && !string.IsNullOrEmpty(error))
+        {
+            coll.TryGetValue("error_description", out var desc);
+            throw new InvalidOperationException(
+                string.IsNullOrEmpty(desc) ? error : $"{error}: {desc}");
+        }
+
+        if (!coll.TryGetValue("code", out var code) || string.IsNullOrEmpty(code))
+            throw new InvalidOperationException("Callback URI is missing code.");
+
+        if (!coll.TryGetValue("state", out var state) || string.IsNullOrEmpty(state))
+            throw new InvalidOperationException("Callback URI is missing state.");
+
+        if (!string.Equals(state, expectedState, StringComparison.Ordinal))
+            throw new InvalidOperationException("State does not match the authorization request.");
+
+        return new AuthorizationCallbackResult(code);
+    }
+
+    static Dictionary<string, string> ParseQueryString(string query)
+    {
+        var d = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+        var trimmed = query.StartsWith("?", StringComparison.Ordinal) ? query[1..] : query;
+        if (trimmed.Length == 0)
+            return d;
+
+        foreach (var part in trimmed.Split('&'))
+        {
+            if (part.Length == 0)
+                continue;
+            var i = part.IndexOf('=');
+            string key;
+            string value;
+            if (i < 0)
+            {
+                key = Uri.UnescapeDataString(part);
+                value = "";
+            }
+            else
+            {
+                key = Uri.UnescapeDataString(part[..i]);
+                value = Uri.UnescapeDataString(part[(i + 1)..]);
+            }
+
+            d[key] = value;
+        }
+
+        return d;
+    }
+}
+
+/// <summary>OAuth authorization redirect response values.</summary>
+/// <param name="AuthorizationCode">The authorization code for the token endpoint.</param>
+public readonly record struct AuthorizationCallbackResult(string AuthorizationCode);
diff --git a/src/Avalonia.Controls.WebView/OAuth2/AuthorizationCodePkceSession.cs b/src/Avalonia.Controls.WebView/OAuth2/AuthorizationCodePkceSession.cs
new file mode 100644
index 0000000..d653ad1
--- /dev/null
+++ b/src/Avalonia.Controls.WebView/OAuth2/AuthorizationCodePkceSession.cs
@@ -0,0 +1,138 @@
+using System;
+using System.Collections.Generic;
+using System.Security.Cryptography;
+
+namespace Avalonia.Controls.OAuth2;
+
+/// <summary>
+/// Holds PKCE and CSRF values for one authorization code flow built from
+/// <see cref="AuthorizationServerMetadata"/> (RFC 8414).
+/// </summary>
+public sealed class AuthorizationCodePkceSession
+{
+    AuthorizationCodePkceSession(
+        Uri authorizationUri,
+        Uri redirectUri,
+        string redirectUriString,
+        string state,
+        string codeVerifier,
+        string? nonce)
+    {
+        AuthorizationUri = authorizationUri;
+        RedirectUri = redirectUri;
+        RedirectUriString = redirectUriString;
+        State = state;
+        CodeVerifier = codeVerifier;
+        Nonce = nonce;
+    }
+
+    /// <summary>Gets the full authorization request URL (includes query).</summary>
+    public Uri AuthorizationUri { get; }
+
+    /// <summary>
+    /// Gets the redirect URI registered for the client (used for broker callback matching).
+    /// </summary>
+    public Uri RedirectUri { get; }
+
+    /// <summary>
+    /// Gets the exact <c>redirect_uri</c> string sent to the authorize and token endpoints
+    /// (must match client registration byte-for-byte).
+    /// Use this instead of <see cref="Uri.ToString"/> on <see cref="RedirectUri"/>, which can add a trailing slash.
+    /// </summary>
+    public string RedirectUriString { get; }
+
+    /// <summary>Gets the opaque CSRF value sent as <c>state</c>.</summary>
+    public string State { get; }
+
+    /// <summary>Gets the PKCE code verifier; send to the token endpoint as <c>code_verifier</c>.</summary>
+    public string CodeVerifier { get; }
+
+    /// <summary>Gets the optional OIDC nonce, if requested.</summary>
+    public string? Nonce { get; }
+
+    /// <summary>
+    /// Creates a session: validates metadata for authorization code + S256 PKCE, then builds the authorization URL.
+    /// </summary>
+    /// <param name="metadata">Authorization server metadata from RFC 8414 discovery.</param>
+    /// <param name="clientId">OAuth client identifier.</param>
+    /// <param name="redirectUri">Registered redirect URI (exact string; must match token request).</param>
+    /// <param name="scope">Space-separated OAuth scopes.</param>
+    /// <param name="nonce">Optional OpenID Connect nonce.</param>
+    /// <param name="resource">Optional resource indicator (RFC 8707).</param>
+    /// <returns>A session holding URIs, PKCE verifier, and state for the broker and token exchange.</returns>
+    public static AuthorizationCodePkceSession Create(
+        AuthorizationServerMetadata metadata,
+        string clientId,
+        string redirectUri,
+        string scope,
+        string? nonce = null,
+        string? resource = null)
+    {
+        if (metadata.AuthorizationEndpoint is not { Length: > 0 } authEndpoint)
+            throw new InvalidOperationException("Authorization server metadata is missing authorization_endpoint.");
+
+        var redirectForOAuth = redirectUri.Trim();
+        if (redirectForOAuth.Length == 0)
+            throw new ArgumentException("Redirect URI is required.", nameof(redirectUri));
+
+        if (!Uri.TryCreate(redirectForOAuth, UriKind.Absolute, out var redirectUriParsed))
+            throw new ArgumentException("Redirect URI must be an absolute URL.", nameof(redirectUri));
+
+        EnsurePkceS256Supported(metadata);
+
+        var codeVerifier = Pkce.CreateCodeVerifier();
+        var codeChallenge = Pkce.CreateCodeChallengeS256(codeVerifier);
+        var state = CreateState();
+
+        var query = new List<string>
+        {
+            "response_type=code",
+            $"client_id={Uri.EscapeDataString(clientId)}",
+            $"redirect_uri={Uri.EscapeDataString(redirectForOAuth)}",
+            $"scope={Uri.EscapeDataString(scope)}",
+            $"state={Uri.EscapeDataString(state)}",
+            $"code_challenge={Uri.EscapeDataString(codeChallenge)}",
+            "code_challenge_method=S256",
+        };
+
+        if (!string.IsNullOrEmpty(nonce))
+            query.Add($"nonce={Uri.EscapeDataString(nonce)}");
+
+        if (!string.IsNullOrEmpty(resource))
+            query.Add($"resource={Uri.EscapeDataString(resource)}");
+
+        var separator = authEndpoint.Contains('?', StringComparison.Ordinal) ? '&' : '?';
+        var authorizationUri = new Uri($"{authEndpoint}{separator}{string.Join("&", query)}");
+
+        return new AuthorizationCodePkceSession(
+            authorizationUri,
+            redirectUriParsed,
+            redirectForOAuth,
+            state,
+            codeVerifier,
+            nonce);
+    }
+
+    static void EnsurePkceS256Supported(AuthorizationServerMetadata metadata)
+    {
+        var methods = metadata.CodeChallengeMethodsSupported;
+        if (methods is null || methods.Length == 0)
+            return;
+
+        foreach (var m in methods)
+        {
+            if (string.Equals(m, "S256", StringComparison.OrdinalIgnoreCase))
+                return;
+        }
+
+        throw new InvalidOperationException(
+            "Authorization server metadata lists code_challenge_methods_supported but does not include S256.");
+    }
+
+    static string CreateState()
+    {
+        var bytes = new byte[32];
+        RandomNumberGenerator.Fill(bytes);
+        return Convert.ToHexString(bytes);
+    }
+}
diff --git a/src/Avalonia.Controls.WebView/OAuth2/AuthorizationServerMetadata.cs b/src/Avalonia.Controls.WebView/OAuth2/AuthorizationServerMetadata.cs
new file mode 100644
index 0000000..7834e01
--- /dev/null
+++ b/src/Avalonia.Controls.WebView/OAuth2/AuthorizationServerMetadata.cs
@@ -0,0 +1,33 @@
+using System.Text.Json.Serialization;
+
+namespace Avalonia.Controls.OAuth2;
+
+/// <summary>
+/// OAuth 2.0 Authorization Server Metadata per <see href="https://www.rfc-editor.org/rfc/rfc8414">RFC 8414</see>.
+/// </summary>
+public sealed class AuthorizationServerMetadata
+{
+    /// <summary>Gets the required issuer identifier.</summary>
+    [JsonPropertyName("issuer")]
+    public string? Issuer { get; init; }
+
+    /// <summary>Gets the URL of the authorization endpoint.</summary>
+    [JsonPropertyName("authorization_endpoint")]
+    public string? AuthorizationEndpoint { get; init; }
+
+    /// <summary>Gets the URL of the token endpoint.</summary>
+    [JsonPropertyName("token_endpoint")]
+    public string? TokenEndpoint { get; init; }
+
+    /// <summary>Gets the PKCE code challenge methods supported by the authorization server.</summary>
+    [JsonPropertyName("code_challenge_methods_supported")]
+    public string[]? CodeChallengeMethodsSupported { get; init; }
+
+    /// <summary>Gets the OAuth scopes the authorization server supports.</summary>
+    [JsonPropertyName("scopes_supported")]
+    public string[]? ScopesSupported { get; init; }
+
+    /// <summary>Gets the OAuth response types the authorization server supports.</summary>
+    [JsonPropertyName("response_types_supported")]
+    public string[]? ResponseTypesSupported { get; init; }
+}
diff --git a/src/Avalonia.Controls.WebView/OAuth2/AuthorizationServerMetadataClient.cs b/src/Avalonia.Controls.WebView/OAuth2/AuthorizationServerMetadataClient.cs
new file mode 100644
index 0000000..eec3258
--- /dev/null
+++ b/src/Avalonia.Controls.WebView/OAuth2/AuthorizationServerMetadataClient.cs
@@ -0,0 +1,54 @@
+using System;
+using System.Net.Http;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Avalonia.Controls.OAuth2;
+
+/// <summary>
+/// Fetches <see cref="AuthorizationServerMetadata"/> from the RFC 8414 well-known URL
+/// <c>/.well-known/oauth-authorization-server</c>.
+/// </summary>
+public static class AuthorizationServerMetadataClient
+{
+    private static readonly HttpClient SharedClient = new();
+
+    /// <summary>
+    /// GET <c>{issuer}/.well-known/oauth-authorization-server</c> and deserialize metadata.
+    /// </summary>
+    /// <param name="issuer">Authorization server issuer identifier (URL, no fragment or query).</param>
+    /// <param name="httpClient">Optional <see cref="HttpClient"/>; a shared instance is used when null.</param>
+    /// <param name="cancellationToken">Token to cancel the operation.</param>
+    /// <returns>The deserialized authorization server metadata.</returns>
+    public static async Task<AuthorizationServerMetadata> GetAsync(
+        string issuer,
+        HttpClient? httpClient = null,
+        CancellationToken cancellationToken = default)
+    {
+        if (string.IsNullOrWhiteSpace(issuer))
+            throw new ArgumentException("Issuer is required.", nameof(issuer));
+
+        var metadataUrl = GetWellKnownMetadataUrl(issuer);
+        var client = httpClient ?? SharedClient;
+        using var response = await client.GetAsync(metadataUrl, cancellationToken).ConfigureAwait(false);
+        response.EnsureSuccessStatusCode();
+        var json = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+        var metadata = JsonSerializer.Deserialize(json, OAuth2JsonContext.Default.AuthorizationServerMetadata);
+        if (metadata is null)
+            throw new InvalidOperationException("Authorization server metadata response was empty.");
+
+        return metadata;
+    }
+
+    /// <summary>
+    /// Builds the RFC 8414 metadata URL: issuer path + <c>/.well-known/oauth-authorization-server</c>.
+    /// </summary>
+    /// <param name="issuer">The authorization server issuer identifier.</param>
+    /// <returns>The absolute metadata document URL.</returns>
+    public static string GetWellKnownMetadataUrl(string issuer)
+    {
+        var trimmed = issuer.TrimEnd('/');
+        return $"{trimmed}/.well-known/oauth-authorization-server";
+    }
+}
diff --git a/src/Avalonia.Controls.WebView/OAuth2/AuthorizationServerTokenClient.cs b/src/Avalonia.Controls.WebView/OAuth2/AuthorizationServerTokenClient.cs
new file mode 100644
index 0000000..601ac50
--- /dev/null
+++ b/src/Avalonia.Controls.WebView/OAuth2/AuthorizationServerTokenClient.cs
@@ -0,0 +1,65 @@
+using System;
+using System.Collections.Generic;
+using System.Net.Http;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Avalonia.Controls.OAuth2;
+
+/// <summary>Exchanges an authorization code for tokens at the RFC 8414 <c>token_endpoint</c>.</summary>
+public static class AuthorizationServerTokenClient
+{
+    private static readonly HttpClient SharedClient = new();
+
+    /// <summary>
+    /// POST <c>grant_type=authorization_code</c> with PKCE <paramref name="codeVerifier"/>.
+    /// </summary>
+    /// <param name="metadata">Authorization server metadata (must include <c>token_endpoint</c>).</param>
+    /// <param name="clientId">OAuth client identifier.</param>
+    /// <param name="authorizationCode">The code from the authorization redirect.</param>
+    /// <param name="redirectUri">Exact <c>redirect_uri</c> used in the authorization request.</param>
+    /// <param name="codeVerifier">The PKCE code verifier for this flow.</param>
+    /// <param name="httpClient">Optional HTTP client; a shared instance is used when null.</param>
+    /// <param name="clientSecret">Optional client secret for confidential clients.</param>
+    /// <param name="cancellationToken">Token to cancel the operation.</param>
+    /// <returns>The token response from the authorization server.</returns>
+    public static async Task<OAuth2TokenResponse> ExchangeAuthorizationCodeAsync(
+        AuthorizationServerMetadata metadata,
+        string clientId,
+        string authorizationCode,
+        string redirectUri,
+        string codeVerifier,
+        HttpClient? httpClient = null,
+        string? clientSecret = null,
+        CancellationToken cancellationToken = default)
+    {
+        if (metadata.TokenEndpoint is not { Length: > 0 } tokenEndpoint)
+            throw new InvalidOperationException("Authorization server metadata is missing token_endpoint.");
+
+        var form = new List<KeyValuePair<string, string>>
+        {
+            new("grant_type", "authorization_code"),
+            new("client_id", clientId),
+            new("code", authorizationCode),
+            new("redirect_uri", redirectUri),
+            new("code_verifier", codeVerifier),
+        };
+
+        if (!string.IsNullOrEmpty(clientSecret))
+            form.Add(new KeyValuePair<string, string>("client_secret", clientSecret));
+
+        var client = httpClient ?? SharedClient;
+        using var content = new FormUrlEncodedContent(form);
+        using var response = await client.PostAsync(tokenEndpoint, content, cancellationToken).ConfigureAwait(false);
+        var body = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+        if (!response.IsSuccessStatusCode)
+            throw new InvalidOperationException($"Token endpoint returned {(int)response.StatusCode}: {body}");
+
+        var token = JsonSerializer.Deserialize(body, OAuth2JsonContext.Default.OAuth2TokenResponse);
+        if (token is null || string.IsNullOrEmpty(token.AccessToken))
+            throw new InvalidOperationException("Token response could not be read.");
+
+        return token;
+    }
+}
diff --git a/src/Avalonia.Controls.WebView/OAuth2/OAuth2JsonContext.cs b/src/Avalonia.Controls.WebView/OAuth2/OAuth2JsonContext.cs
new file mode 100644
index 0000000..8d9b1a6
--- /dev/null
+++ b/src/Avalonia.Controls.WebView/OAuth2/OAuth2JsonContext.cs
@@ -0,0 +1,9 @@
+using System.Text.Json.Serialization;
+
+namespace Avalonia.Controls.OAuth2;
+
+/// <summary>System.Text.Json source generation context for OAuth 2.0 metadata and token JSON.</summary>
+[JsonSourceGenerationOptions(PropertyNameCaseInsensitive = true)]
+[JsonSerializable(typeof(AuthorizationServerMetadata))]
+[JsonSerializable(typeof(OAuth2TokenResponse))]
+internal partial class OAuth2JsonContext : JsonSerializerContext;
diff --git a/src/Avalonia.Controls.WebView/OAuth2/OAuth2TokenResponse.cs b/src/Avalonia.Controls.WebView/OAuth2/OAuth2TokenResponse.cs
new file mode 100644
index 0000000..8c078e2
--- /dev/null
+++ b/src/Avalonia.Controls.WebView/OAuth2/OAuth2TokenResponse.cs
@@ -0,0 +1,33 @@
+using System.Text.Json.Serialization;
+
+namespace Avalonia.Controls.OAuth2;
+
+/// <summary>
+/// Successful token endpoint response (subset of fields commonly used with authorization code + PKCE).
+/// </summary>
+public sealed class OAuth2TokenResponse
+{
+    /// <summary>Gets the access token issued by the authorization server.</summary>
+    [JsonPropertyName("access_token")]
+    public string? AccessToken { get; init; }
+
+    /// <summary>Gets the token type (typically <c>Bearer</c>).</summary>
+    [JsonPropertyName("token_type")]
+    public string? TokenType { get; init; }
+
+    /// <summary>Gets the lifetime in seconds of the access token.</summary>
+    [JsonPropertyName("expires_in")]
+    public long? ExpiresIn { get; init; }
+
+    /// <summary>Gets the refresh token, if issued.</summary>
+    [JsonPropertyName("refresh_token")]
+    public string? RefreshToken { get; init; }
+
+    /// <summary>Gets the OpenID Connect ID token, if issued.</summary>
+    [JsonPropertyName("id_token")]
+    public string? IdToken { get; init; }
+
+    /// <summary>Gets the granted scope, if the server returns it.</summary>
+    [JsonPropertyName("scope")]
+    public string? Scope { get; init; }
+}
diff --git a/src/Avalonia.Controls.WebView/OAuth2/Pkce.cs b/src/Avalonia.Controls.WebView/OAuth2/Pkce.cs
new file mode 100644
index 0000000..5dff95e
--- /dev/null
+++ b/src/Avalonia.Controls.WebView/OAuth2/Pkce.cs
@@ -0,0 +1,46 @@
+using System;
+using System.Security.Cryptography;
+using System.Text;
+
+namespace Avalonia.Controls.OAuth2;
+
+/// <summary>
+/// Proof Key for Code Exchange (PKCE) helpers per <see href="https://www.rfc-editor.org/rfc/rfc7636">RFC 7636</see>.
+/// </summary>
+public static class Pkce
+{
+    /// <summary>
+    /// Creates a new cryptographically random code verifier string (RFC 7636).
+    /// </summary>
+    /// <param name="size">Number of random bytes to encode (default 64). Must be 43-128.</param>
+    /// <returns>The code verifier string.</returns>
+    public static string CreateCodeVerifier(int size = 64)
+    {
+        if (size is < 43 or > 128)
+            throw new ArgumentOutOfRangeException(nameof(size), "Verifier length must be between 43 and 128.");
+
+        // Unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
+        var bytes = new byte[size];
+        RandomNumberGenerator.Fill(bytes);
+        return Base64UrlEncode(bytes);
+    }
+
+    /// <summary>
+    /// Computes the S256 code challenge (BASE64URL(SHA256(code_verifier))) for a verifier.
+    /// </summary>
+    /// <param name="codeVerifier">The PKCE code verifier.</param>
+    /// <returns>The code challenge string.</returns>
+    public static string CreateCodeChallengeS256(string codeVerifier)
+    {
+        var hash = SHA256.HashData(Encoding.ASCII.GetBytes(codeVerifier));
+        return Base64UrlEncode(hash);
+    }
+
+    private static string Base64UrlEncode(ReadOnlySpan<byte> data)
+    {
+        return Convert.ToBase64String(data)
+            .TrimEnd('=')
+            .Replace('+', '-')
+            .Replace('/', '_');
+    }
+}
diff --git a/src/Avalonia.Controls.WebView/README.md b/src/Avalonia.Controls.WebView/README.md
index d83c0b1..bee6cec 100644
--- a/src/Avalonia.Controls.WebView/README.md
+++ b/src/Avalonia.Controls.WebView/README.md
@@ -1,4 +1,4 @@
-# Avalonia WebView
+# Avalonia WebView
 
 The Avalonia WebView component provides native web browser functionality for your Avalonia applications. Unlike embedded WebView solutions that require bundling Chromium, this implementation leverages the platform's native web rendering capabilities, resulting in smaller application size and better performance.
 
@@ -41,3 +41,9 @@ Native web dialog that provides a way to display web content in a separate windo
 WebAuthenticationBroker is a utility class that facilitates OAuth and other web-based authentication flows by providing a secure way to handle web authentication in desktop applications.
 
 **Documentation**: https://docs.avaloniaui.net/accelerate/components/webview/webauthenticationbroker
+
+### OAuth 2.0 Authorization Server Metadata (RFC 8414)
+
+The `Avalonia.Controls.OAuth2` namespace provides discovery at `/.well-known/oauth-authorization-server`, PKCE (RFC 7636), building an authorization code request against `authorization_endpoint`, parsing the redirect, and exchanging the code at `token_endpoint`. Use it together with `WebAuthenticationBroker` when you want standards-based metadata instead of hand-built authorize URLs.
+
+**Sample**: `samples/Avalonia.Controls.WebView.Samples.Oidc`
diff --git a/tests/Avalonia.Controls.WebView.Tests/OAuth2Tests.cs b/tests/Avalonia.Controls.WebView.Tests/OAuth2Tests.cs
new file mode 100644
index 0000000..cc044ea
--- /dev/null
+++ b/tests/Avalonia.Controls.WebView.Tests/OAuth2Tests.cs
@@ -0,0 +1,99 @@
+using System;
+using Avalonia.Controls.OAuth2;
+using Xunit;
+
+namespace Avalonia.Controls.WebView.Tests;
+
+public class OAuth2Tests
+{
+    [Fact]
+    public void Creating_S256_code_challenge_should_match_RFC7636_appendix_B_vector()
+    {
+        const string verifier = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk";
+        var challenge = Pkce.CreateCodeChallengeS256(verifier);
+        Assert.Equal("E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", challenge);
+    }
+
+    [Fact]
+    public void Metadata_client_should_build_RFC8414_well_known_URL()
+    {
+        var url = AuthorizationServerMetadataClient.GetWellKnownMetadataUrl("https://example.com/tenant/");
+        Assert.Equal("https://example.com/tenant/.well-known/oauth-authorization-server", url);
+    }
+
+    [Fact]
+    public void Authorization_callback_parser_should_parse_code_and_validate_state()
+    {
+        var callback = new Uri("http://localhost/callback?code=abc&state=xyz");
+        var r = AuthorizationCallbackParser.Parse(callback, "xyz");
+        Assert.Equal("abc", r.AuthorizationCode);
+    }
+
+    [Fact]
+    public void Authorization_callback_parser_should_throw_when_state_mismatch()
+    {
+        var callback = new Uri("http://localhost/callback?code=abc&state=wrong");
+        Assert.Throws<InvalidOperationException>(() => AuthorizationCallbackParser.Parse(callback, "xyz"));
+    }
+
+    [Fact]
+    public void Authorization_code_pkce_session_should_throw_when_S256_not_supported()
+    {
+        var metadata = new AuthorizationServerMetadata
+        {
+            AuthorizationEndpoint = "https://id.example.com/authorize",
+            CodeChallengeMethodsSupported = new[] { "plain" },
+        };
+
+        Assert.Throws<InvalidOperationException>(() =>
+            AuthorizationCodePkceSession.Create(
+                metadata,
+                "client",
+                "http://localhost/cb",
+                "openid"));
+    }
+
+    [Fact]
+    public void Authorization_code_pkce_session_should_build_authorization_request_uri()
+    {
+        var metadata = new AuthorizationServerMetadata
+        {
+            AuthorizationEndpoint = "https://id.example.com/authorize",
+            CodeChallengeMethodsSupported = new[] { "S256" },
+        };
+
+        var session = AuthorizationCodePkceSession.Create(
+            metadata,
+            "my-client",
+            "http://localhost/cb",
+            "openid offline_access");
+
+        Assert.Equal("http://localhost/cb", session.RedirectUriString);
+        Assert.Contains("response_type=code", session.AuthorizationUri.Query, StringComparison.Ordinal);
+        Assert.Contains("code_challenge_method=S256", session.AuthorizationUri.Query, StringComparison.Ordinal);
+        Assert.Contains("client_id=my-client", session.AuthorizationUri.Query, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public void Authorization_code_pkce_session_should_preserve_redirect_uri_without_trailing_slash()
+    {
+        var metadata = new AuthorizationServerMetadata
+        {
+            AuthorizationEndpoint = "https://id.example.com/authorize",
+            CodeChallengeMethodsSupported = new[] { "S256" },
+        };
+
+        var session = AuthorizationCodePkceSession.Create(
+            metadata,
+            "id",
+            "http://localhost",
+            "openid");
+
+        Assert.Equal("http://localhost", session.RedirectUriString);
+        Assert.Contains("redirect_uri=http%3A%2F%2Flocalhost&", session.AuthorizationUri.Query, StringComparison.Ordinal);
+        Assert.DoesNotContain(
+            "redirect_uri=http%3A%2F%2Flocalhost%2F",
+            session.AuthorizationUri.Query,
+            StringComparison.Ordinal);
+    }
+}