Azure Active Directory B2C: criar uma API Web do .NETAzure Active Directory B2C: Build a .NET web API

Com o Active Directory B2C do Azure (AD do Azure), você pode proteger uma API Web usando tokens de acesso do OAuth 2.0.With Azure Active Directory (Azure AD) B2C, you can secure a web API by using OAuth 2.0 access tokens. Esses tokens permitem que os aplicativos cliente se autentiquem na API.These tokens allow your client apps to authenticate to the API. Este artigo mostra como criar uma API de "lista de tarefas pendentes" MVC .NET que permite que os usuários do aplicativo cliente executem CRUD para as tarefas.This article shows you how to create a .NET MVC "to-do list" API that allows users of your client application to CRUD tasks. A API Web é protegida usando o Azure AD B2C e permite que apenas usuários autenticados gerenciem sua lista de tarefas pendentes.The web API is secured using Azure AD B2C and only allows authenticated users to manage their to-do list.

Criar um diretório do AD B2C do AzureCreate an Azure AD B2C directory

Antes de usar AD B2C do Azure, você deve criar um diretório ou locatário.Before you can use Azure AD B2C, you must create a directory, or tenant. Um diretório é um contêiner para todos os seus usuários, aplicativos, grupos etc.A directory is a container for all of your users, apps, groups, and more. Se você ainda não tiver um, crie um diretório B2C antes de prosseguir neste guia.If you don't have one already, create a B2C directory before you continue in this guide.

Observação

O aplicativo cliente e a API Web devem usar o mesmo diretório do Azure AD B2C.The client application and web API must use the same Azure AD B2C directory.

Criar uma API da WebCreate a web API

Em seguida, você precisa criar um aplicativo de API Web no diretório B2C.Next, you need to create a web API app in your B2C directory. Isso fornece ao AD do Azure as informações de que ele precisa para se comunicar de forma segura com seu aplicativo.This gives Azure AD information that it needs to securely communicate with your app. Para criar um aplicativo, siga estas instruções.To create an app, follow these instructions. É necessário que você:Be sure to:

  • Inclua um aplicativo Web ou uma API Web no aplicativo.Include a web app or web API in the application.
  • Use o URI de redirecionamento https://localhost:44332/ para o aplicativo Web.Use the Redirect URI https://localhost:44332/ for the web app. Esse é o local padrão do aplicativo Web cliente para este exemplo de código.This is the default location of the web app client for this code sample.
  • Copie a ID de aplicativo atribuída ao aplicativo.Copy the Application ID that is assigned to your app. Você precisará dela mais tarde.You'll need it later.
  • Insira um identificador de aplicativo em URI da ID do aplicativo.Enter an app identifier into App ID URI. Copie o URI da ID do Aplicativo completo.Copy the full App ID URI. Você precisará dela mais tarde.You'll need it later.
  • Adicione permissões por meio do menu Escopos publicados.Add permissions through the Published scopes menu.

    Importante

    Não é possível usar aplicativos registrados na guia Aplicativos no Portal de Gerenciamento do Azure para fazer isso.You cannot use applications registered in the Applications tab on the classic Azure Management Portal for this.

Criar suas políticasCreate your policies

No AD B2C do Azure, cada experiência do usuário é definida por uma política.In Azure AD B2C, every user experience is defined by a policy. Você precisará criar uma política para se comunicar com o Azure AD B2C.You will need to create a policy to communicate with Azure AD B2C. É recomendável usar a política combinada de inscrição/entrada, conforme descrito no artigo de referência de política.We recommend using the combined sign-up/sign-in policy, as described in the policy reference article. Ao criar a política, não se esqueça de:When you create your policy, be sure to:

  • Escolher o Nome de exibição e outros atributos de inscrição na política.Choose Display name and other sign-up attributes in your policy.
  • Escolher as declarações Nome de exibição e ID de objeto como declarações de aplicativo para cada política.Choose Display name and Object ID claims as application claims for every policy. Você pode escolher outras declarações também.You can choose other claims as well.
  • Copie o Nome de cada política depois de criá-la.Copy the Name of each policy after you create it. Posteriormente, você precisará do nome da política.You'll need the policy name later.

