Auth0 Aspnetcore Authentication Skill

Auth0 ASP.NET Core Web App Integration

Add login, logout, and user profile to an ASP.NET Core MVC, Razor Pages, or Blazor Server application using Auth0.AspNetCore.Authentication.

---

Prerequisites

• ASP.NET Core application (.NET 8 or higher)
• Auth0 Regular Web Application configured (not an API - must be an Application)
• If you don't have Auth0 set up yet, use the auth0-quickstart skill first

When NOT to Use

• ASP.NET Core Web APIs with JWT Bearer validation - Use auth0-aspnetcore-api for JWT-protected REST APIs
• Blazor WebAssembly - Requires OIDC client-side auth; see the Auth0 Blazor WebAssembly quickstart
• Single Page Applications - Use auth0-react, auth0-vue, or auth0-angular for client-side auth
• Next.js applications - Use auth0-nextjs which handles both client and server
• Python web apps - Use auth0-flask for Flask or see the Django quickstart

---

Quick Start Workflow

1. Install SDK

dotnet add package Auth0.AspNetCore.Authentication

2. Configure Credentials

Add Auth0 settings to appsettings.json:

{
  "Auth0": {
    "Domain": "your-tenant.us.auth0.com",
    "ClientId": "your_client_id",
    "ClientSecret": "your_client_secret"
  }
}

For local development, keep secrets out of source control - use dotnet user-secrets to avoid committing ClientSecret:

dotnet user-secrets set "Auth0:Domain" "your-tenant.us.auth0.com"
dotnet user-secrets set "Auth0:ClientId" "your_client_id"
dotnet user-secrets set "Auth0:ClientSecret" "your_client_secret"

Auth0:Domain is your tenant domain (without https://). Auth0:ClientId and Auth0:ClientSecret come from your Auth0 Application settings.

3. Configure Auth0 Dashboard

In your Auth0 Application settings:

• Allowed Callback URLs: http://localhost:5000/callback
• Allowed Logout URLs: http://localhost:5000
• Allowed Web Origins: http://localhost:5000

4. Register Auth0 in Program.cs

using Auth0.AspNetCore.Authentication;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuth0WebAppAuthentication(options =>
{
    options.Domain = builder.Configuration["Auth0:Domain"];
    options.ClientId = builder.Configuration["Auth0:ClientId"];
    options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];
});

builder.Services.AddControllersWithViews();

var app = builder.Build();

// Standard middleware...
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();

app.UseAuthentication();    // Must come before UseAuthorization
app.UseAuthorization();     // Critical: order matters

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

Critical: UseAuthentication() must come before UseAuthorization(). Reversing these causes silent auth failures where protected routes are never challenged.

5. Create AccountController

using Auth0.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

public class AccountController : Controller
{
    public async Task Login(string returnUrl = "/")
    {
        var authenticationProperties = new LoginAuthenticationPropertiesBuilder()
            .WithRedirectUri(returnUrl)
            .Build();

        await HttpContext.ChallengeAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
    }

    [Authorize]
    public async Task Logout()
    {
        var authenticationProperties = new LogoutAuthenticationPropertiesBuilder()
            .WithRedirectUri(Url.Action("Index", "Home"))
            .Build();

        await HttpContext.SignOutAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
        await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
    }

    [Authorize]
    public IActionResult Profile()
    {
        return View();
    }
}

Login does not need [Authorize] - it is the entry point for unauthenticated users. Logout requires [Authorize] to ensure the sign-out only fires for authenticated sessions. Always call both `SignOutAsync` methods - signing out of only the Auth0 scheme leaves a local cookie; signing out of only the cookie scheme skips the Auth0 logout URL.

6. Create Profile View

Create Views/Account/Profile.cshtml:

@{
    ViewData["Title"] = "User Profile";
}

