Proteggere un'API Web MVCSecure an MVC web API

Con l'endpoint v2.0 di Azure Active Directory è possibile proteggere un'API Web usando token di accesso OAuth 2.0 in modo da consentire agli utenti di accedere all'API Web in modo sicuro con un account Microsoft personale, aziendale o dell'istituto di istruzione.With Azure Active Directory the v2.0 endpoint, you can protect a Web API using OAuth 2.0 access tokens, enabling users with both personal Microsoft account and work or school accounts to securely access your Web API.

Nota

Non tutti gli scenari e le funzionalità di Azure Active Directory sono supportati dall'endpoint 2.0.Not all Azure Active Directory scenarios & features are supported by the v2.0 endpoint. Per determinare se è necessario usare l'endpoint v2.0, leggere le informazioni sulle limitazioni v2.0.To determine if you should use the v2.0 endpoint, read about v2.0 limitations.

Nelle API Web ASP.NET, a questo scopo si usa il middleware OWIN di Microsoft incluso in .NET Framework 4.5.In ASP.NET web APIs, you can accomplish this using Microsoft’s OWIN middleware included in .NET Framework 4.5. Verrà usato OWIN per compilare un'API Web MVC "Elenco attività" che consente ai client di creare e leggere le attività dall'elenco di attività dell'utente.Here we’ll use OWIN to build a "To Do List" MVC Web API that allows clients to create and read tasks from a user's To-Do list. L'API Web verifica che le richieste in ingresso contengano un token di accesso valido e rifiuta le richieste che non superano la convalida su una route protetta.The web API will validate that incoming requests contain a valid access token and reject any requests that do not pass validation on a protected route. Questo esempio è stato creato con Visual Studio 2015.This sample was built using Visual Studio 2015.

ScaricareDownload

Il codice per questa esercitazione è salvato su GitHub.The code for this tutorial is maintained on GitHub. Per seguire la procedura è possibile scaricare la struttura dell'app come file con estensione zip o clonare la struttura:To follow along, you can download the app's skeleton as a .zip or clone the skeleton:

git clone --branch skeleton https://github.com/AzureADQuickStarts/AppModelv2-WebAPI-DotNet.git

Lo scheletro di un'app include tutto il codice boilerplate per una semplice API, ma non tutte le parti relative all'identità.The skeleton app includes all the boilerplate code for a simple API, but is missing all of the identity-related pieces. Se non si vuole proseguire, in alternativa è possibile clonare o scaricare l'esempio completo.If you don't want to follow along, you can instead clone or download the completed sample.

git clone https://github.com/AzureADQuickStarts/AppModelv2-WebAPI-DotNet.git

Registrare un'appRegister an app

Creare una nuova app in apps.dev.microsoft.com o seguire questa procedura dettagliata.Create a new app at apps.dev.microsoft.com, or follow these detailed steps. Verificare di:Make sure to:

  • Copiare l' ID applicazione assegnato all'app, perché verrà richiesto a breve.Copy down the Application Id assigned to your app, you'll need it soon.

Questa soluzione di visual studio contiene anche una "TodoListClient", che è una semplice applicazione WPF.This visual studio solution also contains a "TodoListClient", which is a simple WPF app. La TodoListClient viene utilizzata per illustrare come avviene l’accesso dell'utente e come un client può inviare le richieste all’API Web.The TodoListClient is used to demonstrate how a user signs-in and how a client can issue requests to your Web API. In questo caso, sia TodoListClient sia il TodoListService sono rappresentati dalla stessa app.In this case, both the TodoListClient and the TodoListService are represented by the same app. Per configurare il TodoListClient, è necessario inoltre:To configure the TodoListClient, you should also:

  • Aggiungere la piattaforma Mobile per l'app.Add the Mobile platform for your app.

Installare OWINInstall OWIN

Dopo aver registrato un'app, si dovrà configurarla in modo che comunichi con l'endpoint v 2.0 per convalidare le richieste in ingresso e i token.Now that you’ve registered an app, you need to set up your app to communicate with the v2.0 endpoint in order to validate incoming requests & tokens.

  • Per iniziare, aprire la soluzione e aggiungere i pacchetti NuGet del middleware OWIN al progetto TodoListService usando la Console di Gestione pacchetti.To begin, open the solution and add the OWIN middleware NuGet packages to the TodoListService project using the Package Manager Console.
PM> Install-Package Microsoft.Owin.Security.OAuth -ProjectName TodoListService
PM> Install-Package Microsoft.Owin.Security.Jwt -ProjectName TodoListService
PM> Install-Package Microsoft.Owin.Host.SystemWeb -ProjectName TodoListService
PM> Install-Package Microsoft.IdentityModel.Protocol.Extensions -ProjectName TodoListService

Configurare l'autenticazione OAuthConfigure OAuth authentication

  • Aggiungere al progetto TodoListService una OWIN Startup Class denominata Startup.cs.Add an OWIN Startup class to the TodoListService project called Startup.cs. Fare clic con il pulsante destro del mouse sul progetto, scegliere Aggiungi --> Nuovo elemento e quindi cercare"OWIN".Right click on the project --> Add --> New Item --> Search for “OWIN”. Il middleware OWIN richiamerà il metodo Configuration(…) all'avvio dell'app.The OWIN middleware will invoke the Configuration(…) method when your app starts.
  • Sostituire la dichiarazione della classe con public partial class Startup .Change the class declaration to public partial class Startup - we’ve already implemented part of this class for you in another file. Nel metodo Configuration(…) effettuare una chiamata a ConfgureAuth(...) per configurare l'autenticazione per l'app Web.In the Configuration(…) method, make a call to ConfgureAuth(…) to set up authentication for your web app.
