Introduzione alle API Web .NET per Azure ADAzure AD .NET Web API getting started

Nota

Questo articolo fa parte della Guida per gli sviluppatori di Azure Active Directory.This article is part of the Azure Active Directory developer's guide.

Se si compila un'applicazione che fornisce l'accesso alle risorse protette, è necessario sapere come prevenire l'accesso non protetto a tali risorse.If you’re building an application that provides access to protected resources, you need to know how to prevent unwarranted access to those resources. Azure Active Directory (Azure AD) rende semplici e dirette le operazioni per la protezione di un'API Web usando i token di connessione dell'accesso di OAuth 2.0 con solo poche righe di codice.Azure Active Directory (Azure AD) makes it simple and straightforward to help protect a web API by using OAuth 2.0 bearer access tokens with only a few lines of code.

Nelle app Web Asp.NET, a questo scopo si usa l'implementazione di Microsoft del middleware OWIN gestito dalla community e incluso in .NET Framework 4.5.In ASP.NET web apps, you can accomplish this protection by using the Microsoft implementation of the community-driven OWIN middleware included in .NET Framework 4.5. Qui OWIN verrà usato per creare un'API Web "Elenco attività" in grado di:Here we’ll use OWIN to build a "To Do List" web API that:

  • Designare le API protette.Designates which APIs are protected.
  • Verificare che le chiamate all'API Web contengano un token di accesso valido.Validates that the web API calls contain a valid access token.

Per compilare l'API "To Do List", è innanzitutto necessario:To build the To Do List API, you first need to:

  1. Registrare un'applicazione con Azure AD.Register an application with Azure AD.
  2. Configurare l'app per l'uso della pipeline di autenticazione OWIN.Set up the app to use the OWIN authentication pipeline.
  3. Configurare un'applicazione client per chiamare l'API Web.Configure a client application to call the web API.

Per iniziare, scaricare la struttura dell'app o scaricare l'esempio completato.To get started, download the app skeleton or download the completed sample. Ognuno è una soluzione di Visual Studio 2013.Each is a Visual Studio 2013 solution. È necessario anche un tenant di Azure AD in cui registrare l'applicazione.You also need an Azure AD tenant in which to register your application. Se non si ha già un tenant, vedere le informazioni su come ottenerne uno.If you don't have one already, learn how to get one.

Passaggio 1: Registrare un'applicazione con Azure ADStep 1: Register an application with Azure AD

Per proteggere l'applicazione, si dovrà per prima cosa creare un'applicazione nel proprio tenant e fornire ad Azure AD alcune informazioni fondamentali.To help secure your application, you first need to create an application in your tenant and provide Azure AD with a few key pieces of information.

  1. Accedere al portale di Azure.Sign in to the Azure portal.

  2. Nella barra superiore fare clic sull'account.On the top bar, click your account. Nell'elenco di Directory scegliere il tenant di Azure AD in cui si vuole registrare l'applicazione.In the Directory list, choose the Azure AD tenant where you want to register your application.

  3. Fare clic su More Services (Altri servizi) nel riquadro sinistro, quindi selezionare Azure Active Directory.Click More Services in the left pane, and then select Azure Active Directory.

  4. Fare clic su Registrazioni per l'app e scegliere Aggiungi.Click App registrations, and then select Add.

  5. Seguire le istruzioni e creare una nuova applicazione Web e/o API Web.Follow the prompts and create a new Web Application and/or Web API.

    • Nome descrive l'applicazione agli utenti.Name describes your application to users. Immettere To Do List Service.Enter To Do List Service.
    • URI di reindirizzamento è una combinazione dello schema e della stringa che Azure AD userà per restituire i token richiesti dall'app.Redirect Uri is a scheme and string combination that Azure AD uses to return any tokens that your app has requested. Immettere https://localhost:44321/ per questo valore.Enter https://localhost:44321/ for this value.
  6. Dalla pagina Impostazioni -> Proprietà dell'applicazione aggiornare l'URI dell'ID app.From the Settings -> Properties page for your application, update the App ID URI. Immettere un identificatore specifico del tenant.Enter a tenant-specific identifier. Ad esempio, immettere https://contoso.onmicrosoft.com/TodoListService.For example, enter https://contoso.onmicrosoft.com/TodoListService.

  7. Salvare la configurazione.Save the configuration. Lasciare aperto il portale, poiché tra poco si dovrà registrare anche l'applicazione client.Leave the portal open, because you'll also need to register your client application shortly.