<div class="row">
    <div class="col-md-2">
        <img src="@User.FindFirst(c => c.Type == "picture")?.Value"
             alt="Profile picture" class="img-fluid rounded-circle" />
    </div>
    <div class="col-md-10">
        <h3>@User.Identity.Name</h3>
        <p><strong>Email:</strong>
           @User.FindFirst(c => c.Type == System.Security.Claims.ClaimTypes.Email)?.Value</p>
        <p><strong>User ID:</strong>
           @User.FindFirst(c => c.Type == System.Security.Claims.ClaimTypes.NameIdentifier)?.Value</p>
    </div>
</div>

<h4 class="mt-4">Claims</h4>
<table class="table">
    <thead><tr><th>Claim Type</th><th>Claim Value</th></tr></thead>
    <tbody>
        @foreach (var claim in User.Claims)
        {
            <tr><td>@claim.Type</td><td>@claim.Value</td></tr>
        }
    </tbody>
</table>

7. Update Navigation (_Layout.cshtml)

Add login/logout/profile links to your nav bar inside _Layout.cshtml:

@if (User.Identity.IsAuthenticated)
{
    <li class="nav-item">
        <a class="nav-link text-dark" asp-controller="Account" asp-action="Profile">@User.Identity.Name</a>
    </li>
    <li class="nav-item">
        <a class="nav-link text-dark" asp-controller="Account" asp-action="Logout">Logout</a>
    </li>
}
else
{
    <li class="nav-item">
        <a class="nav-link text-dark" asp-controller="Account" asp-action="Login">Login</a>
    </li>
}

8. Test the App

dotnet run

Visit http://localhost:5000 and click Login to start the Auth0 login flow.

---

Blazor Server Variant

For Blazor Server apps, use Razor Pages as auth endpoints - Blazor components cannot perform the HTTP redirects required by OAuth challenges.

Additional Program.cs Setup

using Auth0.AspNetCore.Authentication;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuth0WebAppAuthentication(options =>
{
    options.Domain = builder.Configuration["Auth0:Domain"];
    options.ClientId = builder.Configuration["Auth0:ClientId"];
    options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];
});

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

builder.Services.AddCascadingAuthenticationState();  // Required for Blazor auth state
builder.Services.AddRazorPages();                     // Required for auth endpoints

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.MapRazorPages();
app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.Run();

Login Razor Page (Pages/Login.cshtml.cs)

using Auth0.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;

public class LoginModel : PageModel
{
    public async Task OnGet(string returnUrl = "/")
    {
        var authenticationProperties = new LoginAuthenticationPropertiesBuilder()
            .WithRedirectUri(returnUrl)
            .Build();

        await HttpContext.ChallengeAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
    }
}

Logout Razor Page (Pages/Logout.cshtml.cs)

using Auth0.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;

public class LogoutModel : PageModel
{
    public async Task OnGet()
    {
        var authenticationProperties = new LogoutAuthenticationPropertiesBuilder()
            .WithRedirectUri(Url.Content("~/"))
            .Build();

        await HttpContext.SignOutAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
        await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
    }
}

Profile Component (Components/Pages/Profile.razor)

@page "/profile"
@attribute [Authorize]
@using System.Security.Claims

<h1>Profile</h1>

<AuthorizeView>
    <Authorized>
        <div class="row">
            <div class="col-2">
                <img src="@context.User.FindFirst("picture")?.Value"
                     alt="Profile" class="img-fluid rounded-circle" />
            </div>
            <div class="col-10">
                <h3>@context.User.Identity?.Name</h3>
                <p><strong>Email:</strong> @context.User.FindFirst(ClaimTypes.Email)?.Value</p>
            </div>
        </div>

        <h4 class="mt-4">Claims</h4>
        <table class="table">
            <thead><tr><th>Type</th><th>Value</th></tr></thead>
            <tbody>
                @foreach (var claim in context.User.Claims)
                {
                    <tr><td>@claim.Type</td><td>@claim.Value</td></tr>
                }
            </tbody>
        </table>
    </Authorized>
</AuthorizeView>

Update MainLayout.razor Navigation

@using Microsoft.AspNetCore.Components.Authorization

