Condividi tramite

API Web protetta: configurazione del codice

Si applica a: cerchio verde con un simbolo di segno di spunta bianco che indica il contenuto seguente si applica ai tenant della forza lavoro. Tenant della forza lavoro (altre informazioni)

Per configurare il codice per l'API Web protetta, comprendere:

  • Cosa definisce le API come protette.
  • Come configurare un token portatore.
  • Come convalidare il token.

Versione accettata del token

Microsoft Identity Platform può emettere token v1.0 e token v2.0. Per altre informazioni su questi tipi di token, vedere Token di accesso.

La versione del token che l'API può accettare dipende dalla selezione di Tipi di account supportati quando si crea la registrazione dell'applicazione API Web nel portale di Azure.

  • Il valore dei Tipi di account supportati è impostato su Account in qualsiasi directory organizzativa e account Microsoft personali (ad esempio Skype, Xbox, Outlook.com), la versione del token accettata deve essere impostata su v2.0.
  • In caso contrario, la versione del token accettata può essere v1.0.

Dopo aver creato l'applicazione, è possibile determinare o modificare la versione del token accettata seguendo questa procedura:

  1. Nell'interfaccia di amministrazione di Microsoft Entra, selezionare l'app e quindi selezionare Manifesto.
  2. Trovare la proprietà accessTokenAcceptedVersion nel manifesto.
  3. Il valore specifica a Microsoft Entra quale versione del token accetta l'API Web.
    • Se il valore è 2, l'API Web accetta i token v2.0.
    • Se il valore è null, l’API Web accetta token v1.0.
  4. Se è stata modificata la versione del token, selezionare Salva.

L'API Web specifica la versione del token accettata. Quando un client richiede un token per l'API Web da Microsoft Identity Platform, il client ottiene un token che indica quale versione del token accetta l'API Web.

Cosa definisce le API di ASP.NET e ASP.NET Core come protette?

Come le app Web, le API Web di ASP.NET e ASP.NET Core sono protette perché le azioni del controller sono precedute dall'attributo [Authorize]. Le azioni del controller possono essere chiamate solo se l'API viene chiamata con un'identità autorizzata.

Prendere in considerazione le domande seguenti:

  • Solo un'app può chiamare un'API Web. In che modo l'API conosce l'identità dell'app che la chiama?
  • Se l'app chiama l'API per conto di un utente, qual è l'identità dell'utente?

Token di accesso

Il bearer token impostato nell'intestazione quando l'app viene chiamata contiene informazioni sull'identità dell'app. Contiene anche informazioni sull'utente, a meno che l'app Web non accetti chiamate da un servizio all'altro da un'applicazione daemon.

Ecco un esempio di codice C# che mostra un client che chiama l'API dopo aver acquisito un token con Microsoft Authentication Library per .NET (MSAL.NET):

var scopes = new[] {$"api://.../access_as_user"};
var result = await app.AcquireToken(scopes)
                      .ExecuteAsync();

httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", result.AccessToken);

// Call the web API.
HttpResponseMessage response = await _httpClient.GetAsync(apiUri);

Importante

Un'applicazione client richiede un token di accesso alla piattaforma di identità Microsoft per l’API web. L'API è l'unica applicazione che deve verificare il token e visualizzare le attestazioni contenute. Le app client non devono mai provare a esaminare le attestazioni nei token.

In futuro, l'API Web potrebbe richiedere che il token sia crittografato. Questo requisito impedisce l'accesso alle app client in grado di visualizzare i token di accesso.

Configurazione di JwtBearer

In questa sezione viene descritto come configurare un token di connessione.

File di configurazione

È necessario specificare il TenantId solo se si desidera accettare i token di accesso da un singolo tenant (applicazione line-of-business). In caso contrario, può essere lasciato come common. I diversi valori possono essere:

  • Un GUID (ID tenant = ID directory)
  • common possono essere qualsiasi organizzazione e account personali
  • organizations può essere qualsiasi organizzazione
  • consumers sono gli account Microsoft personali
{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "Enter_the_Application_(client)_ID_here",
    "TenantId": "common"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

Uso di un URI ID app personalizzato per un'API Web

Se è stato accettato l'URI ID app predefinito proposto dal portale di Azure, non è necessario specificare il gruppo di destinatari. In caso contrario, aggiungere una proprietà Audience il cui valore è l'URI ID app per l'API Web. In genere inizia con api://.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "Enter_the_Application_(client)_ID_here",
    "TenantId": "common",
    "Audience": "Enter_the_Application_ID_URI_here"
  },
}

Inizializzazione del codice

Quando un'app viene chiamata su un'azione controller che contiene un attributo [Authorize], ASP.NET e ASP.NET Core estraggono il token di accesso dal token portatore dell'intestazione Authorization. Il token di accesso viene quindi inoltrato al middleware JwtBearer, che chiama le estensioni Microsoft IdentityModel per .NET.

Microsoft.Identity.Web

Microsoft consiglia di usare il pacchetto NuGet Microsoft.Identity.Web durante lo sviluppo di un'API Web con ASP.NET Core.

Microsoft.Identity.Web fornisce l'associazione tra ASP.NET Core, il middleware di autenticazione e Microsoft Authentication Library (MSAL) per .NET. Consente un'esperienza di sviluppo più chiara e affidabile e sfrutta la potenza di Microsoft Identity Platform e Azure AD B2C.

ASP.NET per .NET 6.0

Per creare un nuovo progetto API Web che usa Microsoft.Identity.Web, usare un modello di progetto nell'interfaccia della riga di comando di .NET 6.0 o in Visual Studio.

Interfaccia della riga di comando di dotnet core

# Create new web API that uses Microsoft.Identity.Web
dotnet new webapi --auth SingleOrg

Visual Studio: per creare un progetto API Web in Visual Studio, selezionare File>Nuovo>Progetto>ASP.NET Core.

Sia l'interfaccia della riga di comando di .NET che i modelli di progetto di Visual Studio creano un file Program.cs simile a questo frammento di codice. Osserva l'utilizzo della direttiva Microsoft.Identity.Web e le righe contenenti l'autenticazione e l'autorizzazione.

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

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

app.MapControllers();

app.Run();
  • Last updated on