Comment utiliser Identity pour sécuriser un back-end d’API web pour les applications monopages

ASP.NET Core Identity fournit des API qui gèrent l’authentification, l’autorisation et la gestion des identity. Les API permettent de sécuriser les points de terminaison d’un back-end d’API web avec une authentification basée sur les cookie. Une option basée sur les jetons est disponible pour les clients qui ne peuvent pas utiliser de cookies. Toutefois, il est essentiel de garantir la sécurité des jetons avec cette solution. Nous vous recommandons d’utiliser des cookies pour les applications basées sur un navigateur, car, par défaut, le navigateur les gère automatiquement sans les exposer à JavaScript.

Cet article explique comment utiliser Identity pour sécuriser un back-end d’API web pour les SPA telles que les applications Angular, React et Vue. Les mêmes API back-end peuvent être utilisées pour sécuriser les applications Blazor WebAssembly.

Prérequis

Les étapes décrites dans cet article ajoutent l’authentification et l’autorisation à une application API web ASP.NET Core qui :

• N’est pas déjà configurée pour l’authentification.
• Cible net8.0 ou une version ultérieure.
• Peut être une API minimale ou une API basée sur un contrôleur.

Certaines des instructions de test de cet article utilisent l’interface utilisateur Swagger incluse dans le modèle de projet. L’interface utilisateur Swagger n’est pas nécessaire pour utiliser Identity avec un back-end d’API web.

Installer les packages NuGet

Installez les packages NuGet suivants :

• Microsoft.AspNetCore.Identity.EntityFrameworkCore - Permet à Identity d’utiliser Entity Framework Core (EF Core).
• Elle permet à EF Core d’utiliser une base de données, telle que l’un des packages suivants :
  • Microsoft.EntityFrameworkCore.SqlServer ou
  • Microsoft.EntityFrameworkCore.Sqlite ou
  • Microsoft.EntityFrameworkCore.InMemory.

Pour commencer rapidement, utilisez la base de données en mémoire.

Remplacez la base de données par SQLite ou SQL Server ultérieurement pour enregistrer les données utilisateur entre les sessions lors du test ou de l’utilisation en production. Cela introduit une certaine complexité par rapport à la base de données en mémoire, car la base de données doit être crée via des migrations, comme illustré dans le tutoriel de prise en mainEF Core.

Installez ces packages à l’aide du gestionnaire de package NuGet dans Visual Studio ou de la commande CLI dotnet add package.

Créer un IdentityDbContext

Ajoutez une classe nommée ApplicationDbContext qui hérite de IdentityDbContext<TUser> :

using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;

public class ApplicationDbContext : IdentityDbContext<IdentityUser>
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) :
        base(options)
    { }
}

Le code présenté fournit un constructeur spécial qui permet de configurer la base de données pour différents environnements.

Ajoutez une ou plusieurs des directives using suivantes si nécessaire lors de l’ajout du code indiqué dans ces étapes.

using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;

Configurer le contexte EF Core

Comme indiqué précédemment, la manière la plus simple de commencer consiste à utiliser la base de données en mémoire. Avec la base de données en mémoire, chaque exécution commence par une nouvelle base de données et il n’est pas nécessaire d’utiliser des migrations. Après l’appel à WebApplication.CreateBuilder(args), ajoutez le code suivant pour configurer Identity pour utiliser une base de données en mémoire :

builder.Services.AddDbContext<ApplicationDbContext>(
    options => options.UseInMemoryDatabase("AppDb"));

Pour enregistrer les données utilisateur entre les sessions lors du test ou de l’utilisation en production, remplacez la base de données par SQLite ou SQL Server ultérieurement.

Ajouter des services Identity au conteneur

Après l’appel à WebApplication.CreateBuilder(args), appelez AddAuthorization pour ajouter des services au conteneur d’injection de dépendances (DI) :

builder.Services.AddAuthorization();

Activer les API Identity

Après l’appel à WebApplication.CreateBuilder(args), appelez AddIdentityApiEndpoints<TUser>(IServiceCollection) et AddEntityFrameworkStores<TContext>(IdentityBuilder).

