API Protection

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

Registre sua API protegida

Para proteger sua API com o Microsoft Entra ID (Microsoft Entra ID), registre primeiro sua API e, em seguida, poderá gerenciar suas APIs registradas. No Microsoft Entra ID, uma API é um aplicativo com configurações de registro de aplicativo específicas que o definem como um recurso ou API que outro aplicativo pode ser autorizado a acessar. No centro de administração do Microsoft Entra, o 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 protegidas pelo Microsoft Entra ID.

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, nesse artigo, abordamos o cenário em que um recurso autónomo expõe uma API.

Normalmente, uma API não executa autenticação ou solicita autorização diretamente. A API valida um token apresentado pelo aplicativo de chamada. As APIs não têm logins interativos, 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 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 ID 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. A ID do Microsoft Entra requer permissões de API somente quando uma API chama outra API. Se a sua API não chamar outra API, remova a permissão User.Read ao registrar sua API.

Você precisa de um identificador exclusivo para sua API, conhecido como URI de ID do aplicativo, para que os aplicativos clientes que precisam acessar sua API solicitem 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), em que <clientId> é a ID do aplicativo da sua API registrada.

Para fornecer aos desenvolvedores que estão chamando sua API um nome mais amigável, você pode utilizar o endereço da API como seu URI de ID do aplicativo. Por exemplo, você pode usar https://API.yourdomain.com, em que yourdomain.com deve estar 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 utilizar o endereço HTTPS da API como o URI de ID do Aplicativo.

Defina permissões delegadas com menos privilégios

Se sua API for chamada por aplicativos que têm 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 a 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, crie suas permissões com o princípio da Confiança Zero 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 utilizar uma única permissão, como "acesso como usuário" ou "representação de 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 pretendeu. Defina seus vários escopos em Permissões da API. Por exemplo, separe escopos da leitura e atualização de dados e considere oferecer permissões somente leitura. O “acesso de gravação” inclui privilégios para operações de criação, atualização e exclusão. Um cliente nunca deve exigir o acesso de gravação somente para ler dados.

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

Sempre avalie as permissões solicitadas para garantir o conjunto absolutamente menos privilegiado 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 ver bons exemplos dessa abordagem. Localize e utilize apenas o número certo de permissões para atender às suas necessidades.

Definir consentimento do usuário e consentimento do administrador

Como parte das definições do seu escopo, decida se a faixa de operação que pode ser executada com um escopo específico exige o consentimento do administrador.

Como designer de API, você pode fornecer orientação sobre quais escopos podem exigir com segurança apenas o consentimento do usuário. 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 consentimento do administrador, a permissão sempre exigirá 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 poderá 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, exibindo perfis de usuário completos de outros usuários), defina essa permissão como exigindo 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 possa ser irreversível. Um escopo amplo indica que você precisa de consentimento do administrador em vez do consentimento do usuário.

Erre no lado conservador e exija o consentimento do administrador se estiver em dúvida. Descreva de forma clara e concisa as consequências do consentimento na 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 forma a alterar a semântica da permissão. A sobrecarga das permissões existentes dilui o raciocínio sobre o qual os clientes concederam consentimento anteriormente.

Definir permissões de aplicativos

Ao criar aplicativos que não são de usuário, você não tem um usuário a quem possa solicitar nome de usuário e senha ou autenticação multifator (MFA). 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 aplicativo 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 a cada cliente.

Cargas de trabalho são autenticadas com credenciais do 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 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.

Aplicar 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. É possível 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 esse token. A validação garante que o token venha do emissor adequado como não adulterado e não modificado. Verifique a assinatura porque você não obtém o token diretamente do Microsoft Entra ID 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, utilize uma biblioteca de validação de token padrão bem mantida e estabelecida. Bibliotecas de autenticação (como Microsoft.Identity.Web) usam as etapas adequadas e atenuam vulnerabilidades conhecidas.

Opcionalmente, estenda a validação de tokens. Use a declaração de ID do locatário (tid) para restringir os locatários nos quais a API pode obter um token. Use as declarações azp e appid para filtrar aplicativos que podem chamar sua API. Use a declaração de ID de 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 utiliza para assinar tokens do Microsoft Entra. Quando suas bibliotecas validam esses tokens, elas obtêm nossa lista publicada de chaves de assinatura pública de um endereço de Internet bem conhecido. Certifique-se de que o ambiente de hospedagem tenha o tempo 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 precisa girar rapidamente essas chaves e as chaves que você baixou não incluem as novas chaves rotacionadas. Sua API pode ficar offline por um dia enquanto aguarda seu ciclo de atualização de metadados. Consulte orientações específicas de atualização de metadados para garantir que você obtenha os metadados adequadamente. Se você estiver utilizando uma biblioteca, verifique se ela trata esses metadados dentro de um tempo razoável.

Aplicar escopos e funções

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

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

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

Depois que sua API validar o token e definir o escopo e processar o ID do objeto (oid), a chave de assunto (sub) e as declarações de funções, sua API poderá retornar os resultados.

Próximas etapas

• O artigo Exemplo de API protegida pela estrutura de consentimento de identidade da Microsoft ajuda você a projetar estratégias de permissões de aplicativos com privilégios mínimos para oferecer a melhor experiência do usuário.
• Chamar uma API de outra API ajuda você a garantir Zero Trust quando você tem uma API que precisa chamar outra API e desenvolver seu aplicativo com segurança quando ele estiver 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 menos privilégios.
• 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, ao mesmo tempo que aumentam a segurança de confiança zero do aplicativo com menos privilégios.
• Adquirir autorização para acessar recursos ajuda você a entender a melhor forma de garantir 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 de aplicativo exigem consentimento administrativo.
• Neste Guia de início rápido: Proteger uma API Web com a plataforma de identidade da Microsoft,, saiba como proteger uma API Web do ASP.NET restringindo o acesso a seus recursos somente a contas autorizadas.
• Neste tutorial: transformar e proteger sua API no Azure API Management, saiba como configurar políticas comuns para ocultar as informações da pilha de tecnologia ou os URLs originais na resposta HTTP da API.