Configurar a autenticação em um aplicativo Web de exemplo que chama uma API Web usando o Azure AD B2C

  • Artigo

Este artigo usa um exemplo de aplicativo Web ASP.NET que chama uma API Web para ilustrar como adicionar a autenticação do Azure Ative Directory B2C (Azure AD B2C) aos seus aplicativos Web.

Importante

O exemplo ASP.NET aplicativo Web mencionado neste artigo é usado para chamar uma API da Web com um token de portador. Para um aplicativo Web que não chama uma API Web, consulte Configurar a autenticação em um aplicativo Web de exemplo usando o Azure AD B2C.

Descrição geral

OpenID Connect (OIDC) é um protocolo de autenticação que é construído em OAuth 2.0. Você pode usar o OIDC para entrar com segurança um usuário em um aplicativo. Este exemplo de aplicativo Web usa o Microsoft Identity Web. O Microsoft Identity Web é um conjunto de bibliotecas ASP.NET Core que simplificam a adição de suporte de autenticação e autorização a aplicativos Web que podem chamar uma API Web segura.

O fluxo de entrada envolve as seguintes etapas:

  1. Os utilizadores vão para a aplicação Web e selecionam Iniciar sessão.

  2. O aplicativo inicia uma solicitação de autenticação e redireciona os usuários para o Azure AD B2C.

  3. Os utilizadores registam-se ou iniciam sessão erepõem a palavra-passe. Em alternativa, podem iniciar sessão com uma conta social.

  4. Depois que os usuários entrarem, o Azure AD B2C retorna um código de autorização para o aplicativo.

  5. Em seguida, o aplicativo faz o seguinte:

    a. Ele troca o código de autorização para um token de ID, token de acesso e token de atualização.
    b. Ele lê as declarações de token de ID e persiste um cookie de autorização de aplicativo.
    c. Ele armazena o token de atualização em um cache na memória para uso posterior.

Visão geral do registro do aplicativo

Para permitir que seu aplicativo entre com o Azure AD B2C e chame uma API Web, registre dois aplicativos no diretório do Azure AD B2C.

  • O registro do aplicativo Web permite que seu aplicativo entre com o Azure AD B2C. Durante o registro, você especifica o URI de redirecionamento. O URI de redirecionamento é o ponto de extremidade para o qual os usuários são redirecionados pelo Azure AD B2C após a conclusão da autenticação com o Azure AD B2C. O processo de registro do aplicativo gera uma ID do aplicativo, também conhecida como ID do cliente, que identifica exclusivamente seu aplicativo. Você também cria um segredo do cliente, que seu aplicativo usa para adquirir os tokens com segurança.

  • O registro da API da Web permite que seu aplicativo chame uma API da Web segura. O registro inclui os escopos da API da Web. Os escopos fornecem uma maneira de gerenciar permissões para recursos protegidos, como sua API da Web. Você concede permissões ao aplicativo Web para os escopos da API da Web. Quando um token de acesso é solicitado, seu aplicativo especifica as permissões desejadas no parâmetro de escopo da solicitação.

A arquitetura e os registros do aplicativo são ilustrados no diagrama a seguir:

Diagram of a web app with web API call registrations and tokens.

Chamada para uma API da Web

Depois que a autenticação é concluída, os usuários interagem com o aplicativo, que invoca uma API da Web protegida. A API da Web usa autenticação de token de portador. O token de portador é o token de acesso que o aplicativo obteve do Azure AD B2C. O aplicativo passa o token no cabeçalho de autorização da solicitação HTTPS.

Authorization: Bearer <access token>

Se o escopo do token de acesso não corresponder aos escopos da API da Web, a biblioteca de autenticação obterá um novo token de acesso com os escopos corretos.

Terminar sessão

O fluxo de saída envolve as seguintes etapas:

  1. A partir da aplicação, os utilizadores terminam sessão.
  2. O aplicativo limpa seus objetos de sessão e a biblioteca de autenticação limpa seu cache de token.
  3. O aplicativo leva os usuários ao ponto de extremidade de saída do Azure AD B2C para encerrar a sessão do Azure AD B2C.
  4. Os usuários são redirecionados de volta para o aplicativo.

Pré-requisitos

Um computador que esteja executando:

Etapa 1: Configurar o fluxo de usuários