builder.Services.AddIdentityApiEndpoints<IdentityUser>()
    .AddEntityFrameworkStores<ApplicationDbContext>();

Par défaut, les cookies et les jetons propriétaires sont tous deux activés. Les cookies et les jetons sont émis lors de la connexion si le paramètre de la chaîne de requête de useCookies dans le point de terminaison de la connexion est true.

Mapper des itinéraires Identity

Après l’appel à builder.Build(), appelez MapIdentityApi<TUser>(IEndpointRouteBuilder) pour mapper les points de terminaison Identity :

app.MapIdentityApi<IdentityUser>();

Sécuriser les points de terminaison sélectionnés

Pour sécuriser un point de terminaison, utilisez la méthode d’extension RequireAuthorization sur l’appel Map{Method} qui définit l’itinéraire. Par exemple :

app.MapGet("/weatherforecast", (HttpContext httpContext) =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = summaries[Random.Shared.Next(summaries.Length)]
        })
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi()
.RequireAuthorization();

La méthode RequireAuthorization peut également être utilisée pour :

• Sécuriser les points de terminaison de l’interface utilisateur Swagger, comme illustré dans l’exemple suivant :

  app.MapSwagger().RequireAuthorization();
  

• Sécuriser avec une revendication ou une autorisation spécifique, comme indiqué dans l’exemple suivant :

  .RequireAuthorization("Admin");
  

Dans un projet d'API Web basé sur un contrôleur, sécurisez les points de terminaison en appliquant l'attribut [Authorize] à un contrôleur ou à une action.

Tester l’API

Un moyen rapide de tester l’authentification consiste à utiliser la base de données en mémoire et l’interface utilisateur Swagger incluse dans le modèle de projet. Les étapes suivantes montrent comment tester l’API avec l’interface utilisateur Swagger. Assurez-vous que les points de terminaison de l’interface utilisateur Swagger ne sont pas sécurisés.

Tenter d’accéder à un point de terminaison sécurisé

• Exécutez l’application et accédez à l’interface utilisateur Swagger.
• Développez un point de terminaison sécurisé, tel que /weatherforecast dans un projet créé par le modèle d’API web.
• Sélectionnez Essayer.
• Sélectionnez Exécuter. La réponse est 401 - not authorized.

Tester l’inscription

• Développez /register et sélectionnez Essayer.

• Dans la sectionParamètres de l’interface utilisateur, un exemple de corps de la demande s’affiche :

  {
    "email": "string",
    "password": "string"
  }
  

• Remplacez « string » par une adresse e-mail et un mot de passe valides, puis sélectionnez Exécuter.

  Pour respecter les règles de validation de mot de passe par défaut, le mot de passe doit comporter au moins six caractères et contenir au moins l’un des caractères suivants :

  • Lettre majuscule
  • Lettre minuscule
  • Un chiffre numérique
  • Caractère non-alphanumérique

  Si vous entrez une adresse e-mail invalide ou un mot de passe incorrect, le résultat inclut les erreurs de validation. Voici un exemple de corps de réponse avec des erreurs de validation :

  {
    "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
      "PasswordTooShort": [
        "Passwords must be at least 6 characters."
      ],
      "PasswordRequiresNonAlphanumeric": [
        "Passwords must have at least one non alphanumeric character."
      ],
      "PasswordRequiresDigit": [
        "Passwords must have at least one digit ('0'-'9')."
      ],
      "PasswordRequiresLower": [
        "Passwords must have at least one lowercase ('a'-'z')."
      ]
    }
  }
  

  Les erreurs sont retournées au format ProblemDetails afin que le client puisse les analyser et afficher les erreurs de validation en fonction des besoins.

  Une inscription réussie entraîne une réponse 200 - OK.

Tester la connexion

