> ## Documentation Index
> Fetch the complete documentation index at: https://translations.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
export const HowToSchema = () => ;
Ce Quickstart est actuellement en **bêta**. Nous aimerions beaucoup connaître votre avis!
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](https://agentskills.io/home).
**Installer :**
```bash theme={null}
npx skills add auth0/agent-skills --skill auth0
```
**Demandez ensuite à votre assistant IA :**
```text theme={null}
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 →](/docs/fr-ca/quickstart/agent-skills)
**Prérequis :** Avant de commencer, assurez-vous d’avoir installé les éléments suivants :
* **[.NET 8.0 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)** 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.
Créez un nouveau projet ASP.NET Core Web API pour ce Quickstart
```bash theme={null}
dotnet new webapi -n Auth0Api
```
Ouvrir le projet
```bash theme={null}
cd Auth0Api
```
```bash theme={null}
dotnet add package Auth0.AspNetCore.Authentication.Api
```
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 :
Exécutez la commande shell suivante à la racine de votre projet pour créer une API Auth0 et mettre à jour votre fichier `appsettings.json` :
```bash theme={null}
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
```
```powershell theme={null}
$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
```
Avant de commencer, ajoutez la configuration d’Auth0 à votre fichier `appsettings.json`
```json appsettings.json theme={null}
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
},
"AllowedHosts": "*",
"Auth0": {
"Domain": "YOUR_AUTH0_DOMAIN",
"Audience": "YOUR_AUTH0_API_IDENTIFIER"
}
}
```
1. Accédez à [Auth0 Dashboard](https://manage.auth0.com) → **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.
Remplacez l’intégralité du contenu de `Program.cs` par le code suivant :
```csharp Program.cs lines theme={null}
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();
```
Ajoutez des points de terminaison pour tester l’authentification. Ajoutez le code suivant dans `Program.cs` avant `app.Run()` :
```csharp Program.cs theme={null}
// 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");
```
```bash theme={null}
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](https://localhost:7190/)
***
## Utilisation avancée
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 :
```bash theme={null}
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](https://manage.auth0.com/#/applications) et autorisez-la pour votre API.
**2. Testez le point de terminaison public** (devrait renvoyer 200 OK) :
```bash theme={null}
curl https://localhost:7190/api/public
```
**3. Testez le point de terminaison protégé sans authentification** (devrait renvoyer 401 Unauthorized) :
```bash theme={null}
curl https://localhost:7190/api/private
```
**4. Faites une requête au point de terminaison protégé avec le jeton :**
```bash theme={null}
curl https://localhost:7190/api/private \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```
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 :**
```csharp Program.cs theme={null}
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` :
```csharp Controllers/MessagesController.cs theme={null}
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é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](https://manage.auth0.com) → APIs → Your API → Permissions, ajoutez des scopes :
* `read:messages` - Lire les messages
* `write:messages` - Écrire des messages
**2. Configurez les politiques d'autorisation :**
```csharp Program.cs theme={null}
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 :**
```csharp theme={null}
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 :
```bash theme={null}
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"}'
```
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 :**
```csharp Program.cs theme={null}
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) :
```csharp theme={null}
using Auth0.AspNetCore.Authentication.Api.DPoP;
.WithDPoP(dpopOptions =>
{
dpopOptions.Mode = DPoPModes.Allowed;
});
```
Accepter uniquement les jetons DPoP et rejeter les jetons Bearer :
```csharp theme={null}
using Auth0.AspNetCore.Authentication.Api.DPoP;
.WithDPoP(dpopOptions =>
{
dpopOptions.Mode = DPoPModes.Required;
});
```
Configurer les paramètres de validation temporelle :
```csharp theme={null}
.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](https://auth0.com/docs/secure/sender-constraining/demonstrating-proof-of-possession-dpop).
Créez des politiques d’autorisation réutilisables pour répondre à des exigences complexes.
**1. Créer une exigence personnalisée :**
```csharp Authorization/HasScopeRequirement.cs theme={null}
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 :**
```csharp Authorization/HasScopeHandler.cs theme={null}
using Microsoft.AspNetCore.Authorization;
namespace Auth0Api.Authorization;
public class HasScopeHandler : AuthorizationHandler
{
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 :**
```csharp Program.cs theme={null}
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();
var app = builder.Build();
// ... reste de la configuration
```
Extrayez les renseignements sur l’utilisateur à partir du jeton d’authentification.
```csharp theme={null}
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();
```
Personnalisez les paramètres de validation du jeton JWT en fonction de vos besoins particuliers.
```csharp Program.cs theme={null}
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 complète du SDK et référence de l’API
Migration à partir de l’authentification JWT Bearer
Exemples de code complets et modèles
En savoir plus sur la sécurité par preuve de possession
Meilleures pratiques de sécurité pour les jetons
Obtenez de l’aide auprès de la communauté Auth0
***
## Problèmes courants
**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.
```json theme={null}
{
"Auth0": {
"Audience": "https://my-api" // Doit correspondre à l’identifier de l’Auth0 API
}
}
```
**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}`.
```json theme={null}
{
"Auth0": {
"Domain": "your-tenant.auth0.com" // Sans https://
}
}
```
**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 :
```csharp theme={null}
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")
};
});
```
**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 :
```bash theme={null}
dotnet dev-certs https --trust
```
Ou générez un nouveau certificat :
```bash theme={null}
dotnet dev-certs https --clean
dotnet dev-certs https --trust
```
**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()` :
```csharp theme={null}
app.UseAuthentication(); // Doit être avant UseAuthorization
app.UseAuthorization();
app.MapControllers();
```
**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 :
```bash theme={null}
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.
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 :
```bash theme={null}
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
```