Azure Active Directory B2C: compilare un'API Web .NETAzure Active Directory B2C: Build a .NET web API

Azure Active Directory (Azure AD) B2C permette di proteggere un'API Web usando i token di accesso OAuth 2.0.With Azure Active Directory (Azure AD) B2C, you can secure a web API by using OAuth 2.0 access tokens. Questi token consentono alle app client di eseguire l'autenticazione all'API.These tokens allow your client apps to authenticate to the API. Questo articolo illustra come creare un'API "elenco attività" MVC .NET che consente agli utenti dell'applicazione client di eseguire azioni CRUD sulle attività.This article shows you how to create a .NET MVC "to-do list" API that allows users of your client application to CRUD tasks. L'API Web è protetta con Azure AD B2C e consente soltanto agli utenti autenticati di gestire il proprio elenco attività.The web API is secured using Azure AD B2C and only allows authenticated users to manage their to-do list.

Creare una directory Azure AD B2CCreate an Azure AD B2C directory

Prima di poter usare Azure AD B2C, è necessario creare una directory, o tenant.Before you can use Azure AD B2C, you must create a directory, or tenant. Una directory è un contenitore per utenti, app, gruppi e così via.A directory is a container for all of your users, apps, groups, and more. Se non è già stato fatto, creare una directory B2C prima di proseguire con questa guida.If you don't have one already, create a B2C directory before you continue in this guide.

Nota

L'applicazione client e l'API Web devono usare la stessa directory di Azure AD B2C.The client application and web API must use the same Azure AD B2C directory.

Creare un'API WebCreate a web API

Successivamente, è necessario creare un'app per le API Web nella directory B2C.Next, you need to create a web API app in your B2C directory. In questo modo Azure AD acquisisce le informazioni necessarie per comunicare in modo sicuro con l'app.This gives Azure AD information that it needs to securely communicate with your app. Per creare un'app, seguire questa procedura.To create an app, follow these instructions. Assicurarsi di:Be sure to:

  • Includere un'app Web o un'API Web nell'applicazione.Include a web app or web API in the application.
  • Usare l'URI di reindirizzamento https://localhost:44332/ per l'app Web.Use the Redirect URI https://localhost:44332/ for the web app. Si tratta della posizione predefinita del client dell'app Web per questo codice di esempio.This is the default location of the web app client for this code sample.
  • Copiare l' ID applicazione assegnato all'app.Copy the Application ID that is assigned to your app. Sarà necessario più avanti.You'll need it later.
  • Immettere un identificatore app in URI ID app.Enter an app identifier into App ID URI. Copiare l'URI ID app completo.Copy the full App ID URI. Sarà necessario più avanti.You'll need it later.
  • Aggiungere le autorizzazioni tramite il menu Ambiti pubblicati.Add permissions through the Published scopes menu.

    Importante

    Non è possibile usare le applicazioni registrate nella scheda Applicazioni del portale di gestione di Azure per questa operazione.You cannot use applications registered in the Applications tab on the classic Azure Management Portal for this.

Creare i criteriCreate your policies

In Azure AD B2C ogni esperienza utente è definita da criterispecifici.In Azure AD B2C, every user experience is defined by a policy. Sarà necessario creare un criterio per comunicare con Azure AD B2C.You will need to create a policy to communicate with Azure AD B2C. È consigliabile usare i criteri di iscrizione/accesso combinati, come illustrato nell'articolo di riferimento sui criteri.We recommend using the combined sign-up/sign-in policy, as described in the policy reference article. Durante la creazione dei criteri, assicurarsi di:When you create your policy, be sure to:

  • Scegliere Nome visualizzato e altri attributi di iscrizione nei criteri.Choose Display name and other sign-up attributes in your policy.
  • Scegliere le attestazioni Nome visualizzato e ID oggetto come attestazioni dell'applicazione in tutti i criteri.Choose Display name and Object ID claims as application claims for every policy. È consentito scegliere anche altre attestazioni.You can choose other claims as well.
  • Copiare il Nome di ogni criterio dopo averlo creato.Copy the Name of each policy after you create it. Il nome dei criteri sarà necessario più avanti.You'll need the policy name later.