public partial class Startup
{
    public void Configuration(IAppBuilder app)
    {
        ConfigureAuth(app);
    }
}
  • Aprire il file App_Start\Startup.Auth.cs e implementare il metodo ConfigureAuth(…), che configura l'API Web per accettare token dall'endpoint 2.0.Open the file App_Start\Startup.Auth.cs and implement the ConfigureAuth(…) method, which will set up the Web API to accept tokens from the v2.0 endpoint.
public void ConfigureAuth(IAppBuilder app)
{
        var tvps = new TokenValidationParameters
        {
                // In this app, the TodoListClient and TodoListService
                // are represented using the same Application Id - we use
                // the Application Id to represent the audience, or the
                // intended recipient of tokens.

                ValidAudience = clientId,

                // In a real applicaiton, you might use issuer validation to
                // verify that the user's organization (if applicable) has
                // signed up for the app.  Here, we'll just turn it off.

                ValidateIssuer = false,
        };

        // Set up the OWIN pipeline to use OAuth 2.0 Bearer authentication.
        // The options provided here tell the middleware about the type of tokens
        // that will be recieved, which are JWTs for the v2.0 endpoint.

        // NOTE: The usual WindowsAzureActiveDirectoryBearerAuthenticaitonMiddleware uses a
        // metadata endpoint which is not supported by the v2.0 endpoint.  Instead, this
        // OpenIdConenctCachingSecurityTokenProvider can be used to fetch & use the OpenIdConnect
        // metadata document.

        app.UseOAuthBearerAuthentication(new OAuthBearerAuthenticationOptions
        {
                AccessTokenFormat = new Microsoft.Owin.Security.Jwt.JwtFormat(tvps, new OpenIdConnectCachingSecurityTokenProvider("https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration")),
        });
}
  • È ora possibile usare gli attributi [Authorize] per proteggere i controller e le azioni con l'autenticazione della connessione OAuth 2.0.Now you can use [Authorize] attributes to protect your controllers and actions with OAuth 2.0 bearer authentication. Decorare la classe Controllers\TodoListController.cs con un tag di autorizzazione.Decorate the Controllers\TodoListController.cs class with an authorize tag. Ciò forzerà l'utente a eseguire l'accesso prima di accedere alla pagina.This will force the user to sign in before accessing that page.
[Authorize]
public class TodoListController : ApiController
{
  • Quando un chiamante autorizzato riesce a chiamare una delle API TodoListController , l'azione potrebbe richiedere l'accesso alle informazioni relative al chiamante.When an authorized caller successfully invokes one of the TodoListController APIs, the action might need access to information about the caller. OWIN fornisce l'accesso alle attestazioni all'interno del token di connessione tramite l'oggetto ClaimsPrincipal .OWIN provides access to the claims inside the bearer token via the ClaimsPrincipal object.
public IEnumerable<TodoItem> Get()
{
    // You can use the ClaimsPrincipal to access information about the
    // user making the call.  In this case, we use the 'sub' or
    // NameIdentifier claim to serve as a key for the tasks in the data store.

    Claim subject = ClaimsPrincipal.Current.FindFirst(ClaimTypes.NameIdentifier);

    return from todo in todoBag
           where todo.Owner == subject.Value
           select todo;
}
  • Infine aprire il file web.config nella radice del progetto TodoListService e immettere i valori di configurazione nella sezione <appSettings>.Finally, open the web.config file in the root of the TodoListService project, and enter your configuration values in the <appSettings> section.
    • ida:Audience rappresenta l' ID applicazione dell'app immesso nel portale.Your ida:Audience is the Application Id of the app that you entered in the portal.

Configurare l'app clientConfigure the client app

Prima di poter vedere in azione il servizio To Do List, è necessario configurare il client To Do List in modo che possa ricevere i token dall'endpoint 2.0 ed eseguire chiamate al servizio.Before you can see the Todo List Service in action, you need to configure the Todo List Client so it can get tokens from the v2.0 endpoint and make calls to the service.

  • Nel progetto client To Do List aprire App.config e immettere i valori di configurazione nella sezione <appSettings>.In the TodoListClient project, open App.config and enter your configuration values in the <appSettings> section.
    • ID applicazione ida:ClientId copiato dal portale.Your ida:ClientId Application Id you copied from the portal.

Infine pulire, compilare ed eseguire ogni progetto.Finally, clean, build and run each project! È ora disponibile un'API Web .NET MVC che accetta token da account Microsoft personali, aziendali e dell'istituto di istruzione.You now have a .NET MVC Web API that accepts tokens from both personal Microsoft accounts and work or school accounts. Accedere al client To Do List e chiamare l'API Web in modo che aggiunga attività all'elenco di attività da svolgere dell'utente.Sign into the TodoListClient, and call your web api to add tasks to the user's To-Do list.

Come riferimento, l'esempio completato (senza i valori di configurazione) è disponibile in un file con estensione .zip qui. In alternativa, è possibile clonarlo da GitHub:For reference, the completed sample (without your configuration values) is provided as a .zip here, or you can clone it from GitHub:

git clone --branch complete https://github.com/AzureADQuickStarts/AppModelv2-WebAPI-DotNet.git

Passaggi successiviNext steps

È ora possibile passare ad altri argomenti.You can now move onto additional topics. È possibile:You may want to try:

Chiamare un'API Web da un'app Web >>Calling a Web API from a Web App >>

Per altre risorse, vedere:For additional resources, check out:

Ottenere aggiornamenti della sicurezza per i prodottiGet security updates for our products

È consigliabile ricevere notifiche in caso di problemi di sicurezza. A tale scopo, visitare questa pagina e sottoscrivere gli avvisi di sicurezza.We encourage you to get notifications of when security incidents occur by visiting this page and subscribing to Security Advisory Alerts.