Quando os usuários tentam entrar em seu aplicativo, o aplicativo inicia uma solicitação de autenticação para o ponto de extremidade de autorização por meio de um fluxo de usuário. O fluxo do usuário define e controla a experiência do usuário. Depois que os usuários concluem o fluxo de usuários, o Azure AD B2C gera um token e, em seguida, redireciona os usuários de volta para seu aplicativo.

Se ainda não tiver feito isso, crie um fluxo de usuário ou uma política personalizada. Repita as etapas para criar três fluxos de usuário separados da seguinte maneira:

  • Um fluxo de usuário combinado de login e inscrição , como susi. Esse fluxo de usuário também suporta a experiência Esqueceu sua senha .
  • Um fluxo de usuário de edição de perfil, como edit_profile.
  • Um fluxo de usuário de redefinição de senha, como reset_password.

O Azure AD B2C precede o nome do fluxo de B2C_1_ usuário. Por exemplo, susi passa a B2C_1_susi.

Passo 2: Registar aplicações Web

Nesta etapa, você cria o aplicativo Web e o registro do aplicativo de API Web e especifica os escopos de sua API Web.

Etapa 2.1: Registrar o aplicativo de API da Web

Para criar o registro do aplicativo de API da Web (ID do aplicativo: 2), siga estas etapas:

  1. Inicie sessão no portal do Azure.

  2. Verifique se você está usando o diretório que contém seu locatário do Azure AD B2C. Selecione o ícone Diretórios + assinaturas na barra de ferramentas do portal.

  3. Nas configurações do Portal | Página Diretórios + assinaturas , localize seu diretório do Azure AD B2C na lista Nome do diretório e selecione Alternar.

  4. No portal do Azure, procure e selecione Azure AD B2C.

  5. Selecione Registos de aplicações e, em seguida, selecione Novo registo.

  6. Em Name, insira um nome para o aplicativo (por exemplo, my-api1). Deixe os valores padrão para URI de redirecionamento e tipos de conta suportados.

  7. Selecione Registar.

  8. Depois que o registro do aplicativo for concluído, selecione Visão geral.

  9. Registre o valor da ID do aplicativo (cliente) para uso posterior ao configurar o aplicativo Web.

    Screenshot that demonstrates how to get a web A P I application I D.

Etapa 2.2: Configurar escopos de aplicativo de API Web

  1. Selecione o aplicativo my-api1 que você criou (ID do aplicativo: 2) para abrir a página Visão geral.

  2. Em Gerenciar, selecione Expor uma API.

  3. Ao lado de URI da ID do aplicativo, selecione o link Definir. Substitua o valor padrão (GUID) por um nome exclusivo (por exemplo, tasks-api) e selecione Salvar.

    Quando seu aplicativo Web solicita um token de acesso para a API da Web, ele deve adicionar esse URI como o prefixo para cada escopo que você define para a API.

  4. Em Escopos definidos por esta API, selecione Adicionar um escopo.

  5. Para criar um escopo que defina o acesso de leitura à API:

    1. Em Nome do escopo, insira tasks.read.
    2. Para Nome de exibição do consentimento do administrador, insira API de acesso de leitura às tarefas.
    3. Para Descrição do consentimento do administrador, insira Permite acesso de leitura à API de tarefas.

  6. Selecione Adicionar escopo.

  7. Selecione Adicionar um escopo e adicione um escopo que defina o acesso de gravação à API:

    1. Em Nome do escopo, insira tasks.write.
    2. Para Nome de exibição do consentimento do administrador, digite Acesso de gravação à API de tarefas.
    3. Para Descrição do consentimento do administrador, insira Permite acesso de gravação à API de tarefas.

  8. Selecione Adicionar escopo.

Etapa 2.3: Registrar o aplicativo Web

Para criar o registro do aplicativo Web, faça o seguinte:

  1. Selecione Registos de aplicações e, em seguida, selecione Novo registo.

  2. Em Nome, insira um nome para o aplicativo (por exemplo, webapp1).

  3. Em Tipos de conta suportados, selecione Contas em qualquer provedor de identidade ou diretório organizacional (para autenticar usuários com fluxos de usuários).

  4. Em Redirecionar URI, selecione Web e, na caixa URL, digite https://localhost:5000/signin-oidc.

  5. Em Permissões, marque a caixa de seleção Conceder consentimento de administrador para permissões de acesso openid e offline.

  6. Selecione Registar.

  7. Depois que o registro do aplicativo for concluído, selecione Visão geral.

  8. Registre o ID do aplicativo (cliente) para uso posterior, quando você configurar o aplicativo Web.

    Screenshot of the web app Overview page for recording your web application ID.

