Proteção de API

Quando você, como desenvolvedor, protege sua API, seu foco está na autorização. Para chamar a API do seu recurso, os aplicativos precisam adquirir autorização de aplicativo. O próprio recurso deve impor a autorização. Neste artigo, você aprenderá as práticas recomendadas para proteger sua API por meio de registro, definição de permissões e consentimento e imposição de acesso para atingir suas metas de Zero Trust .

Registre sua API protegida

Para proteger sua API com o Microsoft Entra ID (Microsoft Entra ID), você primeiro registrará sua API, após o que poderá gerenciar suas APIs registradas. No Microsoft Entra ID, uma API é um aplicativo com configurações específicas de registro de aplicativo que o definem como um recurso ou API que outro aplicativo pode ser autorizado a acessar. No centro de administração do Microsoft Entra, Microsoft Identity Developer, Registros de aplicativos, são APIs que estão no locatário como APIs de linha de negócios ou serviços de provedores de SaaS que têm APIs que o Microsoft Entra ID protege.

Durante o registro, você define como os aplicativos de chamada fazem referência à sua API e suas permissões delegadas e de aplicativo. Um registro de aplicativo pode representar uma solução que tenha aplicativos cliente e APIs. No entanto, neste artigo, abordamos o cenário em que um recurso autônomo expõe uma API.

Normalmente, uma API não realiza autenticação ou solicita autorização diretamente. A API valida um token que o aplicativo de chamada apresenta. As APIs não têm entradas interativas, portanto, você não precisa registrar configurações como URI de redirecionamento ou tipo de aplicativo. As APIs obtêm seus tokens dos aplicativos que estão chamando essas APIs, não interagindo com o Microsoft Entra ID. Para APIs da Web, use tokens de acesso OAuth2 para autorização. As APIs da Web validam tokens de portador para autorizar chamadores. Não aceite tokens de identificação como prova de permissão.

Por padrão, o Microsoft Entra ID adiciona User.Read às permissões de API de qualquer novo registro de aplicativo. Você remove essa permissão para a maioria das APIs da Web. O Microsoft Entra ID requer permissões de API somente quando uma API chama outra API. Se sua API não chamar outra API, remova a User.Read permissão quando você registrar sua API.

Você precisa de um identificador exclusivo para sua API, conhecido como URI de ID do aplicativo, que os aplicativos cliente que precisam acessar sua API pedem permissão para chamar sua API. O URI da ID do Aplicativo precisa ser exclusivo em todos os locatários do Microsoft Entra. Você pode usar api://<clientId> (a sugestão padrão no portal), onde <clientId> é o ID do aplicativo da sua API registrada.

Para fornecer aos desenvolvedores que estão chamando sua API um nome mais amigável, você pode usar o endereço da API como seu URI de ID do aplicativo. Por exemplo, você pode usar https://API.yourdomain.com onde yourdomain.com deve ser um domínio de editor configurado em seu locatário do Microsoft Entra. A Microsoft valida que você tem a propriedade do domínio para que você possa usá-lo como o identificador exclusivo para sua API. Você não precisa ter código neste endereço. A API pode estar onde você quiser, mas é uma boa prática usar o endereço HTTPS da API como o URI da ID do aplicativo.

Definir permissões delegadas com o mínimo de privilégios

Se sua API for chamada por aplicativos que tenham usuários, você deverá definir pelo menos uma permissão delegada (consulte Adicionar um escopo no registro do aplicativo Expor uma API).

As APIs que fornecem acesso aos armazenamentos de dados da organização podem atrair a atenção de invasores que desejam acessar esses dados. Em vez de ter apenas uma permissão delegada, projete suas permissões com o princípio Zero Trust de acesso com privilégios mínimos em mente. Pode ser difícil entrar em um modelo menos privilegiado mais tarde se todos os aplicativos cliente começarem com acesso privilegiado total.

Muitas vezes, os desenvolvedores caem em um padrão de usar uma única permissão, como "acesso como usuário" ou "representação do usuário" (que é uma frase comum, embora tecnicamente imprecisa). Permissões únicas como essas só permitem acesso total e privilegiado à sua API.

Declare escopos de privilégios mínimos para que seus aplicativos não sejam vulneráveis a comprometimento ou usados para executar uma tarefa que você nunca pretendia. Defina seus vários escopos em Permissões de API. Por exemplo, separe os escopos da leitura e atualização de dados e considere oferecer permissões somente leitura. "Acesso de gravação" inclui privilégios para operações de criação, atualização e exclusão. Um cliente nunca deve exigir acesso de gravação apenas para ler dados.

Considere as permissões de acesso "padrão" e "total" quando sua API trabalhar com dados confidenciais. Restrinja as propriedades confidenciais para que uma permissão padrão não permita acesso (por exemplo, Resource.Read). Em seguida, implemente uma permissão de acesso "total" (por exemplo, Resource.ReadFull) que retorna propriedades e informações confidenciais.