<AuthorizeView>
    <Authorized>
        <a href="/profile">@context.User.Identity?.Name</a>
        <a href="/Logout">Logout</a>
    </Authorized>
    <NotAuthorized>
        <a href="/Login">Login</a>
    </NotAuthorized>
</AuthorizeView>

Routes.razor

Wrap the Router in CascadingAuthenticationState to enable authorization throughout the component tree:

<CascadingAuthenticationState>
    <Router AppAssembly="typeof(Program).Assembly">
        <Found Context="routeData">
            <AuthorizeRouteView RouteData="routeData" DefaultLayout="typeof(Layout.MainLayout)" />
            <FocusOnNavigate RouteData="routeData" Selector="h1" />
        </Found>
    </Router>
</CascadingAuthenticationState>

---

Razor Pages Variant

For Razor Pages apps (without Blazor), use AddRazorPages() instead of AddControllersWithViews() in Program.cs. Auth endpoints are the same Login/Logout page models shown in the Blazor Server section. Replace navigation in _Layout.cshtml using the same User.Identity.IsAuthenticated check shown in the MVC section.

---

Common Mistakes

---

Key SDK Methods

---

Related Skills

• auth0-aspnetcore-api - For ASP.NET Core Web APIs with JWT Bearer token validation
• auth0-express - For server-rendered Express web apps with login/logout sessions
• auth0-flask - For Flask web applications with session-based auth

---

Quick Reference

SDK registration:

builder.Services.AddAuth0WebAppAuthentication(options =>
{
    options.Domain = builder.Configuration["Auth0:Domain"];        // required
    options.ClientId = builder.Configuration["Auth0:ClientId"];    // required
    options.ClientSecret = builder.Configuration["Auth0:ClientSecret"]; // required
});

Login action:

var props = new LoginAuthenticationPropertiesBuilder().WithRedirectUri(returnUrl).Build();
await HttpContext.ChallengeAsync(Auth0Constants.AuthenticationScheme, props);

Logout action (always call both):

var props = new LogoutAuthenticationPropertiesBuilder().WithRedirectUri(Url.Action("Index", "Home")).Build();
await HttpContext.SignOutAsync(Auth0Constants.AuthenticationScheme, props);
await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);

Route protection:

[Authorize]
public IActionResult Profile() { return View(); }

appsettings.json configuration keys:

• Auth0:Domain - Auth0 tenant domain (e.g., tenant.us.auth0.com)
• Auth0:ClientId - Application client ID
• Auth0:ClientSecret - Application client secret (use user-secrets in development)

---

Detailed Documentation

• [Setup Guide](references/setup.md) - Automated setup scripts, credential configuration, Auth0 CLI usage
• [Integration Guide](references/integration.md) - Protected routes, calling APIs, Blazor patterns, error handling
• [API Reference](references/api.md) - Complete SDK configuration, builder options, claims reference

---

References

• Auth0.AspNetCore.Authentication on NuGet
• Auth0 ASP.NET Core MVC Quickstart
• Auth0 ASP.NET Core Blazor Server Quickstart
• ASP.NET Core Documentation

Auth0 ASP.NET Core Authentication API Reference

Complete configuration and API reference for ASP.NET Core web application authentication.

---

AddAuth0WebAppAuthentication Configuration

Complete Configuration Options

using Auth0.AspNetCore.Authentication;

builder.Services.AddAuth0WebAppAuthentication(options =>
{
    options.Domain = builder.Configuration["Auth0:Domain"];         // required: tenant domain (without https://)
    options.ClientId = builder.Configuration["Auth0:ClientId"];     // required: app client ID
    options.ClientSecret = builder.Configuration["Auth0:ClientSecret"]; // required: app client secret
    options.CallbackPath = "/callback";                             // optional: defaults to /callback
    options.Backchannel = null;                                     // optional: custom HttpClient
    options.MaxAge = TimeSpan.FromDays(1);                          // optional: max auth age
    options.LoginParameters = new Dictionary<string, string>        // optional: extra OIDC params
    {
        { "audience", "https://your-api-identifier" }
    };
    options.Scope = "openid profile email";                         // optional: scopes to request
    options.ResponseType = "code";                                  // optional: default is "code"
    options.UsePkce = true;                                         // optional: default is true
    options.SkipCookieMiddleware = false;                           // optional: skip automatic cookie middleware
})
.WithAccessToken(tokenOptions =>
{
    tokenOptions.Audience = "https://your-api-identifier";          // required for API calls
    tokenOptions.UseRefreshTokens = true;                           // optional: enable refresh tokens
});

