ASP.NET Core Web API

Ajoutez l’authentification JWT d’Auth0 à une API Web ASP.NET Core avec des points de terminaison protégés

Ce Quickstart est actuellement en bêta. Nous aimerions beaucoup connaître votre avis!

Utiliser l’IA pour intégrer Auth0

Si vous utilisez un assistant IA de codage comme Claude Code, Cursor ou GitHub Copilot, vous pouvez ajouter automatiquement l’authentification Auth0 en quelques minutes à l’aide d’Agent Skills.

Installer :

npx skills add auth0/agent-skills --skill auth0

Demandez ensuite à votre assistant IA :

Add Auth0 JWT authentication to my ASP.NET Core Web API

Votre assistant IA créera automatiquement votre API Auth0, récupérera les informations d’identification, installera le SDK Auth0 ASP.NET Core Authentication API, configurera l’authentification JWT Bearer et implémentera des points de terminaison d’API protégés. Documentation complète sur Agent Skills →

Prérequis : Avant de commencer, assurez-vous d’avoir installé les éléments suivants :

• .NET 8.0 SDK ou une version ultérieure
• L’IDE de votre choix (Visual Studio 2022, VS Code ou Rider)

Compatibilité des versions de .NET : Ce Quickstart fonctionne avec .NET 8.0 et les versions ultérieures.

​

Pour commencer

Ce Quickstart montre comment ajouter l’authentification JWT d’Auth0 à une API Web ASP.NET Core. Vous allez créer une API sécurisée avec des points de terminaison protégés à l’aide du SDK d’API ASP.NET Core d’Auth0.

1. Créer un nouveau projet

   Créez un nouveau projet ASP.NET Core Web API pour ce Quickstart

   dotnet new webapi -n Auth0Api
   

   Ouvrir le projet

   cd Auth0Api
   
2. Installez le SDK Auth0

   dotnet add package Auth0.AspNetCore.Authentication.Api
   