Observação

No AD B2C do Azure, o nome da política será prefixado com b2c_1_, como b2c_1_sign_up.In Azure AD B2C, your policy's name will be prefixed with b2c_1_, like b2c_1_sign_up. Você é livre para usar as políticas em todos os seus aplicativos cliente e servidor.You are free to use your policies across all of your apps, both client and server. Se você criou anteriormente políticas em outro passo a passo do B2C, não é necessário fazê-lo novamente.If you've previously created policies in another B2C walk-through, there is no need to do so again. Você pode reutilizar as políticas que criou anteriormente no portal se elas correspondem aos requisitos do aplicativo.You may reuse the policies you've previously created in the portal if they match the requirements of the application.

Após criar a política com êxito, você estará pronto para compilar o aplicativo.After you have successfully created the policy, you're ready to build your app.

Baixar o códigoDownload the code

O código para este tutorial é mantido no GitHub.The code for this tutorial is maintained on GitHub. Você pode clonar a amostra executando:You can clone the sample by running:

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

Depois de baixar o código de exemplo, abra o arquivo .sln do Visual Studio para começar.After you download the sample code, open the Visual Studio .sln file to get started. Agora, sua solução contém dois projetos: TaskWebApp e TaskService.The solution file contains two projects: TaskWebApp and TaskService. TaskWebApp é um aplicativo Web de MVC com o qual o usuário interage.TaskWebApp is an MVC web application that the user interacts with. TaskService é API Web back-end do aplicativo que armazena a lista de tarefas de cada usuário.TaskService is the app's back-end web API that stores each user's to-do list. Este artigo discutirá apenas o aplicativo TaskService.This article will only discuss the TaskService application. Para saber como criar TaskWebApp usando o Azure AD B2C, confira nosso tutorial do aplicativo Web .NET.To learn how to build TaskWebApp using Azure AD B2C, see our .NET web app tutorial.

Atualizar a configuração do Azure AD B2CUpdate the Azure AD B2C configuration

O exemplo é configurado para usar as políticas e a ID do cliente da demonstração.Our sample is configured to use the policies and client ID of our demo tenant. Se quiser usar seu próprio locatário, você precisará fazer o seguinte:If you would like to use your own tenant, you will need to do the following:

  1. Abra web.config no projeto TaskService e substitua os valores deOpen web.config in the TaskService project and replace the values for

    • ida:Tenant pelo nome do locatárioida:Tenant with your tenant name
    • ida:ClientId com a ID do aplicativo de API da Webida:ClientId with your web API application ID
    • ida:SignUpSignInPolicyId pelo nome da política "Inscrever-se ou Entrar"ida:SignUpSignInPolicyId with your "Sign-up or Sign-in" policy name
  2. Abra web.config no projeto TaskWebApp e substitua os valores deOpen web.config in the TaskWebApp project and replace the values for

    • ida:Tenant pelo nome do locatárioida:Tenant with your tenant name
    • ida:ClientId pela ID de aplicativo do aplicativo Webida:ClientId with your web app application ID
    • ida:ClientSecret pela chave de segredo do aplicativo Webida:ClientSecret with your web app secret key
    • ida:SignUpSignInPolicyId pelo nome da política "Inscrever-se ou Entrar"ida:SignUpSignInPolicyId with your "Sign-up or Sign-in" policy name
    • ida:EditProfilePolicyId pelo nome de política "Editar Perfil"ida:EditProfilePolicyId with your "Edit Profile" policy name
    • ida:ResetPasswordPolicyId pelo nome de política "Redefinir Senha"ida:ResetPasswordPolicyId with your "Reset Password" policy name
    • api:ApiIdentifier com o “URI de ID do aplicativo"api:ApiIdentifier with your "App ID URI"

Proteger a APISecure the API

Quando tem um cliente que chama a API, você pode proteger a API (por exemplo TaskService) usando os tokens de portador 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. Isso garante que cada solicitação à API seja válida apenas se a solicitação tiver um token de portador.This ensures that each request to your API will only be valid if the request has a bearer token. Sua API pode aceitar e validar tokens de portador usando a biblioteca OWIN (Open Web Interface para .NET) da Microsoft.Your API can accept and validate bearer tokens by using Microsoft's Open Web Interface for .NET (OWIN) library.