---

LoginAuthenticationPropertiesBuilder

Fluent builder for constructing authentication properties used in the login challenge.

var authenticationProperties = new LoginAuthenticationPropertiesBuilder()
    .WithRedirectUri("/dashboard")                 // redirect after login
    .WithParameter("screen_hint", "signup")        // Auth0 Universal Login hint
    .WithParameter("connection", "google-oauth2")  // force specific connection
    .WithParameter("ui_locales", "es")             // locale
    .Build();

await HttpContext.ChallengeAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);

---

LogoutAuthenticationPropertiesBuilder

Fluent builder for constructing authentication properties used in the logout flow.

var authenticationProperties = new LogoutAuthenticationPropertiesBuilder()
    .WithRedirectUri(Url.Action("Index", "Home"))  // post-logout redirect
    .Build();

await HttpContext.SignOutAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);

Always call both `SignOutAsync` methods. Calling only Auth0Constants.AuthenticationScheme signs out of Auth0 but leaves the local cookie intact. Calling only CookieAuthenticationDefaults.AuthenticationScheme clears the cookie but skips the Auth0 logout endpoint.

---

WithAccessToken Options

Configure token storage for API calls via the .WithAccessToken() extension:

builder.Services.AddAuth0WebAppAuthentication(options =>
{
    options.Domain = builder.Configuration["Auth0:Domain"];
    options.ClientId = builder.Configuration["Auth0:ClientId"];
    options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];
})
.WithAccessToken(tokenOptions =>
{
    tokenOptions.Audience = builder.Configuration["Auth0:Audience"]; // required for API calls
    tokenOptions.UseRefreshTokens = true;                            // enable refresh token rotation
    tokenOptions.Events = new Auth0WebAppWithAccessTokenEvents       // optional event hooks
    {
        OnMissingRefreshToken = async (context) =>
        {
            await context.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
            context.Response.Redirect("/login");
        }
    };
});

Retrieve the access token in controllers:

var accessToken = await HttpContext.GetTokenAsync("access_token");

---

Claims Reference

After login, user claims are available via User.FindFirst() or HttpContext.User.FindFirst().

Note: Standard claims like email are mapped to ClaimTypes.Email by ASP.NET Core's OIDC middleware. Custom claims added via Auth0 Rules or Actions are available by their exact type string.

---

Cookie Configuration

The SDK uses ASP.NET Core's cookie authentication middleware by default. Cookie behavior is configurable:

builder.Services.AddAuth0WebAppAuthentication(options =>
{
    options.Domain = builder.Configuration["Auth0:Domain"];
    options.ClientId = builder.Configuration["Auth0:ClientId"];
    options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];
    options.SkipCookieMiddleware = true; // take control of cookie middleware yourself
});

// Configure cookie manually when SkipCookieMiddleware = true
builder.Services.AddAuthentication()
    .AddCookie(options =>
    {
        options.Cookie.SecurePolicy = CookieSecurePolicy.Always;     // HTTPS only in production
        options.Cookie.HttpOnly = true;                               // no JS access
        options.Cookie.SameSite = SameSiteMode.Lax;                  // CSRF protection
        options.SlidingExpiration = true;
        options.ExpireTimeSpan = TimeSpan.FromHours(1);
    });

---

Middleware Configuration

var app = builder.Build();

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();

app.UseAuthentication();    // MUST come before UseAuthorization
app.UseAuthorization();     // Checks [Authorize] attributes

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

Middleware order is critical: 1. UseRouting() - before auth middleware so route information is available 2. UseAuthentication() - reads the cookie and sets HttpContext.User 3. UseAuthorization() - enforces [Authorize] policies using the populated HttpContext.User

