Mappatura, personalizzazione e trasformazione delle attestazioni in ASP.NET Core

Di Damien Bowden

Attestazioni possono essere create da qualsiasi utente o dai dati di identità che possono essere emessi usando un provider di identità attendibile o l'identità di ASP.NET Core. Un'attestazione è una coppia nome-valore che rappresenta ciò che il soggetto è, non ciò che il soggetto può fare. Questo articolo illustra le aree seguenti:

• Come configurare ed eseguire il mapping delle attestazioni usando un client OpenID Connect
• Impostare il nome e la dichiarazione del ruolo
• Reimpostare i namespaces delle claims
• Personalizzare ed estendere le attestazioni usando TransformAsync

Mappatura delle affermazioni con l'autenticazione OpenID Connect

Le affermazioni del profilo possono essere restituite in id_token, che viene restituito dopo un'autenticazione riuscita. L'app client ASP.NET Core richiede solo l'ambito del profilo. Quando si usa il id_token per le attestazioni, non è necessario alcun mapping di attestazione aggiuntiva.

using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Authentication.OpenIdConnect;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
})
   .AddCookie()
   .AddOpenIdConnect(options =>
   {
       options.SignInScheme = "Cookies";
       options.Authority = "-your-identity-provider-";
       options.RequireHttpsMetadata = true;
       options.ClientId = "-your-clientid-";
       options.ClientSecret = "-your-client-secret-from-user-secrets-or-keyvault";
       options.ResponseType = "code";
       options.UsePkce = true;
       options.Scope.Add("profile");
       options.SaveTokens = true;
   });

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

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

app.MapRazorPages();

app.Run();

Il codice precedente richiede il pacchetto NuGet Microsoft.AspNetCore.Authentication.OpenIdConnect .

Un altro modo per ottenere le attestazioni utente consiste nell'usare l'API OpenID Connect User Info. L'app client ASP.NET Core usa la GetClaimsFromUserInfoEndpoint proprietà per configurarlo. Una differenza importante rispetto alle prime impostazioni consiste nel fatto che è necessario specificare le attestazioni necessarie usando il MapUniqueJsonKey metodo , altrimenti solo le namegiven_name attestazioni standard e email saranno disponibili nell'app client. Le attestazioni incluse in id_token vengono mappate per impostazione predefinita. Questa è la differenza principale per la prima opzione. È necessario definire in modo esplicito alcune delle attestazioni necessarie.

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Authentication.OpenIdConnect;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
})
   .AddCookie()
   .AddOpenIdConnect(options =>
   {
       options.SignInScheme = "Cookies";
       options.Authority = "-your-identity-provider-";
       options.RequireHttpsMetadata = true;
       options.ClientId = "-your-clientid-";
       options.ClientSecret = "-client-secret-from-user-secrets-or-keyvault";
       options.ResponseType = "code";
       options.UsePkce = true;
       options.Scope.Add("profile");
       options.SaveTokens = true;
       options.GetClaimsFromUserInfoEndpoint = true;
       options.ClaimActions.MapUniqueJsonKey("preferred_username",
                                             "preferred_username");
       options.ClaimActions.MapUniqueJsonKey("gender", "gender");
   });

var app = builder.Build();

// Code removed for brevity.

Nota

Il gestore Open ID Connect predefinito usa richieste di autorizzazione push (PAR) se il documento di individuazione del provider di identità annuncia il supporto per PAR. Il documento di individuazione del provider di identità si trova in genere in .well-known/openid-configuration. Se non è possibile usare PAR nella configurazione del client sul provider di identità, PAR può essere disabilitato utilizzando l'opzione PushedAuthorizationBehavior.

builder.Services
    .AddAuthentication(options =>
    {
        options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
        options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
    })
    .AddCookie()
    .AddOpenIdConnect("oidc", oidcOptions =>
    {
        // Other provider-specific configuration goes here.

        // The default value is PushedAuthorizationBehavior.UseIfAvailable.

        // 'OpenIdConnectOptions' does not contain a definition for 'PushedAuthorizationBehavior'
        // and no accessible extension method 'PushedAuthorizationBehavior' accepting a first argument
        // of type 'OpenIdConnectOptions' could be found
        oidcOptions.PushedAuthorizationBehavior = PushedAuthorizationBehavior.Disable;
    });

Per garantire che l'autenticazione abbia esito positivo solo se viene utilizzato PAR, utilizzare invece PushedAuthorizationBehavior.Require. Questa modifica introduce anche un nuovo evento OnPushAuthorization per OpenIdConnectEvents che può essere usato per personalizzare la richiesta di autorizzazione push o gestirla manualmente. Per altre informazioni, vedere la proposta dell'API .