Sempre avalie as permissões solicitadas para garantir que você busque o conjunto de privilégios mínimos absolutos para realizar o trabalho. Evite solicitar permissões de privilégios mais altos. Em vez disso, crie uma permissão individual para cada cenário principal. Consulte a referência de permissões do Microsoft Graph para obter bons exemplos dessa abordagem. Localize e use apenas o número certo de permissões para atender às suas necessidades.

Definir o consentimento do usuário e o consentimento do administrador

Como parte de suas definições de escopo, decida se o intervalo de operação que pode ser executado com um escopo específico requer o consentimento do administrador.

Como designer de API, você pode fornecer orientação sobre quais escopos podem exigir apenas o consentimento do usuário com segurança. No entanto, os administradores de locatários podem configurar um locatário para que todas as permissões exijam o consentimento do administrador. Se você definir um escopo como exigindo o consentimento do administrador, a permissão sempre exigirá o consentimento do administrador.

Ao decidir sobre o consentimento do usuário ou administrador, você tem duas considerações principais:

1. Se o intervalo de operações por trás da permissão afeta mais de um único usuário. Se a permissão permitir que o usuário escolha qual aplicativo pode acessar apenas suas próprias informações, o consentimento do usuário pode ser apropriado. Por exemplo, o usuário pode consentir em escolher seu aplicativo preferido para e-mail. No entanto, se as operações por trás da permissão envolverem mais de um único usuário (por exemplo, a visualização de perfis completos de usuários de outros usuários), defina essa permissão como exigindo o consentimento do administrador.

2. Se a gama de operações por trás da permissão tem um escopo amplo. Por exemplo, um escopo amplo é quando uma permissão permite que um aplicativo altere tudo em um locatário ou faça algo que pode ser irreversível. Um escopo amplo indica que você precisa do consentimento do administrador em vez do consentimento do usuário.

Erre pelo lado conservador e exija o consentimento do administrador se tiver dúvidas. Descreva de forma clara e concisa as consequências do consentimento em suas cadeias de permissão. Suponha que o indivíduo que lê suas cadeias de caracteres de descrição não tenha familiaridade com suas APIs ou produto.

Evite adicionar suas APIs às permissões existentes de uma forma que altere a semântica da permissão. A sobrecarga das permissões existentes dilui o raciocínio sobre o qual os clientes previamente concederam consentimento.

Definir permissões de aplicativo

Ao criar aplicativos que não são de usuário, você não tem um usuário a quem possa solicitar um nome de usuário e senha ou MFA (Multifactor Authentication). Se aplicativos sem usuários (como cargas de trabalho, serviços e daemons) chamarem sua API, você deverá definir permissões de aplicativo para sua API. Ao definir uma permissão de aplicativo, você usa uma função de aplicativo em vez de usar escopos.

Assim como acontece com as permissões delegadas, você fornece permissões granulares de aplicativos para que as cargas de trabalho que chamam sua API possam seguir o acesso com privilégios mínimos e se alinhar aos princípios de Confiança Zero. Evite publicar apenas uma função de aplicativo (permissão de aplicativo) e um escopo (permissão delegada) ou expor todas as operações para cada cliente.

As cargas de trabalho são autenticadas com credenciais de cliente e solicitam um token usando o escopo, .default conforme demonstrado no código de exemplo a seguir.

// With client credentials flows the scopes is ALWAYS of the shape "resource/.default", as the 
// application permissions need to be set statically (in the portal or by PowerShell), 
// and then granted by a tenant administrator
string[] scopes = new string[] { "https://kkaad.onmicrosoft.com/webapi/.default" };
 
AuthenticationResult result = null;
try
{
  result = await app.AcquireTokenForClient(scopes)
    .ExecuteAsync();
  Console.WriteLine("Token acquired \n");
}
catch (MsalServiceException ex) when (ex.Message.Contains("AADSTS70011"))
{
  // Invalid scope. The scope has to be of the form "https://resourceurl/.default"
  // Mitigation: change the scope to be as expected
  Console.WriteLine("Scope provided is not supported");
}

As permissões exigem o consentimento do administrador quando não há nenhum usuário na frente do aplicativo e quando a permissão do aplicativo permite uma ampla gama de operações.

Impor acesso

Certifique-se de que suas APIs imponham o acesso validando e interpretando os tokens de acesso que os aplicativos de chamada fornecem como tokens de portador no cabeçalho de autorização da solicitação HTTPS. Você pode impor o acesso validando tokens, gerenciando a atualização de metadados e impondo escopos e funções, conforme descrito nas seções a seguir.

Validar tokens