3. Configurez votre API Auth0

   Ensuite, vous devez créer une nouvelle API sur votre tenant Auth0 et ajouter la configuration à votre projet.

   Vous pouvez effectuer cette opération automatiquement en exécutant une commande CLI ou le faire manuellement via le Dashboard :

   CLI

   Exécutez la commande shell suivante à la racine de votre projet pour créer une API Auth0 et mettre à jour votre fichier appsettings.json :

   Mac/Linux

   AUTH0_API_NAME="My ASP.NET Core API" && \
   AUTH0_API_IDENTIFIER="https://my-api" && \
   brew tap auth0/auth0-cli && \
   brew install auth0 && \
   auth0 login --no-input && \
   auth0 apis create -n "${AUTH0_API_NAME}" -i "${AUTH0_API_IDENTIFIER}" --offline-access --token-lifetime 86400 --signing-alg RS256 --json > auth0-api-details.json && \
   DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && \
   AUDIENCE=$(jq -r '.identifier' auth0-api-details.json) && \
   jq --arg domain "$DOMAIN" --arg audience "$AUDIENCE" \
     '.Auth0.Domain = $domain | .Auth0.Audience = $audience' \
     appsettings.json > appsettings.tmp.json && \
   mv appsettings.tmp.json appsettings.json && \
   rm auth0-api-details.json && \
   echo "✅ appsettings.json updated with your Auth0 API details:" && \
   cat appsettings.json
   

   Windows (PowerShell)

   $ApiName = "My ASP.NET Core API"
   $ApiIdentifier = "https://my-api"
   $latestRelease = Invoke-RestMethod -Uri "https://api.github.com/repos/auth0/auth0-cli/releases/latest"
   $latestVersion = $latestRelease.tag_name
   $version = $latestVersion -replace "^v"
   Invoke-WebRequest -Uri "https://github.com/auth0/auth0-cli/releases/download/${latestVersion}/auth0-cli_${version}_Windows_x86_64.zip" -OutFile ".\auth0.zip"
   Expand-Archive ".\auth0.zip" .\
   [System.Environment]::SetEnvironmentVariable('PATH', $Env:PATH + ";${pwd}")
   auth0 login --no-input
   auth0 apis create -n "$ApiName" -i "$ApiIdentifier" --offline-access --token-lifetime 86400 --signing-alg RS256 --json | Set-Content -Path auth0-api-details.json
   $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name
   $Audience = (Get-Content -Raw auth0-api-details.json | ConvertFrom-Json).identifier
   $Config = Get-Content -Raw appsettings.json | ConvertFrom-Json
   if (-not $Config.Auth0) { $Config | Add-Member -MemberType NoteProperty -Name Auth0 -Value @{} }
   $Config.Auth0.Domain = $Domain
   $Config.Auth0.Audience = $Audience
   $Config | ConvertTo-Json -Depth 10 | Set-Content appsettings.json
   Remove-Item auth0-api-details.json
   Write-Output "✅ appsettings.json updated with your Auth0 API details:"
   Get-Content appsettings.json
   

   Dashboard

   Avant de commencer, ajoutez la configuration d’Auth0 à votre fichier appsettings.json

   appsettings.json

   {
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft.AspNetCore": "Warning"
       }
     },
     "AllowedHosts": "*",
     "Auth0": {
       "Domain": "YOUR_AUTH0_DOMAIN",
       "Audience": "YOUR_AUTH0_API_IDENTIFIER"
     }
   }
   

   1. Accédez à Auth0 Dashboard → Applications → APIs
   2. Cliquez sur Create API
   3. Saisissez les détails de votre API :
      • Nom : My ASP.NET Core API
      • Identifiant : https://my-api (cela devient votre audience)
      • Signing Algorithm : RS256
   4. Cliquez sur Create
   5. Remplacez YOUR_AUTH0_DOMAIN dans appsettings.json par votre Domain de l’onglet Test (p. ex. your-tenant.auth0.com)
   6. Remplacez YOUR_AUTH0_API_IDENTIFIER dans appsettings.json par votre Identifiant (p. ex. https://my-api)

   Votre Domain ne doit pas inclure https:// — utilisez seulement le nom de domaine (p. ex. your-tenant.auth0.com).

   L’Audience (identifiant d’API) est un identifiant unique pour votre API et peut être n’importe quel URI valide. Il n’a pas besoin d’être une URL accessible publiquement.

4. Configurer l’authentification

   Remplacez l’intégralité du contenu de Program.cs par le code suivant :

   Program.cs

   using Auth0.AspNetCore.Authentication.Api;
   using Microsoft.AspNetCore.Authentication.JwtBearer;
   
   var builder = WebApplication.CreateBuilder(args);
   
   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();
   
   if (!app.Environment.IsDevelopment())
   {
       app.UseHttpsRedirection();
   }
   
   app.UseAuthentication();
   app.UseAuthorization();
   
   app.Run();
   
5. Créer des points de terminaison publics et protégés

   Ajoutez des points de terminaison pour tester l’authentification. Ajoutez le code suivant dans Program.cs avant app.Run() :

   Program.cs

   // Point de terminaison public - aucune authentification requise
   app.MapGet("/api/public", () => 
       Results.Ok(new { Message = "This endpoint is public" }))
       .WithName("GetPublic");
   
   // Point de terminaison protégé - authentification requise
   app.MapGet("/api/private", () => 
       Results.Ok(new { Message = "This endpoint requires authentication" }))
       .RequireAuthorization()
       .WithName("GetPrivate");
   
6. Lancez votre API

   dotnet run
   

   Votre API fonctionne maintenant à l’adresse https://localhost:7190 (ou une URL semblable - vérifiez la sortie de la console pour l’URL exacte).

Étape de vérification

Vous devriez maintenant disposer d’une API protégée par Auth0, pleinement fonctionnelle, sur votre localhost

---

​

Utilisation avancée

Appeler des API protégées

Testez vos points de terminaison protégés avec un jeton d’accès.

1. Obtenez un jeton d’accès auprès d’Auth0 à l’aide du flux Client Credentials :

curl --request POST \
  --url https://YOUR_DOMAIN/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","audience":"YOUR_AUDIENCE","grant_type":"client_credentials"}'

Pour obtenir YOUR_CLIENT_ID et YOUR_CLIENT_SECRET, créez une Machine to Machine Application dans le Auth0 Dashboard et autorisez-la pour votre API.

2. Testez le point de terminaison public (devrait renvoyer 200 OK) :

curl https://localhost:7190/api/public

3. Testez le point de terminaison protégé sans authentification (devrait renvoyer 401 Unauthorized) :

curl https://localhost:7190/api/private

4. Faites une requête au point de terminaison protégé avec le jeton :

curl https://localhost:7190/api/private \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Utiliser des points de terminaison basés sur des contrôleurs

Pour les API plus volumineuses, utilisez des contrôleurs plutôt que des points de terminaison d’API minimaux.

1. Ajoutez la prise en charge des contrôleurs :

Program.cs

builder.Services.AddControllers();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseHttpsRedirection();
}

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