Passaggio 2: Configurare l'app per l'uso della pipeline di autenticazione OWINStep 2: Set up the app to use the OWIN authentication pipeline

Per convalidare le richieste in ingresso e i token, è necessario configurare l'applicazione per la comunicazione con Azure AD.To validate incoming requests and tokens, you need to set up your application to communicate with Azure AD.

  1. 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 by using the Package Manager Console.

    PM> Install-Package Microsoft.Owin.Security.ActiveDirectory -ProjectName TodoListService
    PM> Install-Package Microsoft.Owin.Host.SystemWeb -ProjectName TodoListService
    
  2. 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 cercare OWIN.Right-click the project, select Add > New Item, and then 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.

  3. Modificare la dichiarazione di classe in public partial class Startup.Change the class declaration to public partial class Startup. Parte di questa classe è stata già implementata in un altro file.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);
        }
    }
    
  4. Aprire il file App_Start\Startup.Auth.cs e implementare il metodo ConfigureAuth(…).Open the file App_Start\Startup.Auth.cs and implement the ConfigureAuth(…) method. I parametri forniti in WindowsAzureActiveDirectoryBearerAuthenticationOptions fungeranno da coordinate per consentire all'app di comunicare con Azure AD.The parameters that you provide in WindowsAzureActiveDirectoryBearerAuthenticationOptions will serve as coordinates for your app to communicate with Azure AD.

    public void ConfigureAuth(IAppBuilder app)
    {
        app.UseWindowsAzureActiveDirectoryBearerAuthentication(
            new WindowsAzureActiveDirectoryBearerAuthenticationOptions
            {
                Audience = ConfigurationManager.AppSettings["ida:Audience"],
                Tenant = ConfigurationManager.AppSettings["ida:Tenant"]
            });
    }
    
  5. A questo punto è possibile usare gli attributi [Authorize] per proteggere i controller e le azioni con l'autenticazione della connessione al token JSON Web (JWT).Now you can use [Authorize] attributes to help protect your controllers and actions with JSON Web Token (JWT) 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 ClaimsPrincpal .OWIN provides access to the claims inside the bearer token via the ClaimsPrincpal object.

  6. Un requisito comune per l'API Web è la convalida degli "ambiti" presenti nel token.A common requirement for web APIs is to validate the "scopes" present in the token. Ciò garantisce che l'utente goda delle autorizzazioni necessarie per accedere a To Do List Service.This ensures that the user has consented to the permissions required to access the To Do List Service.

    public IEnumerable<TodoItem> Get()
    {
        // user_impersonation is the default permission exposed by applications in Azure AD
        if (ClaimsPrincipal.Current.FindFirst("http://schemas.microsoft.com/identity/claims/scope").Value != "user_impersonation")
        {
            throw new HttpResponseException(new HttpResponseMessage {
              StatusCode = HttpStatusCode.Unauthorized,
              ReasonPhrase = "The Scope claim does not contain 'user_impersonation' or scope claim not found"
            });
        }
        ...
    }
    
  7. Aprire il file web.config nella radice del progetto TodoListService e immettere i valori di configurazione nella sezione <appSettings>.Open the web.config file in the root of the TodoListService project, and enter your configuration values in the <appSettings> section.

    • ida:Tenant è il nome del tenant di Azure AD, ad esempio contoso.onmicrosoft.com.ida:Tenant is the name of your Azure AD tenant--for example, contoso.onmicrosoft.com.
    • ida:Audience è l'URI ID app dell'applicazione immesso nel portale di Azure.ida:Audience is the App ID URI of the application that you entered in the Azure portal.