Etapa 2.4: Criar um segredo do cliente do aplicativo Web

Crie um segredo de cliente para o aplicativo Web registrado. O aplicativo Web usa o segredo do cliente para provar sua identidade quando solicita tokens.

  1. Em Gerenciar, selecione Certificados & segredos.
  2. Selecione Novo segredo do cliente.
  3. Na caixa Descrição, insira uma descrição para o segredo do cliente (por exemplo, clientsecret1).
  4. Em Expira, selecione uma duração para a qual o segredo é válido e, em seguida, selecione Adicionar.
  5. Registre o valor do segredo. Você usará esse valor para configuração em uma etapa posterior.

Etapa 2.5: Conceder permissões ao aplicativo Web para a API da Web

Para conceder permissões ao seu aplicativo (ID do aplicativo: 1), siga estas etapas:

  1. Selecione Registos de aplicações e, em seguida, selecione a aplicação que criou (ID da aplicação: 1).

  2. Em Gerenciar, selecione Permissões de API.

  3. Em Permissões configuradas, selecione Adicionar uma permissão.

  4. Selecione a guia Minhas APIs .

  5. Selecione a API (ID do aplicativo: 2) à qual o aplicativo Web deve ter acesso. Por exemplo, digite my-api1.

  6. Em Permissão, expanda tarefas e selecione os escopos definidos anteriormente (por exemplo, tasks.read e tasks.write).

  7. Selecione Adicionar permissões.

  8. Selecione Conceder consentimento de administrador para <o nome> do seu inquilino.

  9. Selecione Yes (Sim).

  10. Selecione Atualizar e verifique se Concedido para ... aparece em Status para ambos os escopos.

  11. Na lista Permissões configuradas, selecione seu escopo e copie o nome completo do escopo.

    Screenshot of the configured permissions pane, showing that read access permissions are granted.

Etapa 3: Obter o exemplo de aplicativo Web

Baixe o arquivo zip ou execute o seguinte comando Bash para clonar o aplicativo Web de exemplo do GitHub.

git clone https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2

Extraia o arquivo de exemplo para uma pasta onde o comprimento total do caminho é de 260 ou menos caracteres.

Etapa 4: Configurar a API Web de exemplo

Na pasta de exemplo, na pasta 4-WebApp-your-API/4-2-B2C/TodoListService, abra o projeto TodoListService.csproj com Visual Studio ou Visual Studio Code.

Na pasta raiz do projeto, abra o arquivo appsettings.json . Este arquivo contém informações sobre seu provedor de identidade do Azure AD B2C. O aplicativo de API Web usa essas informações para validar o token de acesso que o aplicativo Web passa como um token de portador. Atualize as seguintes propriedades das configurações do aplicativo:

Secção Key valor
AzureAdB2C Instância A primeira parte do nome do locatário do Azure AD B2C. Por exemplo, https://contoso.b2clogin.com.
AzureAdB2C Domínio Seu nome completo de locatário do Azure AD B2C. Por exemplo, contoso.onmicrosoft.com.
AzureAdB2C ClientId O ID do aplicativo de API da Web da etapa 2.1.
AzureAdB2C SignUpSignInPolicyId Os fluxos de usuário ou a política personalizada que você criou na etapa 1.

Seu arquivo de configuração final deve se parecer com o seguinte arquivo JSON:

{
  "AzureAdB2C": {
    "Instance": "https://contoso.b2clogin.com",
    "Domain": "contoso.onmicrosoft.com",
    "ClientId": "<web-api-app-application-id>",
    "SignedOutCallbackPath": "/signout/<your-sign-up-in-policy>",
    "SignUpSignInPolicyId": "<your-sign-up-in-policy>"
  },
  // More settings here
}

Etapa 4.1: Definir a política de permissão

A API da Web verifica se o usuário se autenticou com o token de portador e se o token de portador tem os escopos aceitos configurados. Se o token portador não tiver nenhum desses escopos aceitos, a API da Web retornará o código de status HTTP 403 (Proibido) e gravará no corpo da resposta uma mensagem informando quais escopos são esperados no token.