Nota

In Azure AD B2C, il nome del criterio verrà preceduto da b2c_1_, come b2c_1_sign_up.In Azure AD B2C, your policy's name will be prefixed with b2c_1_, like b2c_1_sign_up. Si è liberi di utilizzare i criteri in tutte le app, sia client che server.You are free to use your policies across all of your apps, both client and server. Se sono stati creati in precedenza criteri in un altra procedura B2C, non è necessario procedere nuovamente.If you've previously created policies in another B2C walk-through, there is no need to do so again. È possibile riutilizzare i criteri creati in precedenza nel portale se corrispondono ai requisiti dell'applicazione.You may reuse the policies you've previously created in the portal if they match the requirements of the application.

Dopo aver creato i criteri, è possibile passare alla compilazione dell'app.After you have successfully created the policy, you're ready to build your app.

Scaricare il codiceDownload the code

Il codice per questa esercitazione è salvato su GitHub.The code for this tutorial is maintained on GitHub. È possibile clonare l'esempio eseguendo:You can clone the sample by running:

git clone https://github.com/Azure-Samples/active-directory-b2c-dotnet-webapp-and-webapi.git

Dopo aver scaricato il codice di esempio, aprire il file SLN di Visual Studio per iniziare.After you download the sample code, open the Visual Studio .sln file to get started. Il file della soluzione contiene due progetti: TaskWebApp e TaskService.The solution file contains two projects: TaskWebApp and TaskService. TaskWebApp è un'applicazione Web MVC con cui l'utente interagisce.TaskWebApp is an MVC web application that the user interacts with. TaskService è l'API Web back-end dell'app in cui viene archiviato l'elenco attività di ogni utente.TaskService is the app's back-end web API that stores each user's to-do list. Questo articolo illustra solo l'applicazione TaskService.This article will only discuss the TaskService application. Per informazioni su come compilare TaskWebApp usando Azure AD B2C, vedere l'esercitazione sulle app Web .NET.To learn how to build TaskWebApp using Azure AD B2C, see our .NET web app tutorial.

Aggiornare la configurazione di Azure AD B2CUpdate the Azure AD B2C configuration

L'esempio è configurato per l'uso dei criteri e dell'ID client del tenant di demo.Our sample is configured to use the policies and client ID of our demo tenant. Se si vuole usare il proprio tenant, sarà necessario seguire questa procedura:If you would like to use your own tenant, you will need to do the following:

  1. Aprire web.config nel progetto TaskService e sostituire i valori seguenti:Open web.config in the TaskService project and replace the values for

    • ida:Tenant con il nome del tenantida:Tenant with your tenant name
    • ida:ClientId con l'ID dell'applicazione API Webida:ClientId with your web API application ID
    • ida:SignUpSignInPolicyId con il nome del criterio "di iscrizione o di accesso"ida:SignUpSignInPolicyId with your "Sign-up or Sign-in" policy name
  2. Aprire web.config nel progetto TaskWebApp e sostituire i valori diOpen web.config in the TaskWebApp project and replace the values for

    • ida:Tenant con il nome del tenantida:Tenant with your tenant name
    • ida:ClientId con l'ID dell'applicazione di tipo app Webida:ClientId with your web app application ID
    • ida:ClientSecret con la chiave privata dell'app Webida:ClientSecret with your web app secret key
    • ida:SignUpSignInPolicyId con il nome del criterio "Iscrizione o accesso"ida:SignUpSignInPolicyId with your "Sign-up or Sign-in" policy name
    • ida:EditProfilePolicyId con il nome del criterio "Modifica profilo"ida:EditProfilePolicyId with your "Edit Profile" policy name
    • ida:ResetPasswordPolicyId con il nome del criterio "Reimposta password"ida:ResetPasswordPolicyId with your "Reset Password" policy name
    • api:ApiIdentifier con "URI ID app"api:ApiIdentifier with your "App ID URI"