---

Auth0Constants

Auth0Constants.AuthenticationScheme  // = "Auth0"

Use this constant instead of the string "Auth0" to avoid typos.

---

Testing

Local Testing

1. Configure appsettings.json or user-secrets with your Auth0 credentials 2. Start your app: dotnet run 3. Visit http://localhost:5000/Account/Login 4. Complete the Auth0 Universal Login flow 5. Verify redirect back to app and claims accessible on profile page 6. Click logout and verify both cookies are cleared

---

References

• Auth0.AspNetCore.Authentication on NuGet
• Auth0.AspNetCore.Authentication GitHub
• ASP.NET Core Authentication Documentation

---

Next Steps

• Integration Guide
• Setup Guide
• Main Skill

Auth0 ASP.NET Core Integration Patterns

Server-side authentication patterns for ASP.NET Core MVC, Razor Pages, and Blazor Server.

---

Protected Routes

Using [Authorize] Attribute on Controller Actions

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

public class DashboardController : Controller
{
    [Authorize]
    public IActionResult Index()
    {
        var userName = User.Identity.Name;
        return View("Index", userName);
    }
}

Using [Authorize] on an Entire Controller

[Authorize]
public class AdminController : Controller
{
    public IActionResult Dashboard()
    {
        return View();
    }

    public IActionResult Settings()
    {
        return View();
    }
}

Manual Check in Action

public IActionResult Dashboard()
{
    if (!User.Identity.IsAuthenticated)
    {
        return RedirectToAction("Login", "Account");
    }
    return View();
}

Policy-Based Authorization

// Register policy in Program.cs
builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("RequireEmail", policy =>
        policy.RequireClaim(System.Security.Claims.ClaimTypes.Email));
});

// Apply to action
[Authorize(Policy = "RequireEmail")]
public IActionResult AdminOnly()
{
    return View();
}

Razor Pages Protection

// Program.cs - protect all Razor Pages under /Admin
builder.Services.AddRazorPages(options =>
{
    options.Conventions.AuthorizeFolder("/Admin");
    options.Conventions.AllowAnonymousToPage("/Admin/Login");
});

---

Calling External APIs

Get Access Token in Controller

using Microsoft.AspNetCore.Authentication;

public class ApiController : Controller
{
    private readonly IHttpClientFactory _httpClientFactory;

    public ApiController(IHttpClientFactory httpClientFactory)
    {
        _httpClientFactory = httpClientFactory;
    }

    [Authorize]
    public async Task<IActionResult> CallApi()
    {
        var accessToken = await HttpContext.GetTokenAsync("access_token");
        if (string.IsNullOrEmpty(accessToken))
        {
            return Unauthorized("No access token available");
        }

        var client = _httpClientFactory.CreateClient();
        client.DefaultRequestHeaders.Authorization =
            new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", accessToken);

        var response = await client.GetAsync("https://your-api.com/data");
        var content = await response.Content.ReadAsStringAsync();

        return Ok(content);
    }
}

Configure Audience for API Calls

Update Program.cs to request an access token for a specific audience:

builder.Services.AddAuth0WebAppAuthentication(options =>
{
    options.Domain = builder.Configuration["Auth0:Domain"];
    options.ClientId = builder.Configuration["Auth0:ClientId"];
    options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];
})
.WithAccessToken(options =>
{
    options.Audience = builder.Configuration["Auth0:Audience"]; // e.g., https://your-api-identifier
    options.UseRefreshTokens = true;
});

Add the audience to appsettings.json:

{
  "Auth0": {
    "Domain": "your-tenant.us.auth0.com",
    "ClientId": "your_client_id",
    "Audience": "https://your-api-identifier"
  }
}

Store ClientSecret in user-secrets (dotnet user-secrets set "Auth0:ClientSecret" "your_client_secret") or environment variables — never commit secrets to source control.

---

Custom Login Options

Force a Specific Connection