Para configurar os escopos aceitos, abra a Controller/TodoListController.cs classe e defina o nome do escopo, sem o URI completo.

[RequiredScope("tasks.read")]

Etapa 4.2: Executar o aplicativo de API Web de exemplo

Para permitir que o aplicativo Web chame o exemplo de API Web, execute a API Web fazendo o seguinte:

  1. Se você for solicitado a fazer isso, restaure as dependências.
  2. Crie e execute o projeto.
  3. Depois que o projeto é criado, Visual Studio ou Visual Studio Code inicia a API da Web nos navegadores com o seguinte endereço: https://localhost:44332.

Etapa 5: Configurar o aplicativo Web de exemplo

Na pasta de exemplo, na 4-WebApp-your-API/4-2-B2C/Client pasta, abra o projeto TodoListClient.csproj com Visual Studio ou Visual Studio Code.

Na pasta raiz do projeto, abra o appsettings.json arquivo. Este arquivo contém informações sobre seu provedor de identidade do Azure AD B2C. O aplicativo Web usa essas informações para estabelecer uma relação de confiança com o Azure AD B2C, entrar e sair de usuários, adquirir tokens e validá-los. Atualize as seguintes propriedades das configurações do aplicativo:

Secção Key valor
AzureAdB2C Instância A primeira parte do nome do locatário do Azure AD B2C (por exemplo, https://contoso.b2clogin.com).
AzureAdB2C Domínio Seu nome completo de locatário do Azure AD B2C (por exemplo, contoso.onmicrosoft.com).
AzureAdB2C ClientId O ID do aplicativo Web da etapa 2.3.
AzureAdB2C ClientSecret O segredo do aplicativo Web da etapa 2.4.
AzureAdB2C SignUpSignInPolicyId Os fluxos de usuário ou a política personalizada que você criou na etapa 1.
TodoList TodoListScope Os escopos da API da Web criados na etapa 2.5.
TodoList TodoListBaseAddress O URI base da sua API da Web (por exemplo https://localhost:44332).

Seu arquivo de configuração final deve se parecer com o seguinte JSON:

{
  "AzureAdB2C": {
    "Instance": "https://contoso.b2clogin.com",
    "Domain": "contoso.onmicrosoft.com",
    "ClientId": "<web-app-application-id>",
    "ClientSecret": "<web-app-application-secret>",  
    "SignedOutCallbackPath": "/signout/<your-sign-up-in-policy>",
    "SignUpSignInPolicyId": "<your-sign-up-in-policy>"
  },
  "TodoList": {
    "TodoListScope": "https://contoso.onmicrosoft.com/api/demo.read",
    "TodoListBaseAddress": "https://localhost:44332"
  }
}

Etapa 6: Executar o aplicativo Web de exemplo

  1. Crie e execute o projeto.
  2. Navegue para https://localhost:5000.
  3. Conclua o processo de inscrição ou login.

Após a autenticação bem-sucedida, você verá seu nome para exibição na barra de navegação. Para exibir as declarações que o token do Azure AD B2C retorna ao seu aplicativo, selecione TodoList.

Screenshot of the web app token claims.

Implementar a sua aplicação

Em um aplicativo de produção, o URI de redirecionamento de registro do aplicativo geralmente é um ponto de extremidade acessível publicamente onde seu aplicativo está sendo executado, como https://contoso.com/signin-oidc.

Você pode adicionar e modificar URIs de redirecionamento em seus aplicativos registrados a qualquer momento. As seguintes restrições se aplicam aos URIs de redirecionamento:

  • O URL de resposta deve começar com o esquema https.
  • O URL de resposta diferencia maiúsculas de minúsculas. Seu caso deve corresponder ao caso do caminho da URL do seu aplicativo em execução.

Cache de token para um aplicativo Web

O exemplo de aplicativo Web usa serialização de cache de token na memória. Esta implementação é ótima em amostras. Também é bom em aplicativos de produção, desde que você não se importe se o cache de token for perdido quando o aplicativo Web for reiniciado.

Para o ambiente de produção, recomendamos o uso de um cache de memória distribuído. Por exemplo, cache Redis, NCache ou um cache do SQL Server. Para obter detalhes sobre as implementações de cache de memória distribuída, consulte Serialização de cache de token.

Próximos passos