Intégration Auth0 ASP.NET Core Web API

Protégez les endpoints Web API ASP.NET Core avec la validation des tokens d'accès JWT en utilisant Auth0.AspNetCore.Authentication.Api.

Prérequis

• .NET 8.0 SDK ou version supérieure
• Auth0 API configurée (pas une Application - doit être une ressource API)
• Si vous n'avez pas encore configuré Auth0, utilisez d'abord la skill auth0-quickstart

Quand NE PAS utiliser

• Applications web rendues côté serveur - Utilisez l'authentification basée sur session (Auth0.AspNetCore.Authentication) pour les apps MVC/Razor Pages
• Single Page Applications - Utilisez auth0-react, auth0-vue ou auth0-angular pour l'authentification côté client
• Applications mobiles - Utilisez auth0-react-native pour React Native/Expo
• Blazor WebAssembly - Nécessite une approche d'authentification différente (OIDC côté client)

Workflow de démarrage rapide

1. Installer le SDK

dotnet add package Auth0.AspNetCore.Authentication.Api

2. Créer une API Auth0

Vous avez besoin d'une API (pas une Application) dans Auth0.

ARRÊT — demandez à l'utilisateur avant de continuer.

Posez exactement cette question et attendez sa réponse avant de faire autre chose :

"Comment voulez-vous créer la ressource API Auth0 ?

1. Automatisé — Je vais exécuter des scripts CLI Auth0 qui créent la ressource et écrivent les valeurs exactes dans votre appsettings.json automatiquement.
2. Manuel — Vous créez l'API vous-même dans le Auth0 Dashboard (ou via auth0 apis create) et me fournissez le Domain et l'Audience.

Laquelle préférez-vous ? (1 = Automatisé / 2 = Manuel)"

Ne procédez à AUCUNE étape de configuration tant que l'utilisateur n'a pas répondu. Ne réglez PAS sur manuel par défaut.

Si l'utilisateur a choisi Automatisé, suivez le Guide de configuration pour les scripts CLI complets. Le chemin automatisé écrit appsettings.json pour vous — passez l'étape 3 ci-dessous et allez directement à l'étape 4.

Si l'utilisateur a choisi Manuel, suivez le Guide de configuration (section Configuration manuelle) pour les instructions complètes incluant User Secrets et les options de variables d'environnement. Puis continuez avec l'étape 3 ci-dessous.

Référence rapide pour la création d'API manuelle :

# Utilisation du CLI Auth0
auth0 apis create \
  --name "My ASP.NET Core API" \
  --identifier https://my-api.example.com

Ou créez manuellement dans Auth0 Dashboard → Applications → APIs

3. Configurer appsettings.json

{
  "Auth0": {
    "Domain": "your-tenant.auth0.com",
    "Audience": "https://my-api.example.com"
  }
}

Important : Domain ne doit PAS inclure https://. La bibliothèque construit l'URL d'autorité automatiquement.

4. Configurer Program.cs

var builder = WebApplication.CreateBuilder(args);

// Enregistrez la validation JWT Auth0
builder.Services.AddAuth0ApiAuthentication(options =>
{
    options.Domain = builder.Configuration["Auth0:Domain"];
    options.JwtBearerOptions = new JwtBearerOptions
    {
        Audience = builder.Configuration["Auth0:Audience"]
    };
});

builder.Services.AddAuthorization();

var app = builder.Build();

// L'ordre des middlewares est important : authentification avant autorisation
app.UseAuthentication();
app.UseAuthorization();

// Ajoutez vos endpoints ici (voir étape 5)
app.MapGet("/api/public", () => Results.Ok(new { message = "Public" }));

app.Run();

5. Protéger les endpoints

Minimal API :

// Endpoint public - pas d'authentification
app.MapGet("/api/public", () => Results.Ok(new { message = "Hello from a public endpoint!" }));

// Endpoint protégé - nécessite un JWT valide
app.MapGet("/api/private", (HttpContext ctx) =>
{
    var userId = ctx.User.FindFirst("sub")?.Value;
    return Results.Ok(new { message = "Hello from a protected endpoint!", userId });
}).RequireAuthorization();

Basé sur contrôleurs :

[ApiController]
[Route("api")]
public class MessagesController : ControllerBase
{
    [HttpGet("public")]
    public IActionResult Public() =>
        Ok(new { message = "Hello from a public endpoint!" });

    [Authorize]
    [HttpGet("private")]
    public IActionResult Private() =>
        Ok(new { message = "Hello from a protected endpoint!", userId = User.FindFirst("sub")?.Value });
}

6. Tester l'API

Testez l'endpoint public :

curl http://localhost:5000/api/public

Testez l'endpoint protégé (nécessite un token d'accès) :

curl http://localhost:5000/api/private \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Récupérez un token de test via le flux Client Credentials ou Auth0 Dashboard → APIs → onglet Test.

Erreurs courantes

Autorisation basée sur les scopes

Voir le Guide d'intégration pour définir et appliquer les politiques de scope.

Support DPoP

Liaison de token proof-of-possession intégrée par RFC 9449. Voir le Guide d'intégration pour la configuration.

Skills associées

• auth0-quickstart - Configuration Auth0 de base
• auth0-mfa - Ajouter l'authentification multifacteur

Référence rapide

Options de configuration :

• options.Domain - Domaine du tenant Auth0, pas de préfixe https:// (requis)
• options.JwtBearerOptions.Audience - API Identifier des paramètres API Auth0 (requis)
• options.JwtBearerOptions - Accès complet aux options JWT Bearer Microsoft sous-jacentes

Revendications utilisateur :

• ctx.User.FindFirst("sub")?.Value - ID utilisateur (subject)
• ctx.User.FindFirst("scope")?.Value - Scopes séparés par des espaces
• ctx.User.FindAll("scope") - Toutes les revendications de scope

Cas d'usage courants :

• Protéger les routes Minimal API → .RequireAuthorization() (voir étape 5)
• Protéger les actions de contrôleurs → attribut [Authorize] (voir étape 5)
• Application des scopes → Guide d'intégration
• Liaison de token DPoP → Guide d'intégration
• Configuration JWT Bearer avancée → Référence API

Documentation détaillée

• Guide de configuration - Configuration CLI Auth0, configuration de l'environnement
• Guide d'intégration - Politiques de scope, DPoP, modèles de contrôleur, gestion des erreurs
• Référence API - Options de configuration complètes et méthodes d'extension

Références

• Auth0 ASP.NET Core Web API Quickstart
• Dépôt GitHub du SDK
• Documentation API
• Guide des Access Tokens