app.MapControllers();

app.Run();

2. Créez un contrôleur :

Créez Controllers/MessagesController.cs :

Controllers/MessagesController.cs

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

namespace Auth0Api.Controllers;

[ApiController]
[Route("api/[controller]")]
public class MessagesController : ControllerBase
{
    [HttpGet]
    public IActionResult GetPublic()
    {
        return Ok(new { Message = "This endpoint is public" });
    }

    [Authorize]
    [HttpGet("private")]
    public IActionResult GetPrivate()
    {
        var userId = User.FindFirst("sub")?.Value;
        return Ok(new { Message = "This endpoint is protected", UserId = userId });
    }

    [Authorize(Policy = "read:messages")]
    [HttpGet("messages")]
    public IActionResult GetMessages()
    {
        return Ok(new { Messages = new[] { "Message 1", "Message 2" } });
    }
}

Protéger des routes avec une autorisation basée sur les scopes

Protégez les points de terminaison en fonction de scopes précis dans le jeton d’accès.

1. Définissez des scopes dans votre Auth0 API :

Dans le Auth0 Dashboard → APIs → Your API → Permissions, ajoutez des scopes :

• read:messages - Lire les messages
• write:messages - Écrire des messages

2. Configurez les politiques d’autorisation :

Program.cs

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("read:messages", policy =>
        policy.RequireClaim("scope", "read:messages"));
    
    options.AddPolicy("write:messages", policy =>
        policy.RequireClaim("scope", "write:messages"));
});

3. Appliquez les politiques aux points de terminaison :

app.MapGet("/api/messages", () => 
    Results.Ok(new { Messages = new[] { "Message 1", "Message 2" } }))
    .RequireAuthorization("read:messages");

app.MapPost("/api/messages", () => 
    Results.Created("/api/messages/1", new { Id = 1, Text = "New message" }))
    .RequireAuthorization("write:messages");

Lorsque vous demandez un jeton d’accès, incluez le scope requis :

curl --request POST \
  --url https://YOUR_DOMAIN/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","audience":"YOUR_AUDIENCE","grant_type":"client_credentials","scope":"read:messages write:messages"}'

Utiliser DPoP pour une sécurité renforcée

DPoP (Demonstration of Proof-of-Possession) lie les jetons d’accès à des clés cryptographiques, ce qui empêche le vol de jetons et les attaques par rejeu.

Activer la prise en charge de DPoP :

Program.cs

builder.Services.AddAuth0ApiAuthentication(options =>
{
    options.Domain = builder.Configuration["Auth0:Domain"];
    options.JwtBearerOptions = new JwtBearerOptions
    {
        Audience = builder.Configuration["Auth0:Audience"]
    };
}).WithDPoP();  // Activer DPoP avec les paramètres par défaut

Modes DPoP :

Accepter à la fois les jetons DPoP et Bearer (par défaut) :

using Auth0.AspNetCore.Authentication.Api.DPoP;

.WithDPoP(dpopOptions =>
{
    dpopOptions.Mode = DPoPModes.Allowed;
});

Accepter uniquement les jetons DPoP et rejeter les jetons Bearer :

using Auth0.AspNetCore.Authentication.Api.DPoP;