public async Task LoginWithGoogle(string returnUrl = "/")
{
    var authenticationProperties = new LoginAuthenticationPropertiesBuilder()
        .WithRedirectUri(returnUrl)
        .WithParameter("connection", "google-oauth2")
        .Build();

    await HttpContext.ChallengeAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
}

Prompt for Signup

public async Task Signup(string returnUrl = "/")
{
    var authenticationProperties = new LoginAuthenticationPropertiesBuilder()
        .WithRedirectUri(returnUrl)
        .WithParameter("screen_hint", "signup")
        .Build();

    await HttpContext.ChallengeAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
}

Custom Logout Return URL

[Authorize]
public async Task LogoutToGoodbye()
{
    var authenticationProperties = new LogoutAuthenticationPropertiesBuilder()
        .WithRedirectUri(Url.Action("Goodbye", "Home"))
        .Build();

    await HttpContext.SignOutAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
    await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
}

---

Accessing User Information

In Controllers

[Authorize]
public IActionResult Profile()
{
    var name = User.Identity.Name;
    var email = User.FindFirst(System.Security.Claims.ClaimTypes.Email)?.Value;
    var picture = User.FindFirst(c => c.Type == "picture")?.Value;
    var userId = User.FindFirst(System.Security.Claims.ClaimTypes.NameIdentifier)?.Value;

    var model = new ProfileViewModel
    {
        Name = name,
        Email = email,
        Picture = picture,
        UserId = userId,
        Claims = User.Claims.ToList()
    };

    return View(model);
}

In Views (Razor)

@if (User.Identity.IsAuthenticated)
{
    <p>Welcome, @User.Identity.Name!</p>
    <img src='@User.FindFirst(c => c.Type == "picture")?.Value' alt="Profile" />
}

In Blazor Components

@using Microsoft.AspNetCore.Components.Authorization
@inject AuthenticationStateProvider AuthStateProvider

<AuthorizeView>
    <Authorized>
        <p>Welcome, @context.User.Identity?.Name!</p>
        <img src='@context.User.FindFirst("picture")?.Value' alt="Profile" />
    </Authorized>
    <NotAuthorized>
        <p>Please <a href="/Login">log in</a>.</p>
    </NotAuthorized>
</AuthorizeView>

---

Injecting User into All Views

Use a base controller or view imports to make the user available everywhere:

// BaseController.cs
public abstract class BaseController : Controller
{
    protected string CurrentUserName => User.Identity.Name ?? "Guest";
    protected bool IsAuthenticated => User.Identity.IsAuthenticated;
}

// DashboardController.cs
public class DashboardController : BaseController
{
    [Authorize]
    public IActionResult Index()
    {
        ViewBag.UserName = CurrentUserName;
        return View();
    }
}

Or use ViewData in _ViewStart.cshtml via a filter:

// AuthUserFilter.cs - inject user into all views automatically
public class AuthUserFilter : IActionFilter
{
    public void OnActionExecuting(ActionExecutingContext context)
    {
        if (context.Controller is Controller controller)
        {
            controller.ViewData["CurrentUser"] = controller.User.Identity.Name;
        }
    }

    public void OnActionExecuted(ActionExecutedContext context) { }
}

// Program.cs
builder.Services.AddControllersWithViews(options =>
{
    options.Filters.Add<AuthUserFilter>();
});

---

Error Handling

Global Unauthorized Redirect

// Program.cs - redirect 401/403 to login page
app.UseStatusCodePages(async statusCodeContext =>
{
    var response = statusCodeContext.HttpContext.Response;
    if (response.StatusCode == 401)
    {
        response.Redirect("/Account/Login");
    }
    else if (response.StatusCode == 403)
    {
        response.Redirect("/Home/AccessDenied");
    }
});

Handling Token Expiry (with .WithAccessToken)

.WithAccessToken(options =>
{
    options.Audience = builder.Configuration["Auth0:Audience"];
    options.UseRefreshTokens = true;
    options.Events = new Auth0WebAppWithAccessTokenEvents
    {
        OnMissingRefreshToken = async (context) =>
        {
            // Refresh token missing - force re-login
            await context.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
            context.Response.Redirect("/Account/Login");
        }
    };
});