Instalar a OWINInstall OWIN

Comece instalando o pipeline de autenticação OWIN OAuth usando o Visual Studio Package Manager Console.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

Isso instalará o middleware OWIN, que aceitará e validará os tokens de portador.This will install the OWIN middleware that will accept and validate bearer tokens.

Adicionar uma classe de inicialização da OWINAdd an OWIN startup class

Adicione uma classe de inicialização OWIN para a API chamada Startup.cs.Add an OWIN startup class to the API called Startup.cs. Clique com o botão direito do mouse no projeto, selecione Adicionar e Novo Item e pesquise OWIN.Right-click on the project, select Add and New Item, and then search for OWIN. O middleware OWIN invocará o método Configuration(…) quando seu aplicativo for iniciado.The OWIN middleware will invoke the Configuration(…) method when your app starts.

Em nossa amostra, alteramos a declaração de classe para public partial class Startup e implementamos a outra parte da classe em 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. No método Configuration, adicionamos uma chamada para ConfigureAuth, que é definida em Startup.Auth.cs.Inside the Configuration method, we added a call to ConfigureAuth, which is defined in Startup.Auth.cs. Após as modificações, Startup.cs é semelhante ao seguinte: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);
    }
}

Configurar a autenticação OAuth 2.0Configure OAuth 2.0 authentication

Abra o arquivo App_Start\Startup.Auth.cs e implemente o método ConfigureAuth(...).Open the file App_Start\Startup.Auth.cs, and implement the ConfigureAuth(...) method. Por exemplo, ele pode ser semelhante ao seguinte: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)))
            });
        }
    }

Proteger o controlador de tarefaSecure the task controller

Após a configuração do aplicativo para usar a autenticação OAuth 2.0, você pode proteger a API Web adicionando uma marca [Authorize] ao controlador de tarefa.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. Este é o controlador onde ocorre toda a manipulação da lista de tarefas, portanto, proteja todo o controlador no nível da classe.This is the controller where all to-do list manipulation takes place, so you should secure the entire controller at the class level. Você também pode adicionar a marca [Authorize] a ações individuais para obter um controle mais refinado.You can also add the [Authorize] tag to individual actions for more fine-grained control.

// Controllers\TasksController.cs

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

Obter informações de usuário do tokenGet user information from the token

TasksController armazena tarefas em um banco de dados, no qual cada tarefa tem um usuário associado que é o "proprietário" da tarefa.TasksController stores tasks in a database where each task has an associated user who "owns" the task. O proprietário é identificado pela ID de objetodo usuário.The owner is identified by the user's object ID. (É por isso que você precisa adicionar a ID do objeto como uma declaração de aplicativo em todas as suas políticas.)(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;
}

Validar as permissões no tokenValidate the permissions in the token

Um requisito comum para APIs Web é validar os “escopos” presentes no token.A common requirement for web APIs is to validate the "scopes" present in the token. Isso garante que o usuário consentiu em conceder as permissões necessárias para acessar o serviço de lista de tarefas pendentes.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"
        });
    }
    ...
}

Executar o aplicativo de exemploRun the sample app

Por fim, compile e execute TaskWebApp e TaskService.Finally, build and run both TaskWebApp and TaskService. Crie algumas tarefas na lista de tarefas do usuário e observe como elas são persistentes na API, mesmo depois que você para e reinicia o cliente.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.

Editar suas políticasEdit your policies

Depois de proteger uma API usando o AD B2C do Azure, experimente a política de Inscrição/Entrada e veja o efeito (ou a falta dele) na 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. Você pode manipular as declarações do aplicativo nas políticas e alterar as informações do usuário que estão disponíveis na API Web.You can manipulate the application claims in the policies and change the user information that is available in the web API. Quaisquer declarações que você adicionar estarão disponíveis para a API Web de MVC do .NET no objeto ClaimsPrincipal , conforme descrito acima.Any claims that you add will be available to your .NET MVC web API in the ClaimsPrincipal object, as described earlier in this article.