Proteggere l'APISecure the API

Quando è disponibile un client che chiama l'API, è possibile proteggere l'API, ad esempio TaskService, usando i token di connessione OAuth 2.0.When you have a client that calls your API, you can secure your API (e.g TaskService) by using OAuth 2.0 bearer tokens. In questo modo si assicura che ogni richiesta all'API sarà valida solo se la richiesta include un token di connessione.This ensures that each request to your API will only be valid if the request has a bearer token. L'API può accettare e convalidare i token di connessione usando la libreria OWIN (Open Web Interface for .NET) di Microsoft.Your API can accept and validate bearer tokens by using Microsoft's Open Web Interface for .NET (OWIN) library.

Installare OWINInstall OWIN

Installare prima di tutto la pipeline di autenticazione OAuth OWIN usando la console di Gestione pacchetti di Visual Studio.Begin by installing the OWIN OAuth authentication pipeline by using the Visual Studio Package Manager Console.

PM> Install-Package Microsoft.Owin.Security.OAuth -ProjectName TaskService
PM> Install-Package Microsoft.Owin.Security.Jwt -ProjectName TaskService
PM> Install-Package Microsoft.Owin.Host.SystemWeb -ProjectName TaskService

Verrà installato il middleware OWIN che accetterà e convaliderà i token di connessione.This will install the OWIN middleware that will accept and validate bearer tokens.

Aggiungere una classe di avvio OWINAdd an OWIN startup class

Aggiungere una classe di avvio OWIN all'API denominata Startup.cs.Add an OWIN startup class to the API called Startup.cs. Fare clic con il pulsante destro del mouse sul progetto, scegliere Aggiungi e quindi Nuovo elemento e cercare "OWIN".Right-click on the project, select Add and 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.

In questo esempio la dichiarazione di classe è stata modificata in public partial class Startup ed è stata implementata l'altra parte della classe in App_Start\Startup.Auth.cs.In our sample, we changed the class declaration to public partial class Startup and implemented the other part of the class in App_Start\Startup.Auth.cs. Nel metodo Configuration è stata aggiunta una chiamata a ConfigureAuth, definita in Startup.Auth.cs.Inside the Configuration method, we added a call to ConfigureAuth, which is defined in Startup.Auth.cs. Dopo le modifiche, Startup.cs ha un aspetto analogo al seguente:After the modifications, Startup.cs looks like the following:

// Startup.cs

public partial class Startup
{
    // The OWIN middleware will invoke this method when the app starts
    public void Configuration(IAppBuilder app)
    {
        // ConfigureAuth defined in other part of the class
        ConfigureAuth(app);
    }
}

Configurare l'autenticazione OAuth 2.0Configure OAuth 2.0 authentication

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. Ad esempio può avere un aspetto simile al seguente:For example, it could look like the following:

// App_Start\Startup.Auth.cs

 public partial class Startup
    {
        // These values are pulled from web.config
        public static string AadInstance = ConfigurationManager.AppSettings["ida:AadInstance"];
        public static string Tenant = ConfigurationManager.AppSettings["ida:Tenant"];
        public static string ClientId = ConfigurationManager.AppSettings["ida:ClientId"];
        public static string SignUpSignInPolicy = ConfigurationManager.AppSettings["ida:SignUpSignInPolicyId"];
        public static string DefaultPolicy = SignUpSignInPolicy;

        /*
         * Configure the authorization OWIN middleware.
         */
        public void ConfigureAuth(IAppBuilder app)
        {
            TokenValidationParameters tvps = new TokenValidationParameters
            {
                // Accept only those tokens where the audience of the token is equal to the client ID of this app
                ValidAudience = ClientId,
                AuthenticationType = Startup.DefaultPolicy
            };

            app.UseOAuthBearerAuthentication(new OAuthBearerAuthenticationOptions
            {
                // This SecurityTokenProvider fetches the Azure AD B2C metadata & signing keys from the OpenIDConnect metadata endpoint
                AccessTokenFormat = new JwtFormat(tvps, new OpenIdConnectCachingSecurityTokenProvider(String.Format(AadInstance, Tenant, DefaultPolicy)))
            });
        }
    }