.WithDPoP(dpopOptions =>
{
    dpopOptions.Mode = DPoPModes.Required;
});

Configurer les paramètres de validation temporelle :

.WithDPoP(dpopOptions =>
{
    dpopOptions.Mode = DPoPModes.Allowed;
    dpopOptions.IatOffset = 300;  // Autoriser une preuve DPoP datant d’au plus 5 minutes
    dpopOptions.Leeway = 30;      // Tolérance de décalage d’horloge de 30 secondes
});

Pour en savoir plus sur DPoP, consultez la documentation DPoP d’Auth0.

Implémenter des politiques d’autorisation personnalisées

Créez des politiques d’autorisation réutilisables pour répondre à des exigences complexes.

1. Créer une exigence personnalisée :

Authorization/HasScopeRequirement.cs

using Microsoft.AspNetCore.Authorization;

namespace Auth0Api.Authorization;

public class HasScopeRequirement : IAuthorizationRequirement
{
    public string Scope { get; }
    public string Issuer { get; }

    public HasScopeRequirement(string scope, string issuer)
    {
        Scope = scope;
        Issuer = issuer;
    }
}

2. Créer un gestionnaire :

Authorization/HasScopeHandler.cs

using Microsoft.AspNetCore.Authorization;

namespace Auth0Api.Authorization;

public class HasScopeHandler : AuthorizationHandler<HasScopeRequirement>
{
    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext context,
        HasScopeRequirement requirement)
    {
        if (!context.User.HasClaim(c => c.Type == "scope" && c.Issuer == requirement.Issuer))
        {
            return Task.CompletedTask;
        }

        var scopes = context.User
            .FindFirst(c => c.Type == "scope" && c.Issuer == requirement.Issuer)?
            .Value.Split(' ');

        if (scopes?.Any(s => s == requirement.Scope) == true)
        {
            context.Succeed(requirement);
        }

        return Task.CompletedTask;
    }
}

3. Enregistrer et utiliser la politique :

Program.cs

using Auth0Api.Authorization;

var builder = WebApplication.CreateBuilder(args);

var domain = $"https://{builder.Configuration["Auth0:Domain"]}";

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

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("read:messages", policy =>
        policy.Requirements.Add(new HasScopeRequirement("read:messages", domain)));
});

builder.Services.AddSingleton<IAuthorizationHandler, HasScopeHandler>();

var app = builder.Build();
// ... reste de la configuration

Accéder aux informations sur l’utilisateur

Extrayez les renseignements sur l’utilisateur à partir du jeton d’authentification.

app.MapGet("/api/user-info", (HttpContext context) =>
{
    var userId = context.User.FindFirst("sub")?.Value;
    var email = context.User.FindFirst("email")?.Value;
    var name = context.User.FindFirst("name")?.Value;
    var scopes = context.User.FindAll("scope")
        .SelectMany(c => c.Value.Split(' '))
        .Distinct();

    return Results.Ok(new
    {
        UserId = userId,
        Email = email,
        Name = name,
        Scopes = scopes
    });
})
.RequireAuthorization();

Validation personnalisée du jeton

Personnalisez les paramètres de validation du jeton JWT en fonction de vos besoins particuliers.

Program.cs

using Microsoft.IdentityModel.Tokens;
using System.Security.Claims;

builder.Services.AddAuth0ApiAuthentication(options =>
{
    options.Domain = builder.Configuration["Auth0:Domain"];
    options.JwtBearerOptions = new JwtBearerOptions
    {
        Audience = builder.Configuration["Auth0:Audience"],
        
        TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuerSigningKey = true,
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ClockSkew = TimeSpan.FromMinutes(5),
            NameClaimType = ClaimTypes.NameIdentifier,
            RoleClaimType = "https://my-app.com/roles"
        },
        
        Events = new JwtBearerEvents
        {
            OnAuthenticationFailed = context =>
            {
                Console.WriteLine($"Authentication failed: {context.Exception.Message}");
                return Task.CompletedTask;
            },
            
            OnTokenValidated = context =>
            {
                var userId = context.Principal?.FindFirst("sub")?.Value;
                Console.WriteLine($"Token validated for user: {userId}");
                return Task.CompletedTask;
            }
        }
    };
});