• Développez /login et sélectionnez Essayer. L’exemple de corps de la demande montre deux paramètres supplémentaires :

  {
    "email": "string",
    "password": "string",
    "twoFactorCode": "string",
    "twoFactorRecoveryCode": "string"
  }
  

  Les propriétés JSON supplémentaires ne sont pas nécessaires pour cet exemple et peuvent être supprimées. Affectez la valeur useCookies à true.

• Remplacez « string » par l’adresse e-mail et le mot de passe que vous avez utilisés pour vous inscrire, puis sélectionnez Exécuter.

  Une connexion réussie entraîne une réponse 200 - OK avec un cookie en en-tête de réponse.

Retester le point de terminaison sécurisé

Après une connexion réussie, réexécutez le point de terminaison sécurisé. L’authentification cookie est automatiquement envoyée avec la demande et le point de terminaison est autorisé. L’authentification basée sur les Cookie est intégrée en toute sécurité dans le navigateur et « fonctionne simplement ».

Test avec des clients non-navigateurs

Certains clients web peuvent ne pas inclure de cookies dans l’en-tête par défaut :

• Si vous utilisez un outil pour tester les API, vous devrez peut-être activer les cookies dans les paramètres.

• L’API JavaScript fetch n’inclut pas les cookies par défaut. Activez-les en définissant credentials sur la valeur include dans les options.

• Un HttpClient s’exécuant dans une application Blazor WebAssembly a besoin que le HttpRequestMessage inclue des informations d’identification, comme suit :

  request.SetBrowserRequestCredential(BrowserRequestCredentials.Include);
  

Utiliser l’authentification basée sur un jeton

Nous vous recommandons d’utiliser des cookies pour les applications basées sur un navigateur, car, par défaut, le navigateur les gère automatiquement sans les exposer à JavaScript.

Un jeton personnalisé (privé pour la plateforme ASP.NET Core identity) est émis et peut être utilisé pour authentifier les requêtes suivantes. Le jeton est transmis dans l’en-tête Authorization en tant que jeton du porteur. Un jeton d’actualisation est également fourni. Ce jeton permet à l’application de demander un nouveau jeton lorsque l’ancien expire sans forcer l’utilisateur à se reconnecter.

Les jetons ne sont pas des jetons Web JSON standard (JWT). L’utilisation de jetons personnalisés est intentionnelle, car l’API intégrée Identity est destinée principalement aux scénarios simples. L’option de jeton n’est pas destinée à être un fournisseur de services d’identity ou un serveur de jetons complet, mais plutôt une alternative à l’option cookie pour les clients qui ne peuvent pas utiliser de cookies.

Pour utiliser l’authentification basée sur les jetons, affectez la valeur false au paramètre de chaîne de requête useCookies lors de l’appel au point de terminaison /login. Les jetons utilisent le schéma d’authentification du porteur. À l’aide du jeton retourné par l’appel à /login, les appels suivants aux points de terminaison protégés doivent ajouter l’en-tête Authorization: Bearer <token> où <token> est le jeton d’accès. Pour plus d’informations, consultez Utilisation du point de terminaison POST /login plus loin dans cet article.

Se déconnecter

Pour permettre à l’utilisateur de se déconnecter, définissez un point de terminaison /logout comme dans l’exemple suivant :

app.MapPost("/logout", async (SignInManager<IdentityUser> signInManager,
    [FromBody] object empty) =>
{
    if (empty != null)
    {
        await signInManager.SignOutAsync();
        return Results.Ok();
    }
    return Results.Unauthorized();
})
.WithOpenApi()
.RequireAuthorization();

Fournissez un objet JSON ({}) vide dans le corps de la demande lors de l’appel à ce point de terminaison. Le code suivant est un exemple d’appel au point de terminaison de déconnexion :

