Ajoutez l’authentification à votre application .NET Core (Blazor Server)
- La démonstration suivante est construite sur .NET Core 8.0. Le SDK est compatible avec .NET 6.0 ou supérieur.
- Les projets d'exemple .NET Core sont disponibles dans le répertoire GitHub.
Prérequis
- Un compte Logto Cloud ou un Logto auto-hébergé.
- Une application web traditionnelle Logto créée.
Installation
Ajoutez le package NuGet à votre projet :
dotnet add package Logto.AspNetCore.Authentication
Intégration
Ajouter l'authentification Logto
Ouvrez Startup.cs
(ou Program.cs
) et ajoutez le code suivant pour enregistrer les services d'authentification Logto :
using Logto.AspNetCore.Authentication;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddLogtoAuthentication(options =>
{
options.Endpoint = builder.Configuration["Logto:Endpoint"]!;
options.AppId = builder.Configuration["Logto:AppId"]!;
options.AppSecret = builder.Configuration["Logto:AppSecret"];
});
La méthode AddLogtoAuthentication
effectuera les actions suivantes :
- Définir le schéma d'Authentification (Authentication) par défaut sur
LogtoDefaults.CookieScheme
. - Définir le schéma de défi par défaut sur
LogtoDefaults.AuthenticationScheme
. - Définir le schéma de déconnexion par défaut sur
LogtoDefaults.AuthenticationScheme
. - Ajouter des gestionnaires d'authentification par cookie et OpenID Connect au schéma d'authentification.
Flux de connexion et de déconnexion
Avant de continuer, il y a deux termes confus dans le middleware d'authentification .NET Core que nous devons clarifier :
- CallbackPath : L'URI vers laquelle Logto redirigera l'utilisateur après que l'utilisateur se soit connecté (l'"URI de redirection" dans Logto)
- RedirectUri : L'URI vers laquelle sera redirigé après que les actions nécessaires ont été prises dans le middleware d'Authentification (Authentication) Logto.
Le processus de connexion peut être illustré comme suit :
De même, .NET Core a également SignedOutCallbackPath et RedirectUri pour le flux de déconnexion.
Pour plus de clarté, nous les appellerons comme suit :
Terme que nous utilisons | Terme .NET Core |
---|---|
URI de redirection Logto | CallbackPath |
URI de redirection post-déconnexion Logto | SignedOutCallbackPath |
URI de redirection de l'application | RedirectUri |
Concernant la connexion basée sur la redirection
- Ce processus d'authentification (Authentication) suit le protocole OpenID Connect (OIDC), et Logto applique des mesures de sécurité strictes pour protéger la connexion utilisateur.
- Si vous avez plusieurs applications, vous pouvez utiliser le même fournisseur d’identité (Logto). Une fois que l'utilisateur se connecte à une application, Logto complétera automatiquement le processus de connexion lorsque l'utilisateur accède à une autre application.
Pour en savoir plus sur la logique et les avantages de la connexion basée sur la redirection, consultez Expérience de connexion Logto expliquée.
Configurer les URIs de redirection
Dans les extraits de code suivants, nous supposons que votre application fonctionne sur http://localhost:3000/
.
Tout d'abord, configurons l' URI de redirection Logto. Ajoutez l'URI suivante à la liste des "URIs de redirection" sur la page des détails de l'application Logto :
http://http://localhost:3000//Callback
Pour configurer l' URI de redirection après déconnexion Logto, ajoutez l'URI suivante à la liste des "URIs de redirection après déconnexion" sur la page des détails de l'application Logto :
http://http://localhost:3000//SignedOutCallback
Modifier les chemins par défaut
L' URI de redirection Logto a un chemin par défaut de /Callback
, et l' URI de redirection après déconnexion Logto a un chemin par défaut de /SignedOutCallback
.
Vous pouvez les laisser tels quels s'il n'y a pas de besoin particulier. Si vous souhaitez les modifier, vous pouvez définir la propriété CallbackPath
et SignedOutCallbackPath
pour LogtoOptions
:
builder.Services.AddLogtoAuthentication(options =>
{
// Autres configurations...
options.CallbackPath = "/Foo";
options.SignedOutCallbackPath = "/Bar";
});
N'oubliez pas de mettre à jour la valeur sur la page des détails de l'application Logto en conséquence.
Ajouter des routes
Étant donné que Blazor Server utilise SignalR pour communiquer entre le serveur et le client, cela signifie que les méthodes qui manipulent directement le contexte HTTP (comme l'émission de défis ou de redirections) ne fonctionnent pas comme prévu lorsqu'elles sont appelées depuis un composant Blazor.
Pour corriger cela, nous devons explicitement ajouter deux points de terminaison pour les redirections de connexion et de déconnexion :
app.MapGet("/SignIn", async context =>
{
if (!(context.User?.Identity?.IsAuthenticated ?? false))
{
await context.ChallengeAsync(new AuthenticationProperties { RedirectUri = "/" });
} else {
context.Response.Redirect("/");
}
});
app.MapGet("/SignOut", async context =>
{
if (context.User?.Identity?.IsAuthenticated ?? false)
{
await context.SignOutAsync(new AuthenticationProperties { RedirectUri = "/" });
} else {
context.Response.Redirect("/");
}
});
Nous pouvons maintenant rediriger vers ces points de terminaison pour déclencher la connexion et la déconnexion.
Implémenter les boutons de connexion et de déconnexion
Dans le composant Razor, ajoutez le code suivant :
@using Microsoft.AspNetCore.Components.Authorization
@using System.Security.Claims
@inject AuthenticationStateProvider AuthenticationStateProvider
@inject NavigationManager NavigationManager
@* ... *@
<p>Est authentifié : @User.Identity?.IsAuthenticated</p>
@if (User.Identity?.IsAuthenticated == true)
{
<button @onclick="SignOut">Se déconnecter</button>
}
else
{
<button @onclick="SignIn">Se connecter</button>
}
@* ... *@
@code {
private ClaimsPrincipal? User { get; set; }
protected override async Task OnInitializedAsync()
{
var authState = await AuthenticationStateProvider.GetAuthenticationStateAsync();
User = authState.User;
}
private void SignIn()
{
NavigationManager.NavigateTo("/SignIn", forceLoad: true);
}
private void SignOut()
{
NavigationManager.NavigateTo("/SignOut", forceLoad: true);
}
}
Explication :
- Le
AuthenticationStateProvider
injecté est utilisé pour obtenir l'état d'authentification de l'utilisateur actuel et remplir la propriétéUser
. - Les méthodes
SignIn
etSignOut
sont utilisées pour rediriger l'utilisateur vers les points de terminaison de connexion et de déconnexion respectivement. En raison de la nature de Blazor Server, nous devons utiliserNavigationManager
avec un chargement forcé pour déclencher la redirection.
La page affichera le bouton "Se connecter" si l'utilisateur n'est pas authentifié, et affichera le bouton "Se déconnecter" si l'utilisateur est authentifié.
Le composant <AuthorizeView />
Alternativement, vous pouvez utiliser le composant AuthorizeView
pour rendre conditionnellement du contenu en fonction de l'état d'authentification de l'utilisateur. Ce composant est utile lorsque vous souhaitez afficher un contenu différent pour les utilisateurs authentifiés et non authentifiés.
Dans votre composant Razor, ajoutez le code suivant :
@using Microsoft.AspNetCore.Components.Authorization
@* ... *@
<AuthorizeView>
<Authorized>
<p>Nom : @User?.Identity?.Name</p>
@* Contenu pour les utilisateurs authentifiés *@
</Authorized>
<NotAuthorized>
@* Contenu pour les utilisateurs non authentifiés *@
</NotAuthorized>
</AuthorizeView>
@* ... *@
Le composant AuthorizeView
nécessite un paramètre en cascade de type Task<AuthenticationState>
. Un moyen direct d'obtenir ce paramètre est d'ajouter le composant <CascadingAuthenticationState>
. Cependant, en raison de la nature de Blazor Server, nous ne pouvons pas simplement ajouter le composant à la mise en page ou au composant racine (cela peut ne pas fonctionner comme prévu). Au lieu de cela, nous pouvons ajouter le code suivant au builder (Program.cs
ou Startup.cs
) pour fournir le paramètre en cascade :
builder.Services.AddCascadingAuthenticationState();
Ensuite, vous pouvez utiliser le composant AuthorizeView
dans chaque composant qui en a besoin.
Point de contrôle : Testez votre application
Maintenant, vous pouvez tester votre application :
- Exécutez votre application, vous verrez le bouton de connexion.
- Cliquez sur le bouton de connexion, le SDK initiera le processus de connexion et vous redirigera vers la page de connexion Logto.
- Après vous être connecté, vous serez redirigé vers votre application et verrez le bouton de déconnexion.
- Cliquez sur le bouton de déconnexion pour effacer le stockage local et vous déconnecter.
Obtenir des informations sur l'utilisateur
Afficher les informations de l'utilisateur
Pour savoir si l'utilisateur est authentifié, vous pouvez vérifier la propriété User.Identity?.IsAuthenticated
.
Pour obtenir les revendications du profil utilisateur, vous pouvez utiliser la propriété User.Claims
:
var claims = User.Claims;
// Obtenir l'ID de l'utilisateur
var userId = claims.FirstOrDefault(c => c.Type == LogtoParameters.Claims.Subject)?.Value;
Voir LogtoParameters.Claims
pour la liste des noms de revendications et leurs significations.
Demander des revendications supplémentaires
Il se peut que certaines informations utilisateur soient manquantes dans l'objet retourné par User.Claims
. Cela est dû au fait que OAuth 2.0 et OpenID Connect (OIDC) sont conçus pour suivre le principe du moindre privilège (PoLP), et Logto est construit sur ces normes.
Par défaut, des revendications limitées sont retournées. Si vous avez besoin de plus d'informations, vous pouvez demander des portées supplémentaires pour accéder à plus de revendications.
Une "revendication" est une assertion faite à propos d'un sujet ; une "portée" est un groupe de revendications. Dans le cas actuel, une revendication est une information sur l'utilisateur.
Voici un exemple non normatif de la relation portée - revendication :
La revendication "sub" signifie "sujet", qui est l'identifiant unique de l'utilisateur (c'est-à-dire l'ID utilisateur).
Le SDK Logto demandera toujours trois portées : openid
, profile
et offline_access
.
Pour demander des portées supplémentaires, vous pouvez configurer la propriété Scopes
dans l'objet options
:
builder.Services.AddLogtoAuthentication(options =>
{
// ...
options.Scopes = new string[] {
LogtoParameters.Scopes.Email,
LogtoParameters.Scopes.Phone
}
});
Ensuite, vous pouvez accéder aux revendications supplémentaires via User.Claims
:
var claims = User.Claims;
// Obtenir l'email de l'utilisateur
var email = claims.FirstOrDefault(c => c.Type == LogtoParameters.Claims.Email)?.Value;
Revendications nécessitant une requête réseau
Pour éviter de surcharger l'objet utilisateur, certaines revendications nécessitent des requêtes réseau pour être récupérées. Par exemple, la revendication custom_data n'est pas incluse dans l'objet utilisateur même si elle est demandée dans les portées. Pour récupérer ces revendications, vous pouvez définir GetClaimsFromUserInfoEndpoint
sur true
dans l'objet options
:
builder.Services.AddLogtoAuthentication(options =>
{
// ...
options.GetClaimsFromUserInfoEndpoint = true;
});
Portées et revendications
Logto utilise les conventions de portées et revendications OIDC pour définir les Portées et Revendications pour récupérer les informations utilisateur à partir du Jeton d’identifiant et du point de terminaison OIDC userinfo. Les termes "Portée" et "Revendication" proviennent des spécifications OAuth 2.0 et OpenID Connect (OIDC).
Voici la liste des Portées (Scopes) prises en charge et les Revendications (Claims) correspondantes :
openid
Nom de la revendication | Type | Description | Besoin d'userinfo ? |
---|---|---|---|
sub | string | L'identifiant unique de l'utilisateur | Non |
profile
Nom de la revendication | Type | Description | Besoin d'userinfo ? |
---|---|---|---|
name | string | Le nom complet de l'utilisateur | Non |
username | string | Le nom d'utilisateur de l'utilisateur | Non |
picture | string | URL de la photo de profil de l'utilisateur final. Cette URL DOIT faire référence à un fichier image (par exemple, un fichier image PNG, JPEG ou GIF), plutôt qu'à une page Web contenant une image. Notez que cette URL DOIT spécifiquement référencer une photo de profil de l'utilisateur final adaptée à l'affichage lors de la description de l'utilisateur final, plutôt qu'une photo arbitraire prise par l'utilisateur final. | Non |
created_at | number | Heure à laquelle l'utilisateur final a été créé. Le temps est représenté comme le nombre de millisecondes depuis l'époque Unix (1970-01-01T00:00:00Z). | Non |
updated_at | number | Heure à laquelle les informations de l'utilisateur final ont été mises à jour pour la dernière fois. Le temps est représenté comme le nombre de millisecondes depuis l'époque Unix (1970-01-01T00:00:00Z). | Non |
D'autres revendications standard incluent family_name
, given_name
, middle_name
, nickname
, preferred_username
, profile
, website
, gender
, birthdate
, zoneinfo
, et locale
seront également incluses dans la portée profile
sans avoir besoin de demander le point de terminaison userinfo. Une différence par rapport aux revendications ci-dessus est que ces revendications ne seront renvoyées que lorsque leurs valeurs ne sont pas vides, tandis que les revendications ci-dessus renverront null
si les valeurs sont vides.
Contrairement aux revendications standard, les revendications created_at
et updated_at
utilisent des millisecondes au lieu de secondes.
email
Nom de la revendication | Type | Description | Besoin d'userinfo ? |
---|---|---|---|
string | L'adresse e-mail de l'utilisateur | Non | |
email_verified | boolean | Si l'adresse e-mail a été vérifiée | Non |
phone
Nom de la revendication | Type | Description | Besoin d'userinfo ? |
---|---|---|---|
phone_number | string | Le numéro de téléphone de l'utilisateur | Non |
phone_number_verified | boolean | Si le numéro de téléphone a été vérifié | Non |
address
Veuillez vous référer à OpenID Connect Core 1.0 pour les détails de la revendication d'adresse.
custom_data
Nom de la revendication | Type | Description | Besoin d'userinfo ? |
---|---|---|---|
custom_data | object | Les données personnalisées de l'utilisateur | Oui |
identities
Nom de la revendication | Type | Description | Besoin d'userinfo ? |
---|---|---|---|
identities | object | Les identités liées de l'utilisateur | Oui |
sso_identities | array | Les identités SSO liées de l'utilisateur | Oui |
urn:logto:scope:organizations
Nom de la revendication | Type | Description | Besoin d'userinfo ? |
---|---|---|---|
organizations | string[] | Les identifiants d'organisation auxquels l'utilisateur appartient | Non |
organization_data | object[] | Les données d'organisation auxquelles l'utilisateur appartient | Oui |
urn:logto:scope:organization_roles
Nom de la revendication | Type | Description | Besoin d'userinfo ? |
---|---|---|---|
organization_roles | string[] | Les rôles d'organisation auxquels l'utilisateur appartient avec le format <organization_id>:<role_name> | Non |
En considérant la performance et la taille des données, si "Besoin d'userinfo ?" est "Oui", cela signifie que la revendication n'apparaîtra pas dans le Jeton d’identifiant (ID token), mais sera renvoyée dans la réponse du point de terminaison userinfo.
Ressources API
Nous vous recommandons de lire d'abord 🔐 Contrôle d’accès basé sur les rôles (RBAC) pour comprendre les concepts de base de Logto RBAC et comment configurer correctement les ressources API.
Configurer la ressource API dans votre application
Une fois que vous avez configuré les ressources API, vous pouvez les ajouter lors de la configuration de Logto dans votre application :
builder.Services.AddLogtoAuthentication(options =>
{
// ...
options.Resource = "https://<votre-indicateur-de-ressource-api>";
});
Chaque ressource API a ses propres permissions (portées).
Par exemple, la ressource https://shopping.your-app.com/api
a les permissions shopping:read
et shopping:write
, et la ressource https://store.your-app.com/api
a les permissions store:read
et store:write
.
Pour demander ces permissions, vous pouvez les ajouter lors de la configuration de Logto dans votre application :
builder.Services.AddLogtoAuthentication(options =>
{
// ...
options.Resource = "https://shopping.your-app.com/api";
options.Scopes = new string[] {
"openid",
"profile",
"offline_access",
"read",
"write"
};
});
Vous pouvez remarquer que les portées sont définies séparément des ressources API. Cela est dû au fait que les Indicateurs de ressource pour OAuth 2.0 spécifient que les portées finales pour la requête seront le produit cartésien de toutes les portées de tous les services cibles.
Il est acceptable de demander des portées qui ne sont pas définies dans les ressources API. Par exemple, vous pouvez demander la portée email
même si les ressources API n'ont pas la portée email
disponible. Les portées non disponibles seront ignorées en toute sécurité.
Après une connexion réussie, Logto émettra les portées appropriées aux ressources API en fonction des rôles de l'utilisateur.
Récupérer des jetons
Récupérer le jeton via HttpContext
Parfois, vous pouvez avoir besoin de récupérer le jeton d’accès (Access token) ou le jeton d’identifiant (ID token) pour des appels API. Vous pouvez utiliser la méthode GetTokenAsync
pour récupérer les jetons :
var accessToken = await HttpContext.GetTokenAsync(LogtoParameters.Tokens.AccessToken);
var idToken = await HttpContext.GetTokenAsync(LogtoParameters.Tokens.IdToken);
Pas besoin de vous soucier de l'expiration du jeton, le middleware d'authentification (Authentication) actualisera automatiquement les jetons lorsque cela sera nécessaire.
Bien que le middleware d'authentification (Authentication) actualise automatiquement les jetons, les revendications (Claims) dans l'objet utilisateur ne seront pas mises à jour en raison de la limitation du gestionnaire d'authentification OpenID Connect sous-jacent. Cela peut être résolu une fois que nous aurons écrit notre propre gestionnaire d'authentification.
Notez que le jeton d’accès (Access token) ci-dessus est un jeton opaque (Opaque token) pour le point de terminaison userinfo dans OpenID Connect, qui n'est pas un jeton JWT. Si vous avez spécifié la ressource API, vous devez utiliser LogtoParameters.Tokens.AccessTokenForResource
pour récupérer le jeton d’accès (Access token) pour la ressource API :
var accessToken = await HttpContext.GetTokenAsync(LogtoParameters.Tokens.AccessTokenForResource);
Ce jeton sera un jeton JWT avec la ressource API comme audience.