Depois que sua API recebe um token, ela deve validar o token. A validação garante que o token venha do emissor adequado como inviolável e sem modificações. Verifique a assinatura porque você não obtém o token diretamente da ID do Microsoft Entra como faz com os tokens de ID. Valide a assinatura depois que sua API receber um token de uma fonte não confiável na rede.

Como há vulnerabilidades conhecidas em torno da verificação de assinatura de token da Web JSON, use uma biblioteca de validação de token padrão bem mantida e estabelecida. As bibliotecas de autenticação (como Microsoft.Identity.Web) usam as etapas apropriadas e atenuam vulnerabilidades conhecidas.

Opcionalmente, estenda a validação do token. Use a declaração de ID do locatário (tid) para restringir os locatários nos quais sua API pode obter um token. Use as azp declarações e appid para filtrar aplicativos que podem chamar sua API. Use a declaração de ID do objeto (oid) para restringir ainda mais o acesso a usuários individuais.

Gerenciar atualização de metadados

Certifique-se sempre de que sua biblioteca de validação de token gerencie efetivamente os metadados necessários. Nesse caso, os metadados são as chaves públicas, o par de chaves privadas, que a Microsoft usa para assinar tokens do Microsoft Entra. Quando suas bibliotecas validam esses tokens, elas obtêm nossa lista publicada de chaves de assinatura públicas de um endereço de Internet bem conhecido. Certifique-se de que o ambiente de hospedagem tenha o momento certo para obter essas chaves.

Por exemplo, bibliotecas mais antigas eram ocasionalmente codificadas para atualizar essas chaves de assinatura públicas a cada 24 horas. Considere quando o Microsoft Entra ID tem que girar rapidamente essas chaves e as chaves que você baixou não incluem as novas chaves giradas. Sua API pode ficar offline por um dia enquanto aguarda seu ciclo de atualização de metadados. Consulte diretrizes de atualização de metadados específicos para garantir que você obtenha os metadados corretamente. Se você estiver usando uma biblioteca, certifique-se de que ela trate esses metadados dentro de um prazo razoável.

Impor escopos e funções

Depois de validar seu token, sua API examina as declarações no token para determinar como ele deve funcionar.

Para tokens de permissão delegados, peça à sua API que inspecione a declaração de escopo (scp) para ver o que o aplicativo tem consentimento para fazer. Inspecione as declarações de ID de objeto (oid) ou chave de assunto (sub) para ver o usuário em nome do qual o aplicativo está funcionando.

Em seguida, faça sua verificação de API para garantir que o usuário também tenha acesso à operação solicitada. Se sua API definir funções para atribuir a usuários e grupos, peça à API que verifique se há declarações de funções no token e se comporte de acordo. Os tokens de permissão de aplicativo não têm uma declaração de escopo (scp). Em vez disso, peça à API que inspecione a declaração de funções para determinar quais permissões de aplicativo a carga de trabalho recebeu.

Depois que a API valida o token e os escopos e processa a ID do objeto (oid), a chave do assunto (sub) e as declarações de funções, a API pode retornar os resultados.

Próximos passos

• Exemplo de API protegida pela estrutura de consentimento de identidade da Microsoft ajuda você a projetar estratégias de permissões de aplicativo de privilégios mínimos para a melhor experiência do usuário.
• Chamar uma API de outra API ajuda você a garantir o Zero Trust quando você tem uma API que precisa chamar outra API e desenvolver seu aplicativo com segurança quando ele está trabalhando em nome de um usuário.
• Personalizar tokens descreve as informações que você pode receber nos tokens do Microsoft Entra. Ele explica como personalizar tokens para melhorar a flexibilidade e o controle e, ao mesmo tempo, aumentar a segurança de confiança zero do aplicativo com o menor privilégio.
• Configurar declarações de grupo e funções de aplicativo em tokens mostra como configurar seus aplicativos com definições de função de aplicativo e atribuir grupos de segurança a funções de aplicativo. Esses métodos ajudam a melhorar a flexibilidade e o controle e, ao mesmo tempo, aumentam a segurança de confiança zero do aplicativo com o menor privilégio.
• Adquirir autorização para acessar recursos ajuda você a entender a melhor forma de garantir o Zero Trust ao adquirir permissões de acesso a recursos para seu aplicativo.
• Solicitar permissões que exigem consentimento administrativo descreve a experiência de permissão e consentimento quando as permissões do aplicativo exigem consentimento administrativo.
• Neste Guia de início rápido: proteger uma API da Web com a plataforma de identidade da Microsoft, saiba como proteger uma API da Web ASP.NET restringindo o acesso aos seus recursos apenas a contas autorizadas.
• Neste Tutorial - Transformar e proteger sua API no Gerenciamento de API do Azure, saiba mais sobre como configurar políticas comuns para ocultar as informações da pilha de tecnologia ou as URLs originais na resposta HTTP da API.