---

​

Ressources supplémentaires

Documentation du SDK

Documentation complète du SDK et référence de l’API

Guide de migration

Migration à partir de l’authentification JWT Bearer

Exemples de code

Exemples de code complets et modèles

Documentation DPoP

En savoir plus sur la sécurité par preuve de possession

Meilleures pratiques relatives aux jetons

Meilleures pratiques de sécurité pour les jetons

Forum de la communauté

Obtenez de l’aide auprès de la communauté Auth0

---

​

Problèmes courants

401 Non autorisé - audience invalide

Problème : La validation du token échoue en raison d’une erreur de non-correspondance de l’audience.

Solution : Assurez-vous que Audience dans appsettings.json correspond exactement à l’identifier de votre Auth0 API. La claim audience du token doit correspondre à cette valeur.

{
  "Auth0": {
    "Audience": "https://my-api"  // Doit correspondre à l’identifier de l’Auth0 API
  }
}

401 Non autorisé - émetteur invalide

Problème : La validation du token échoue en raison d’une erreur liée à l’émetteur.

Solution : Vérifiez que votre Domain est correct et n’inclut pas https://. La library construit automatiquement l’autorité au format https://{Domain}.

{
  "Auth0": {
    "Domain": "your-tenant.auth0.com"  // Sans https://
  }
}

Valeurs de configuration introuvables

Problème : ArgumentNullException: Value cannot be null. (Parameter 'Domain') ou un message semblable.

Solution : Assurez-vous que appsettings.json contient la section Auth0 avec les valeurs Domain et Audience. Vérifiez également que la configuration est lue correctement :

builder.Services.AddAuth0ApiAuthentication(options =>
{
    options.Domain = builder.Configuration["Auth0:Domain"]
        ?? throw new InvalidOperationException("Auth0:Domain is required");
    options.JwtBearerOptions = new JwtBearerOptions
    {
        Audience = builder.Configuration["Auth0:Audience"]
            ?? throw new InvalidOperationException("Auth0:Audience is required")
    };
});

Erreurs de certificat HTTPS en développement

Problème : Des erreurs de certificat SSL/TLS se produisent lors de l’exécution en local.

Solution : Faites confiance au certificat de développement :

dotnet dev-certs https --trust

Ou générez un nouveau certificat :

dotnet dev-certs https --clean
dotnet dev-certs https --trust

Problèmes d’ordre du middleware

Problème : L’authentification ne fonctionne pas malgré une configuration correcte.

Solution : Assurez-vous que le middleware est dans le bon ordre. UseAuthentication() doit venir avant UseAuthorization() :

app.UseAuthentication();  // Doit être avant UseAuthorization
app.UseAuthorization();
app.MapControllers();

Les scopes ne fonctionnent pas dans les politiques d’autorisation

Problème : Les politiques d’autorisation basées sur des scopes échouent systématiquement.

Solution : Assurez-vous que votre jeton d’accès inclut les scopes requis. Lorsque vous demandez un token, précisez les scopes :

curl --request POST \
  --url https://YOUR_DOMAIN/oauth/token \
  --data '{"client_id":"...","client_secret":"...","audience":"...","grant_type":"client_credentials","scope":"read:messages write:messages"}'

Vérifiez aussi que les scopes sont définis dans les paramètres de votre Auth0 API (Dashboard → APIs → Your API → Permissions).

---

​

Application d’exemple

Une application d’exemple complète qui présente toutes les fonctionnalités est disponible dans le dépôt du SDK.

Application de démonstration

Comprend des points de terminaison publics et protégés, la prise en charge de DPoP, l’intégration de Swagger UI et une collection Postman

Clonez et exécutez :

git clone https://github.com/auth0/aspnetcore-api.git
cd aspnetcore-api/Auth0.AspNetCore.Authentication.Api.Playground
# Mettez à jour appsettings.json avec votre configuration Auth0
dotnet run