---

Blazor Server: Auth in Components

AuthorizeView Component

<AuthorizeView>
    <Authorized>
        <!-- Only shown to authenticated users -->
        <p>Welcome, @context.User.Identity?.Name!</p>
    </Authorized>
    <NotAuthorized>
        <!-- Only shown to unauthenticated users -->
        <a href="/Login">Please log in</a>
    </NotAuthorized>
    <Authorizing>
        <!-- Shown while auth state is loading -->
        <p>Loading...</p>
    </Authorizing>
</AuthorizeView>

Programmatic Auth State in Blazor

@inject AuthenticationStateProvider AuthStateProvider

@code {
    private bool isAuthenticated;
    private string userName = "";

    protected override async Task OnInitializedAsync()
    {
        var authState = await AuthStateProvider.GetAuthenticationStateAsync();
        var user = authState.User;
        isAuthenticated = user.Identity?.IsAuthenticated ?? false;
        userName = user.Identity?.Name ?? "";
    }
}

---

Common Issues

---

Next Steps

• API Reference
• Setup Guide
• Main Skill

Auth0 ASP.NET Core Setup Guide

Setup instructions for ASP.NET Core MVC, Razor Pages, and Blazor Server applications.

---

Quick Setup (Automated)

Below automates the setup, except for the ClientSecret. Inform the user that they have to fill in the value for ClientSecret themselves.

Never read the contents of `appsettings.json`, `appsettings.Development.json`, or user-secrets at any point during setup. These files may contain sensitive secrets that should not be exposed in the LLM context. If you determine you need to read the file for any reason, ask the user for explicit permission before doing so — do not proceed until the user confirms.

Before running any part of this setup that writes to a config file, you MUST ask the user for explicit confirmation. Follow the steps below precisely.

Step 1: Check for existing config files and confirm with user

Before writing credentials, check which config files exist:

test -f appsettings.Development.json && echo "DEV_SETTINGS_EXISTS" || echo "DEV_SETTINGS_NOT_FOUND"
test -f appsettings.json && echo "SETTINGS_EXISTS" || echo "SETTINGS_NOT_FOUND"

Then ask the user for explicit confirmation before proceeding — do not continue until the user confirms:

• If appsettings.Development.json exists, ask:
• Question: "An appsettings.Development.json file already exists and may contain settings unrelated to Auth0. This setup will append Auth0 credentials to it without modifying existing content. Do you want to proceed?"
• Options: "Yes, append to existing appsettings.Development.json" / "No, I'll update it manually"

• If appsettings.Development.json does not exist but appsettings.json exists, ask:
• Question: "An appsettings.json file already exists. This setup will add the Auth0 section to it. Would you prefer to use dotnet user-secrets to keep the ClientSecret out of source control?"
• Options: "Yes, use user-secrets" / "Yes, write to appsettings.json" / "No, I'll configure it manually"

• If neither exists, ask:
• Question: "This setup will create an appsettings.json file containing Auth0 settings (Domain, ClientId) and a placeholder for ClientSecret. Do you want to proceed?"
• Options: "Yes, create appsettings.json" / "No, I'll configure it manually"

Do not proceed with writing to any config file unless the user selects the confirmation option.

Step 2: Run automated setup (only after confirmation)

#!/bin/bash

# Install Auth0 CLI
if ! command -v auth0 &> /dev/null; then
  [[ "$OSTYPE" == "darwin"* ]] && brew install auth0/auth0-cli/auth0 || \
  curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh -s -- -b /usr/local/bin
fi

# Login
auth0 login 2>/dev/null || auth0 login

# Create/select app
auth0 apps list
read -p "Enter app ID (or Enter to create): " APP_ID

if [ -z "$APP_ID" ]; then
  APP_ID=$(auth0 apps create --name "${PWD##*/}-aspnetcore" --type regular \
    --callbacks "http://localhost:5000/callback,https://localhost:7000/callback" \
    --logout-urls "http://localhost:5000,https://localhost:7000" \
    --metadata "created_by=agent_skills" \
    --json-compact | jq -r '.client_id')