Proteggere il controller dell'attivitàSecure the task controller

Dopo aver configurato l'app per usare l'autenticazione OAuth 2.0, per proteggere l'API Web aggiungere un tag [Authorize] al controller dell'attività.After the app is configured to use OAuth 2.0 authentication, you can secure your web API by adding an [Authorize] tag to the task controller. Si tratta del controller in cui avvengono tutte le modifiche relative all'elenco attività. Sarà quindi necessario proteggere l'intero controller a livello della classe.This is the controller where all to-do list manipulation takes place, so you should secure the entire controller at the class level. È anche possibile aggiungere il tag [Authorize] a singole azioni per un controllo più specifico.You can also add the [Authorize] tag to individual actions for more fine-grained control.

// Controllers\TasksController.cs

[Authorize]
public class TasksController : ApiController
{
    ...
}

Ottenere le informazioni utente dal tokenGet user information from the token

TasksController archivia le attività in un database in cui a ogni attività è associato un utente "proprietario" dell'attività.TasksController stores tasks in a database where each task has an associated user who "owns" the task. Il proprietario è identificato dall' ID oggettodell'utente.The owner is identified by the user's object ID. Per questo motivo è necessario aggiungere l'ID oggetto come attestazione dell'applicazione in tutti i criteri.(This is why you needed to add the object ID as an application claim in all of your policies.)

// Controllers\TasksController.cs

public IEnumerable<Models.Task> Get()
{
    string owner = ClaimsPrincipal.Current.FindFirst("http://schemas.microsoft.com/identity/claims/objectidentifier").Value;
    IEnumerable<Models.Task> userTasks = db.Tasks.Where(t => t.owner == owner);
    return userTasks;
}

Convalidare le autorizzazioni nel tokenValidate the permissions in the token

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 un servizio di tipo "To Do List".This ensures that the user has consented to the permissions required to access the to-do list service.

public IEnumerable<Models.Task> Get()
{
    if (ClaimsPrincipal.Current.FindFirst("http://schemas.microsoft.com/identity/claims/scope").Value != "read")
    {
        throw new HttpResponseException(new HttpResponseMessage {
            StatusCode = HttpStatusCode.Unauthorized,
            ReasonPhrase = "The Scope claim does not contain 'read' or scope claim not found"
        });
    }
    ...
}

Eseguire l'app di esempioRun the sample app

Compilare ed eseguire infine TaskWebApp e TaskService.Finally, build and run both TaskWebApp and TaskService. Creare alcune attività nell'elenco attività dell'utente e osservarne la persistenza nell'API anche dopo l'arresto e il riavvio del client.Create some tasks on the user's to-do list and notice how they are persisted in the API even after you stop and restart the client.

Modificare i criteriEdit your policies

Dopo aver protetto l'API con Azure AD B2C, è possibile provare i criteri di iscrizione/di accesso dell'app e visualizzarne gli effetti o l'assenza di effetti nell'API.After you have secured an API by using Azure AD B2C, you can experiment with your Sign-in/Sign-up policy and view the effects (or lack thereof) on the API. È possibile modificare le attestazioni dell'applicazione nei criteri nonché le informazioni utente disponibili nell'API Web.You can manipulate the application claims in the policies and change the user information that is available in the web API. Le eventuali attestazioni aggiunte saranno disponibili per l'API Web MVC .NET nell'oggetto ClaimsPrincipal , come descritto in precedenza in questo articolo.Any claims that you add will be available to your .NET MVC web API in the ClaimsPrincipal object, as described earlier in this article.