public signOut() {
  return this.http.post('/logout', {}, {
    withCredentials: true,
    observe: 'response',
    responseType: 'text'

Les points de terminaison MapIdentityApi<TUser>

L’appel à MapIdentityApi<TUser> ajoute les points de terminaison suivants à l’application :

• POST /register
• POST /login
• POST /refresh
• GET /confirmEmail
• POST /resendConfirmationEmail
• POST /forgotPassword
• POST /resetPassword
• POST /manage/2fa
• GET /manage/info
• POST /manage/info

Utiliser le point de terminaison POST /register

Le corps de la requête doit avoir des propriétés Email et Password :

{
  "email": "string",
  "password": "string",
}

Pour plus d’informations, consultez l’article suivant :

• Tester l’inscription plus haut dans cet article.
• RegisterRequest.

Utiliser le point de terminaison POST /login

Dans le corps de la requête, Email et Password sont obligatoires. Si l’authentification à deux facteurs (2FA) est activée, TwoFactorCode ou TwoFactorRecoveryCode est requis. Si 2FA n’est pas activée, omettez twoFactorCode et twoFactorRecoveryCode. Pour plus d’informations, consultez Utiliser le point de terminaison POST /manage/2fa plus loin dans cet article.

Voici un exemple de corps de requête avec 2FA non activée :

{
  "email": "string",
  "password": "string"
}

Voici des exemples de corps de requête avec 2FA activée :

• {
    "email": "string",
    "password": "string",
    "twoFactorCode": "string",
  }
  

• {
    "email": "string",
    "password": "string",
    "twoFactorRecoveryCode": "string"
  }
  

Le point de terminaison attend un paramètre de chaîne de requête :

• useCookies : définir sur true pour l’authentification basée sur les cookies. Définir sur false ou omettre pour l’authentification basée sur les jetons.

Pour plus d’informations sur l’authentification basée sur les cookies, consultez Tester la connexion plus haut dans cet article.

Authentification basée sur un jeton

Si useCookies est false ou omis, l’authentification basée sur les jetons est activée. Le corps de la réponse comprend les propriétés suivantes :

{
  "tokenType": "string",
  "accessToken": "string",
  "expiresIn": 0,
  "refreshToken": "string"
}

Pour plus d’informations sur ces propriétés, consultez AccessTokenResponse.

Placez le jeton d’accès dans un en-tête pour effectuer des requêtes authentifiées, comme illustré dans l’exemple suivant.

Authorization: Bearer {access token}

Lorsque le jeton d’accès est sur le point d’expirer, appelez le point de terminaison /refresh.

Utiliser le point de terminaison POST /refresh

Pour une utilisation uniquement avec l’authentification basée sur les jetons. Obtient un nouveau jeton d’accès sans forcer l’utilisateur à se reconnecter. Appelez ce point de terminaison lorsque le jeton d’accès est sur le point d’expirer.

Le corps de la requête contient uniquement le RefreshToken. Voici un exemple de corps de requête :

{
  "refreshToken": "string"
}

Si l’appel réussit, le corps de la réponse est un nouveau AccessTokenResponse, comme illustré dans l’exemple suivant :

{
  "tokenType": "string",
  "accessToken": "string",
  "expiresIn": 0,
  "refreshToken": "string"
}

Utiliser le point de terminaison GET /confirmEmail

Si Identity est configuré pour la confirmation par e-mail, un appel réussi au point de terminaison /register entraîne l’envoi d’un e-mail contenant un lien vers le point de terminaison /confirmEmail. Le lien contient les paramètres de chaîne de requête suivants :

• userId
• code
• changedEmail : inclus uniquement si l’utilisateur a changé l’adresse e-mail lors de l’inscription.

Identity fournit le texte par défaut de l’e-mail de confirmation. Par défaut, l’objet de l’e-mail est « Confirmez votre e-mail » et le corps de l’e-mail ressemble à l’exemple suivant :

 Please confirm your account by <a href='https://contoso.com/confirmEmail?userId={user ID}&code={generated code}&changedEmail={new email address}'>clicking here</a>.

Si la propriété RequireConfirmedEmail a la valeur true, l’utilisateur ne peut pas se connecter tant qu’il n’a pas confirmé l’adresse e-mail en cliquant sur le lien dans l’e-mail. Le point de terminaison /confirmEmail :

• Confirme l’adresse e-mail et permet à l’utilisateur de se connecter.
• Retourne le texte « Merci d’avoir confirmé votre e-mail » dans le corps de la réponse.

Pour configurer Identity pour la confirmation par e-mail, ajoutez du code dans Program.cs afin d’affecter la valeur true à RequireConfirmedEmail et ajoutez une classe qui implémente IEmailSender dans le conteneur d’injection de dépendances. Par exemple :

builder.Services.Configure<IdentityOptions>(options =>
{
    options.SignIn.RequireConfirmedEmail = true;
});

builder.Services.AddTransient<IEmailSender, EmailSender>();

Pour plus d’informations, consultez Confirmation de compte et récupération de mot de passe dans ASP.NET Core.

Identity fournit le texte par défaut des autres e-mails qui doivent également être envoyés, comme pour l’authentification 2FA et la réinitialisation de mot de passe. Pour personnaliser ces e-mails, fournissez une implémentation personnalisée de l’interface IEmailSender. Dans l’exemple précédent, EmailSender est une classe qui implémente IEmailSender. Pour plus d’informations, notamment un exemple de classe qui implémente IEmailSender, consultez Confirmation de compte et récupération de mot de passe dans ASP.NET Core.

Utiliser le point de terminaison POST /resendConfirmationEmail

Envoie un e-mail uniquement si l’adresse est valide pour un utilisateur inscrit.

Le corps de la requête contient uniquement le Email. Voici un exemple de corps de requête :

{
  "email": "string"
}

Pour plus d’informations, consultez Utilisation du point de terminaison GET /confirmEmail plus haut dans cet article.

Utiliser le point de terminaison POST /forgotPassword

Génère un e-mail qui contient un code de réinitialisation de mot de passe. Envoyez ce code à /resetPassword avec un nouveau mot de passe.

Le corps de la requête contient uniquement l’Email. Voici un exemple :

{
  "email": "string"
}

Pour plus d’informations sur la façon de permettre à Identity d’envoyer des e-mails, consultez Utiliser le point de terminaison GET /confirmEmail.

Utiliser le point de terminaison POST /resetPassword

Appelez ce point de terminaison après avoir obtenu un code de réinitialisation en appelant le point de terminaison /forgotPassword.

Le corps de la requête nécessite Email, ResetCode et NewPassword. Voici un exemple :

{
  "email": "string",
  "resetCode": "string",
  "newPassword": "string"
}

Utiliser le point de terminaison POST /manage/2fa

Configure l’authentification à deux facteurs (2FA) pour l’utilisateur. Lorsque 2FA est activée, l’établissement d’une connexion nécessite un code généré par une application d’authentification en plus de l’adresse e-mail et du mot de passe.

Activer la 2FA

Pour activer 2FA pour l’utilisateur actuellement authentifié :

• Appelez le point de terminaison /manage/2fa, en envoyant un objet JSON vide ({}) dans le corps de la demande.

• Le corps de la réponse fournit la SharedKey ainsi que d’autres propriétés qui ne sont pas nécessaires à ce stade. La clé partagée est utilisée pour configurer l’application d’authentification. Exemple de corps de réponse :

  {
    "sharedKey": "string",
    "recoveryCodesLeft": 0,
    "recoveryCodes": null,
    "isTwoFactorEnabled": false,
    "isMachineRemembered": false
  }
  

• Utilisez la clé partagée pour obtenir un mots de passe à usage unique et durée définie (TOTP). Pour plus d’informations, consultez Activer la génération de code QR pour les applications d’authentification TOTP dans ASP.NET Core.

• Appelez le point de terminaison /manage/2fa, en envoyant le TOTP et "enable": true dans le corps de la requête. Par exemple :

  {
    "enable": true,
    "twoFactorCode": "string"
  }
  

• Le corps de la réponse confirme que IsTwoFactorEnabled est true et fournit les RecoveryCodes. Les codes de récupération sont utilisés pour se connecter lorsque l’application d’authentification n’est pas disponible. Exemple de corps de réponse après l’activation de 2FA :

  {
    "sharedKey": "string",
    "recoveryCodesLeft": 10,
    "recoveryCodes": [
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string"
    ],
    "isTwoFactorEnabled": true,
    "isMachineRemembered": false
  }
  

Se connecter avec 2FA

Appelez le point de terminaison /login, en envoyant l’adresse e-mail, le mot de passe et le TOTP dans le corps de la requête. Par exemple :

{
  "email": "string",
  "password": "string",
  "twoFactorCode": "string"
}

Si l’utilisateur n’a pas accès à l’application d’authentification, connectez-vous en appelant le point de terminaison /login avec l’un des codes de récupération fournis lorsque 2FA a été activée. Le corps de votre requête ressemble à l’exemple suivant :

{
  "email": "string",
  "password": "string",
  "twoFactorRecoveryCode": "string"
}

Réinitialiser les codes de récupération

Pour obtenir une nouvelle collection de codes de récupération, appelez ce point de terminaison avec ResetRecoveryCodes défini sur true. Voici un exemple de corps de requête :

{
  "resetRecoveryCodes": true
}

Réinitialiser la clé partagée

Pour obtenir une nouvelle clé partagée aléatoire, appelez ce point de terminaison avec ResetSharedKey défini sur true. Voici un exemple de corps de requête :

{
  "resetSharedKey": true
}

La réinitialisation de la clé désactive automatiquement l’exigence de connexion à deux facteurs pour l’utilisateur authentifié jusqu’à ce qu’elle soit réactivée par une requête ultérieure.

Oublier la machine

Pour effacer le cookie « indicateur Mémoriser mes informations » s’il est présent, appelez ce point de terminaison avec ForgetMachine défini sur true. Voici un exemple de corps de requête :

{
  "forgetMachine": true
}

Ce point de terminaison n’a aucun impact sur l’authentification basée sur les jetons.

Utiliser le point de terminaison GET /manage/info

Obtient l’adresse e-mail et l’état de la confirmation par e-mail de l’utilisateur connecté. Les revendications ont été omises de ce point de terminaison pour des raisons de sécurité. Si des revendications sont nécessaires, utilisez les API côté serveur afin de configurer un point de terminaison pour les revendications. Ou au lieu de partager toutes les revendications des utilisateurs, fournissez un point de terminaison de validation qui accepte une revendication et répond si l’utilisateur la détient.

La requête ne nécessite aucun paramètre. Le corps de la réponse inclut les propriétés Email et IsEmailConfirmed, comme dans l’exemple suivant :

{
  "email": "string",
  "isEmailConfirmed": true
}

Utiliser le point de terminaison POST /manage/info

Met à jour l’adresse e-mail et le mot de passe de l’utilisateur connecté. Envoyez NewEmail, NewPassword et OldPassword dans le corps de la requête, comme illustré dans l’exemple suivant :

{
  "newEmail": "string",
  "newPassword": "string",
  "oldPassword": "string"
}

Voici un exemple de corps de réponse :

{
  "email": "string",
  "isEmailConfirmed": false
}

Voir aussi

Pour plus d’informations, consultez les ressources suivantes :

• Choisir une solution de gestion des identity
• Identity solutions de gestion pour des applications web .NET
• Autorisation simple dans ASP.NET Core
• Ajouter, télécharger et supprimer des données utilisateur dans Identity dans un projet ASP.NET Core
• Créer une application ASP.NET Core avec des données utilisateur protégées par une autorisation
• Account confirmation and password recovery in ASP.NET Core (Confirmation de compte et récupération de mot de passe dans ASP.NET Core)
• Activer la génération de code QR pour les applications d’authentification TOTP dans ASP.NET Core
• Exemple de back-end d’API web pour les SPA Le fichier .http affiche l’authentification basée sur les jetons. Par exemple :
  • Ne définit pas useCookies
  • Utilise l’en-tête d’autorisation pour passer le jeton
  • Affiche l’actualisation pour étendre la session sans forcer l’utilisateur à se reconnecter
• Exemple d’application Angular qui utilise Identity pour sécuriser un back-end d’API web