docs: added docs for the new dotnet example (#11541)

2026-11-14 09:55:12 +00:00 · 2026-02-23 07:55:18 +00:00
parent 71fab2e574
commit 6150a61216
6 changed files with 137 additions and 2 deletions
@@ -0,0 +1,78 @@
+---
+title: ASP.NET Core
+sidebar_label: ASP.NET Core
+framework_url: https://learn.microsoft.com/aspnet/core/
+auth_library: "Microsoft.AspNetCore.Authentication.OpenIdConnect"
+auth_library_url: https://learn.microsoft.com/aspnet/core/security/authentication/openid-connect
+example_repo: https://github.com/zitadel/example-auth-dotnet
+auth_flow: pkce
+status: stable
+---
+
+## Overview
+
+[ASP.NET Core](https://learn.microsoft.com/aspnet/core/) is a production-ready framework for building web applications. This example integrates **Zitadel** with the built-in **OpenID Connect handler** using the **Authorization Code Flow + PKCE** to authenticate users securely and manage sessions.
+
+#### Auth library
+
+This example uses **[Microsoft.AspNetCore.Authentication.OpenIdConnect](https://learn.microsoft.com/aspnet/core/security/authentication/openid-connect)**. The middleware handles the PKCE dance, exchanges authorization codes for tokens, keeps tokens available on the request, and plugs into the standard ASP.NET Core authentication/authorization pipeline.
+
+---
+
+## What this example demonstrates
+
+- Public landing page with “Sign in with Zitadel”.
+- PKCE login handled by the ASP.NET Core OIDC middleware.
+- Route protection via the auth/authorization middleware; profile page renders OIDC claims.
+- Cookie-based session management with configurable idle timeout.
+- Federated logout that clears the local session and redirects through Zitadel’s RP-initiated logout.
+
+---
+
+## Getting started
+
+### Prerequisites
+
+- .NET SDK 8 or later
+
+### Account setup
+
+Create a Web application in Zitadel configured for Authorization Code + PKCE, then set:
+
+> **Redirect URIs:** `http://localhost:3000/auth/callback`  
+> **Post Logout Redirect URIs:** `http://localhost:3000/auth/logout/callback`
+
+These values must match the sample configuration.
+
+### Run the example
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/zitadel/example-auth-dotnet.git
+   cd example-auth-dotnet
+   ```
+2. Copy `.env.example` to `.env` and fill in your values:
+   ```dotenv
+   PORT=3000
+   SESSION_DURATION=3600
+   ZITADEL_DOMAIN="https://your-zitadel-domain"
+   ZITADEL_CLIENT_ID="your-zitadel-application-client-id"
+   ZITADEL_CLIENT_SECRET="your-randomly-generated-client-secret"
+   ZITADEL_POST_LOGOUT_URL="http://localhost:3000/auth/logout/callback"
+   ```
+3. Start the dev server (restores dependencies automatically):
+   ```bash
+   make start
+   ```
+
+The app will be available at `http://localhost:3000`.
+
+---
+
+## Learn more and resources
+
+* [PKCE concept](https://oauth.net/2/pkce/)
+* [ASP.NET Core OIDC handler](https://learn.microsoft.com/aspnet/core/security/authentication/openid-connect)
+* [Zitadel OIDC guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
+* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
+* [Example repository](https://github.com/zitadel/example-auth-dotnet)