Chiamare un'API Web da un'applicazione Web .NETCalling a web API from a .NET web app

Con l'endpoint v2.0 è possibile aggiungere rapidamente l'autenticazione alle app Web e alle API Web con supporto per account Microsoft personali, aziendali o dell'istituto di istruzione.With the v2.0 endpoint, you can quickly add authentication to your web apps and web APIs with support for both personal Microsoft accounts and work or school accounts. Di seguito viene creata un'app Web MVC che consente agli utenti di accedere tramite OpenID Connect e con l'aiuto del middleware OWIN di Microsoft.Here, we'll build an MVC web app that signs users in using OpenID Connect, with some help from Microsoft's OWIN middleware. L'applicazione Web otterrà i token di accesso OAuth 2.0 per un'api Web protetta da OAuth 2.0 che consente di creare, leggere ed eliminare le voci dell'elenco attività di un determinato utente.The web app will get OAuth 2.0 access tokens for a web api secured by OAuth 2.0 that allows create, read, and delete on a given user's "To-Do List".

Questa esercitazione è incentrata principalmente sull'uso di MSAL per l'acquisizione e l'uso di token di accesso in un'app Web, la cui descrizione dettagliata è disponibile qui.This tutorial will focus primarily on using MSAL to acquire and use access tokens in a web app, described in full here. Come prerequisiti, è consigliabile apprendere come aggiungere l'accesso base a un'app Web o come proteggere correttamente un'API Web.As prerequisites, you may want to first learn how to add basic sign-in to a web app or how to properly secure a 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.

Scaricare il codice di esempioDownload sample code

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-WebApp-WebAPI-OpenIdConnect-DotNet.git

In alternativa, è possibile scaricare l'app completata come file con estensione zip oppure clonare l'app completata:Alternatively, you can download the completed app as a .zip or clone the completed app:

git clone --branch complete https://github.com/AzureADQuickStarts/AppModelv2-WebApp-WebAPI-OpenIdConnect-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.
  • Creare una Chiave privata app di tipo Password e copiare il relativo valore per usarlo in seguito.Create an App Secret of the Password type, and copy down its value for later
  • Aggiungere la piattaforma Web per l'app.Add the Web platform for your app.
  • Immettere l' URI di reindirizzamentocorretto.Enter the correct Redirect URI. L'URI di reindirizzamento indica ad Azure AD dove indirizzare le risposte di autenticazione. Il valore predefinito per questa esercitazione è https://localhost:44326/.The redirect uri indicates to Azure AD where authentication responses should be directed - the default for this tutorial is https://localhost:44326/.

Installare OWINInstall OWIN

Aggiungere i pacchetti NuGet del middleware OWIN al progetto TodoList-WebApp tramite la console di Gestione pacchetti.Add the OWIN middleware NuGet packages to the TodoList-WebApp project using the Package Manager Console. Il middleware OWIN verrà usato, tra le altre cose, per inviare le richieste di accesso e disconnessione, gestire la sessione dell'utente e ottenere informazioni sull'utente.The OWIN middleware will be used to issue sign-in and sign-out requests, manage the user's session, and get information about the user, amongst other things.

PM> Install-Package Microsoft.Owin.Security.OpenIdConnect -ProjectName TodoList-WebApp
PM> Install-Package Microsoft.Owin.Security.Cookies -ProjectName TodoList-WebApp
PM> Install-Package Microsoft.Owin.Host.SystemWeb -ProjectName TodoList-WebApp

Connettere l'utente all'appSign the user in

Configurare il middleware OWIN per l'uso del protocollo di autenticazione OpenID Connect.Now configure the OWIN middleware to use the OpenID Connect authentication protocol.

  • Aprire il file web.config nella radice del progetto TodoList-WebApp e immettere i valori di configurazione dell'app nella sezione <appSettings>.Open the web.config file in the root of the TodoList-WebApp project, and enter your app's configuration values in the <appSettings> section.
    • ida:ClientId rappresenta l' ID applicazione assegnato all'app nel portale di registrazione.The ida:ClientId is the Application Id assigned to your app in the registration portal.
    • ida:ClientSecret rappresenta la chiave privata app creata nel portale di registrazione.The ida:ClientSecret is the App Secret you created in the registration portal.
    • ida:RedirectUri rappresenta l' URI di reindirizzamento immesso nel portale.The ida:RedirectUri is the Redirect Uri you entered in the portal.
  • Aprire il file web.config nella radice del progetto TodoList-Service e sostituire ida:Audience con lo stesso ID applicazione di cui sopra.Open the web.config file in the root of the TodoList-Service project, and replace the ida:Audience with the same Application Id as above.
  • Aprire il file App_Start\Startup.Auth.cs e aggiungere istruzioni using per le librerie indicate in precedenza.Open the file App_Start\Startup.Auth.cs and add using statements for the libraries from above.
  • Nello stesso file, implementare il metodo ConfigureAuth(...) .In the same file, implement the ConfigureAuth(...) method. I parametri forniti in OpenIDConnectAuthenticationOptions fungeranno da coordinate per consentire all'app di comunicare con Azure AD.The parameters you provide in OpenIDConnectAuthenticationOptions will serve as coordinates for your app to communicate with Azure AD.