fi

# Get credentials
DOMAIN=$(auth0 apps show "$APP_ID" --json-compact | jq -r '.domain')
CLIENT_ID=$(auth0 apps show "$APP_ID" --json-compact | jq -r '.client_id')

echo "Auth0 Domain: $DOMAIN"
echo "Auth0 Client ID: $CLIENT_ID"
echo ""
echo "Add these to your appsettings.json or use dotnet user-secrets:"
echo ""
echo "  dotnet user-secrets set \"Auth0:Domain\" \"$DOMAIN\""
echo "  dotnet user-secrets set \"Auth0:ClientId\" \"$CLIENT_ID\""
echo "  dotnet user-secrets set \"Auth0:ClientSecret\" \"YOUR_CLIENT_SECRET\""

After the script runs, remind the user to: 1. Replace YOUR_CLIENT_SECRET with the actual client secret from Auth0. 2. For production, use environment variables or a secrets manager — never commit the client secret to source control. 3. Verify the HTTPS port in Properties/launchSettings.json and update the Auth0 callback/logout URLs if needed (ASP.NET Core assigns random HTTPS ports in the 7000-7300 range).

---

Manual Setup

Install Package

dotnet add package Auth0.AspNetCore.Authentication

Configure appsettings.json

Add the Auth0 section:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Auth0": {
    "Domain": "your-tenant.us.auth0.com",
    "ClientId": "your-client-id",
    "ClientSecret": "your-client-secret"
  }
}

For local development, use dotnet user-secrets to keep the client secret out of source control:

dotnet user-secrets init
dotnet user-secrets set "Auth0:Domain" "your-tenant.us.auth0.com"
dotnet user-secrets set "Auth0:ClientId" "your-client-id"
dotnet user-secrets set "Auth0:ClientSecret" "your-client-secret"

User secrets override appsettings.json in the Development environment. In production, use environment variables:

export Auth0__Domain="your-tenant.us.auth0.com"
export Auth0__ClientId="your-client-id"
export Auth0__ClientSecret="your-client-secret"

Note: Environment variable names use double underscores (__) to represent the : separator in .NET configuration keys.

Get Auth0 Credentials

CLI: auth0 apps show <app-id> --reveal-secrets

Dashboard: Create a Regular Web Application, then copy Domain, Client ID, and Client Secret from the Settings tab.

Configure Auth0 Dashboard

In your Auth0 Application settings:

• Allowed Callback URLs: http://localhost:5000/callback, https://localhost:{HTTPS_PORT}/callback
• Allowed Logout URLs: http://localhost:5000, https://localhost:{HTTPS_PORT}
• Allowed Web Origins: http://localhost:5000, https://localhost:{HTTPS_PORT}

Check Properties/launchSettings.json for your project's actual HTTPS port (ASP.NET Core assigns a random port in the 7000-7300 range).

Application type must be Regular Web Application (not SPA or Native).

---

Troubleshooting

"IDX20803: Unable to obtain configuration" error: Verify Auth0:Domain is the bare domain (e.g., your-tenant.us.auth0.com) without https://. The SDK prepends the protocol automatically.

"Callback URL mismatch" error: The Allowed Callback URLs in Auth0 Dashboard must exactly match your app's callback URL. Check for trailing slashes or http vs https mismatches.

Client secret required: ASP.NET Core apps use Regular Web Application type — ensure the app was created as regular, not SPA or Native. SPA apps do not have client secrets.

Middleware order error (auth not working): Ensure app.UseAuthentication() is called before app.UseAuthorization() in Program.cs.

User-secrets not loading: User secrets only load in the Development environment (ASPNETCORE_ENVIRONMENT=Development). Verify the environment variable is set correctly.

SignOut not clearing session: Ensure both SignOutAsync(Auth0Constants.AuthenticationScheme) and SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme) are called in the Logout action.

---

Next Steps

• Integration Guide
• API Reference
• Main Skill