Passaggio 3: Configurare un'applicazione client ed eseguire il servizioStep 3: Configure a client application and run the service

Prima di poter vedere To Do List Service in azione, è necessario configurare To Do List Client, in modo che possa ricevere i token da Azure AD ed effettuare chiamate al servizio.Before you can see the To Do List Service in action, you need to configure the To Do List client so it can get tokens from Azure AD and make calls to the service.

  1. Tornare al portale di Azure.Go back to the Azure portal.

  2. Creare una nuova applicazione nel tenant di Azure AD e selezionare Applicazione client nativa nella richiesta risultante.Create a new application in your Azure AD tenant, and select Native Client Application in the resulting prompt.

    • Il nome descrive l'applicazione agli utenti.Name describes your application to users.
    • Immettere http://TodoListClient/ per il valore di URI di reindirizzamento .Enter http://TodoListClient/ for the Redirect Uri value.
  3. Dopo aver completato la registrazione, Azure AD assegna all'app un ID applicazione univoco.After you finish registration, Azure AD assigns a unique application ID to your app. Poiché questo valore sarà necessario nelle sezioni successive, copiarlo dalla pagina dell'applicazione.You’ll need this value in the next steps, so copy it from the application page.

  4. Nella pagina Impostazioni selezionare Autorizzazioni necessarie e selezionare Aggiungi.From the Settings page, select Required Permissions, and then select Add. Individuare e selezionare To Do List Service, aggiungere l'autorizzazione di Access TodoListService in Autorizzazioni delegate e quindi fare clic su Operazione completata.Locate and select the To Do List Service, add the Access TodoListService permission under Delegated Permissions, and then click Done.

  5. In Visual Studio aprire App.config nel progetto TodoListClient e quindi immettere i valori di configurazione nella sezione <appSettings>.In Visual Studio, open App.config in the TodoListClient project, and then enter your configuration values in the <appSettings> section.

    • ida:Tenant è il nome del tenant di Azure AD, ad esempio contoso.onmicrosoft.com.ida:Tenant is the name of your Azure AD tenant--for example, contoso.onmicrosoft.com.
    • ida:ClientId è l'ID app copiato dal portale di Azure.ida:ClientId is the app ID that you copied from the Azure portal.
    • todo:TodoListResourceId è l'URI ID app dell'applicazione To Do List Service immesso nel portale di Azure.todo:TodoListResourceId is the App ID URI of the To Do List Service application that you entered in the Azure portal.

Passaggi successiviNext steps

Infine pulire, compilare ed eseguire ogni progetto.Finally, clean, build, and run each project. Se non si è ancora creato un nuovo utente nel tenant con un dominio *.onmicrosoft.com, ora è possibile farlo.If you haven’t already, now is the time to create a new user in your tenant with a *.onmicrosoft.com domain. Accedere al client To Do List come l'utente creato e aggiungere alcune attività all'elenco delle attività dell'utente.Sign in to the To Do List client with that user, and add some tasks to the user's to-do list.

Come riferimento, l'esempio completo, senza valori di configurazione, è disponibile in GitHub.For reference, the completed sample (without your configuration values) is available in GitHub. È ora possibile passare ad altri scenari relativi alle identità.You can now move on to more identity scenarios.

Risorse aggiuntiveAdditional resources

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 la pagina del TechCenter per le notifiche sulla sicurezza tecnica per Microsoft e sottoscrivere gli avvisi di sicurezza.We encourage you to get notifications of when security incidents occur by visiting the TechCenter page for Microsoft technical security notifications and subscribing to security advisory alerts.