public void ConfigureAuth(IAppBuilder app)
{
    app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);

    app.UseCookieAuthentication(new CookieAuthenticationOptions());

    app.UseOpenIdConnectAuthentication(
        new OpenIdConnectAuthenticationOptions
        {

                    // The `Authority` represents the v2.0 endpoint - https://login.microsoftonline.com/common/v2.0
                    // The `Scope` describes the permissions that your app will need.  See https://azure.microsoft.com/documentation/articles/active-directory-v2-scopes/
                    // In a real application you could use issuer validation for additional checks, like making sure the user's organization has signed up for your app, for instance.

                    ClientId = clientId,
                    Authority = String.Format(CultureInfo.InvariantCulture, aadInstance, "common", "/v2.0 "),
                    Scope = "openid email profile offline_access",
                    RedirectUri = redirectUri,
                    PostLogoutRedirectUri = redirectUri,
                    TokenValidationParameters = new TokenValidationParameters
                    {
                        ValidateIssuer = false,
                    },

                    // The `AuthorizationCodeReceived` notification is used to capture and redeem the authorization_code that the v2.0 endpoint returns to your app.

                    Notifications = new OpenIdConnectAuthenticationNotifications
                    {
                        AuthenticationFailed = OnAuthenticationFailed,
                        AuthorizationCodeReceived = OnAuthorizationCodeReceived,
                    }

        });
}
// ...

Usare MSAL per ottenere i token di accessoUse MSAL to get access tokens

Nella notifica AuthorizationCodeReceived si desidera usare OAuth 2.0 in parallelo con OpenID Connect per riscattare l'authorization_code per un token di accesso al servizio To Do List.In the AuthorizationCodeReceived notification, we want to use OAuth 2.0 in tandem with OpenID Connect to redeem the authorization_code for an access token to the To-Do List Service. MSAL può semplificare questo processo.MSAL can make this process easy for you:

  • Per prima cosa installare la versione di anteprima di MSAL:First, install the preview version of MSAL:

PM> Install-Package Microsoft.Identity.Client -ProjectName TodoList-WebApp -IncludePrerelease

  • Aggiungere quindi un'altra istruzione usingal file App_Start\Startup.Auth.cs per MSAL.And add another using statement to the App_Start\Startup.Auth.cs file for MSAL.
  • Aggiungere ora un nuovo metodo, il gestore eventi OnAuthorizationCodeReceived.Now add a new method, the OnAuthorizationCodeReceived event handler. Questo gestore userà MSAL per acquisire un token di accesso per l'API To Do List e archivierà il token nella cache dei token di MSAL per usi successivi:This handler will use MSAL to acquire an access token to the To-Do List API, and will store the token in MSAL's token cache for later:
private async Task OnAuthorizationCodeReceived(AuthorizationCodeReceivedNotification notification)
{
        string userObjectId = notification.AuthenticationTicket.Identity.FindFirst("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier").Value;
        string tenantID = notification.AuthenticationTicket.Identity.FindFirst("http://schemas.microsoft.com/identity/claims/tenantid").Value;
        string authority = String.Format(CultureInfo.InvariantCulture, aadInstance, tenantID, string.Empty);
        ClientCredential cred = new ClientCredential(clientId, clientSecret);

        // Here you ask for a token using the web app's clientId as the scope, since the web app and service share the same clientId.
        app = new ConfidentialClientApplication(Startup.clientId, redirectUri, cred, new NaiveSessionCache(userObjectId, notification.OwinContext.Environment["System.Web.HttpContextBase"] as HttpContextBase)) {};
        var authResult = await app.AcquireTokenByAuthorizationCodeAsync(new string[] { clientId }, notification.Code);
}
// ...
  • Nelle app Web, MSAL ha una cache di token estendibile che può essere usata per archiviare i token.In web apps, MSAL has an extensible token cache that can be used to store tokens. Questo esempio implementa NaiveSessionCache che usa lo spazio di archiviazione della sessione HTTP per la memorizzazione dei token nella cache.This sample implements the NaiveSessionCache which uses http session storage to cache tokens.

Chiamare l'API WebCall the Web API