Mappatura delle richieste di nome e ruolo

L'attestazione Name e l'attestazione Role vengono mappate alle proprietà predefinite nel contesto HTTP principale di ASP.NET. A volte è necessario usare attestazioni diverse per le proprietà predefinite oppure l'attestazione del nome e l'attestazione del ruolo non corrispondono ai valori predefiniti. Le attestazioni possono essere mappate utilizzando la proprietà TokenValidationParameters e configurate per qualsiasi esigenza. I valori delle attestazioni possono essere utilizzati direttamente nella proprietà Name di HttpContext User. e nei ruoli.

Se il User.Identity.Name non ha alcun valore o i ruoli sono mancanti, controllare i valori nelle attestazioni restituite e impostare i valori NameClaimType e RoleClaimType. Le attestazioni restituite dall'autenticazione client possono essere visualizzate nel contesto HTTP.

builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
})
  .AddCookie()
  .AddOpenIdConnect(options =>
  {
       // Other options...
       options.TokenValidationParameters = new TokenValidationParameters
       {
          NameClaimType = "email"
          //, RoleClaimType = "role"
       };
  });

Namespace delle attestazioni, namespace predefiniti

ASP.NET Core aggiunge namespace predefiniti ad alcuni claim noti, che potrebbero non essere necessari nell'app. Se lo si desidera, disabilitare questi namespace aggiunti e usare le attestazioni esatte create dal server OpenID Connect.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

JsonWebTokenHandler.DefaultInboundClaimTypeMap.Clear();

builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
})
   .AddCookie()
   .AddOpenIdConnect(options =>
   {
       options.SignInScheme = "Cookies";
       options.Authority = "-your-identity-provider-";
       options.RequireHttpsMetadata = true;
       options.ClientId = "-your-clientid-";
       options.ClientSecret = "-your-client-secret-from-user-secrets-or-keyvault";
       options.ResponseType = "code";
       options.UsePkce = true;
       options.Scope.Add("profile");
       options.SaveTokens = true;
   });

var app = builder.Build();

// Code removed for brevity.

Se è necessario disabilitare i namespace per schema invece che a livello globale, è possibile usare l'opzione MapInboundClaims = false.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
})
   .AddCookie()
   .AddOpenIdConnect(options =>
   {
       options.SignInScheme = "Cookies";
       options.Authority = "-your-identity-provider-";
       options.RequireHttpsMetadata = true;
       options.ClientId = "-your-clientid-";
       options.ClientSecret = "-your-client-secret-from-user-secrets-or-keyvault";
       options.ResponseType = "code";
       options.UsePkce = true;
       options.MapInboundClaims = false;
       options.Scope.Add("profile");
       options.SaveTokens = true;
   });

var app = builder.Build();

// Code removed for brevity.

Estendere o aggiungere attestazioni personalizzate usando IClaimsTransformation

L'interfaccia IClaimsTransformation può essere usata per aggiungere attestazioni aggiuntive alla ClaimsPrincipal classe . L'interfaccia richiede un singolo metodo TransformAsync. Questo metodo può essere chiamato più volte. Aggiungi una nuova attestazione solo se non esiste già in ClaimsPrincipal. Viene creato un oggetto ClaimsIdentity per aggiungere le nuove attestazioni e questo può essere aggiunto a ClaimsPrincipal.

using Microsoft.AspNetCore.Authentication;
using System.Security.Claims;

public class MyClaimsTransformation : IClaimsTransformation
{
    public Task<ClaimsPrincipal> TransformAsync(ClaimsPrincipal principal)
    {
        ClaimsIdentity claimsIdentity = new ClaimsIdentity();
        var claimType = "myNewClaim";
        if (!principal.HasClaim(claim => claim.Type == claimType))
        {
            claimsIdentity.AddClaim(new Claim(claimType, "myClaimValue"));
        }

        principal.AddIdentity(claimsIdentity);
        return Task.FromResult(principal);
    }
}

L'interfaccia IClaimsTransformation e la MyClaimsTransformation classe possono essere registrate come servizio:

builder.Services.AddTransient<IClaimsTransformation, MyClaimsTransformation>();

Mappare le attestazioni dai provider di identità esterni

Fare riferimento al documento seguente:

Salvare attestazioni e token aggiuntivi da fornitori esterni in ASP.NET Core