È ora possibile usare il token di accesso acquisito al passaggio 3.Now it's time to actually use the access_token you acquired in step 3. Aprire il file Controllers\TodoListController.cs dell'app Web, che esegue tutte le richieste CRUD all'API To Do List.Open the web app's Controllers\TodoListController.cs file, which makes all the CRUD requests to the To-Do List API.

  • È possibile usare nuovamente MSAL per recuperare i token di accesso dalla cache MSAL.You can use MSAL again here to fetch access_tokens from the MSAL cache. Per prima cosa aggiungere un'istruzione using per MSAL a questo file.First, add a using statement for MSAL to this file.

    using Microsoft.Identity.Client;

  • Nell'azione Index usare il metodo AcquireTokenSilentAsync di MSAL per ottenere un token di accesso da usare per leggere i dati dal servizio To Do List:In the Index action, use MSAL's AcquireTokenSilentAsync method to get an access_token that can be used to read data from the To-Do List service:
// ...
string userObjectID = ClaimsPrincipal.Current.FindFirst("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier").Value;
string tenantID = ClaimsPrincipal.Current.FindFirst("http://schemas.microsoft.com/identity/claims/tenantid").Value;
string authority = String.Format(CultureInfo.InvariantCulture, Startup.aadInstance, tenantID, string.Empty);
ClientCredential credential = new ClientCredential(Startup.clientId, Startup.clientSecret);

// Here you ask for a token using the web app's clientId as the scope, since the web app and service share the same clientId.
app = new ConfidentialClientApplication(Startup.clientId, redirectUri, credential, new NaiveSessionCache(userObjectID, this.HttpContext)){};
result = await app.AcquireTokenSilentAsync(new string[] { Startup.clientId });
// ...
  • L'esempio aggiunge quindi il token risultante alla richiesta HTTP GET come intestazione Authorization, usata dal servizio To Do List per autenticare la richiesta.The sample then adds the resulting token to the HTTP GET request as the Authorization header, which the To-Do List service uses to authenticate the request.
  • Se il servizio To Do List restituisce una risposta 401 Unauthorized, significa che i token di accesso in MSAL per qualche motivo non sono più validi.If the To-Do List service returns a 401 Unauthorized response, the access_tokens in MSAL have become invalid for some reason. In questo caso, è consigliabile eliminare tutti i token di accesso dalla cache MSAL e visualizzare all'utente un messaggio che comunica che potrebbe essere necessario eseguire un nuovo accesso. In questo modo verrà riavviato il flusso di acquisizione dei token.In this case, you should drop any access_tokens from the MSAL cache and show the user a message that they may need to sign in again, which will restart the token acquisition flow.
// ...
// If the call failed with access denied, then drop the current access token from the cache,
// and show the user an error indicating they might need to sign-in again.
if (response.StatusCode == System.Net.HttpStatusCode.Unauthorized)
{
        app.AppTokenCache.Clear(Startup.clientId);

        return new RedirectResult("/Error?message=Error: " + response.ReasonPhrase + " You might need to sign in again.");
}
// ...
  • Analogamente, se per qualsiasi motivo MSAL non riesce a restituire un token di accesso, è consigliabile chiedere all'utente di eseguire di nuovo l'accesso.Similarly, if MSAL is unable to return an access_token for any reason, you should instruct the user to sign in again. Questo è semplice quanto individuare eventuali MSALException:This is as simple as catching any MSALException:
// ...
catch (MsalException ee)
{
        // If MSAL could not get a token silently, show the user an error indicating they might need to sign in again.
        return new RedirectResult("/Error?message=An Error Occurred Reading To Do List: " + ee.Message + " You might need to log out and log back in.");
}
// ...
  • La stessa identica chiamata AcquireTokenSilentAsync viene implementata nelle azioni Create e Delete.The exact same AcquireTokenSilentAsync call is implementd in the Create and Delete actions. Nelle app Web è possibile usare questo metodo MSAL per ottenere i token di accesso ogni volta che sono necessari nell'app.In web apps, you can use this MSAL method to get access_tokens whenever you need them in your app. L'acquisizione, la memorizzazione nella cache e l'aggiornamento dei token vengono gestiti da MSAL.MSAL will take care of acquiring, caching, and refreshing tokens for you.

Infine compilare ed eseguire l'app.Finally, build and run your app! Accedere con un account Microsoft o con un account Azure AD e osservare che l'identità dell'utente sia visibile nella barra di spostamento superiore.Sign in with either a Microsoft Account or an Azure AD Account, and notice how the user's identity is reflected in the top navigation bar. Aggiungere ed eliminare alcuni elementi dall'elenco di attività dell'utente per vedere le chiamate API protette OAuth 2.0 in azione.Add and delete some items from the user's To-Do List to see the OAuth 2.0 secured API calls in action. Sono ora disponibili un'app e un'API Web protette che usano protocolli standard del settore in grado di autenticare gli utenti con account personali, aziendali e dell'istituto di istruzione.You now have a web app & web API, both secured using industry standard protocols, that can authenticate users with both their personal and work/school accounts.

Come riferimento, viene fornito l'esempio completato (senza i valori di configurazione) qui.For reference, the completed sample (without your configuration values) is provided here.

Fasi successiveNext Steps

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.