Compartilhar via

API Web protegida: registro de aplicativo

  • Artigo

Este artigo explica como registrar um aplicativo para uma API Web protegida.

Para ver as etapas comuns para registrar um aplicativo, veja Início Rápido: Registrar um aplicativo com a plataforma de identidade da Microsoft.

Versão de token aceita

A plataforma de identidade da Microsoft pode emitir tokens v1.0 e v2.0. Para obter mais informações sobre esses tokens, confira Tokens de acesso.

A versão do token que a API pode aceitar depende da seleção de Tipos de conta com suporte ao criar o registro de aplicativo da API Web no portal do Azure.

  • Se o valor de Tipos de conta com suporte for Contas em qualquer diretório organizacional e contas pessoais da Microsoft (como Skype, Xbox, Outlook.com), a versão do token aceita deverá ser a v2.0.
  • Caso contrário, a versão de token aceita pode ser v1.0.

Após criar o aplicativo, você pode determinar ou alterar a versão do token aceito seguindo estas etapas:

  1. No Centro de administração do Microsoft Entra, selecione seu aplicativo e, em seguida, Manifesto.
  2. Encontre a propriedade accessTokenAcceptedVersion no manifesto.
  3. O valor especifica para o Microsoft Entra qual versão de token a API da Web aceita.
    • Se o valor for 2, a API Web aceitará tokens v2.0.
    • Se o valor for null, a API Web aceitará tokens v1.0.
  4. Se você alterou a versão do token, selecione Salvar.

A API Web especifica qual versão de token aceita. Quando um cliente solicita um token para a API Web da plataforma de identidade da Microsoft, ele também recebe um token que indica qual versão de token a API Web aceita.

URI sem redirecionamento

APIs Web não precisam registrar um URI de redirecionamento porque nenhum usuário está conectado interativamente.

API exposta

As outras configurações específicas para APIs Web são a API exposta e os escopos expostos ou funções de aplicativo.

Escopos e o URI da ID do Aplicativo

Os escopos geralmente têm o formato resourceURI/scopeName. Para o Microsoft Graph, os escopos têm atalhos. Por exemplo, User.Read é um atalho para https://graph.microsoft.com/user.read.

Durante o registro do aplicativo, defina estes parâmetros:

  • O URI do recurso
  • Um ou mais escopos
  • Uma ou mais funções de aplicativo

Por padrão, o portal de registro de aplicativos recomenda usar o URI de recurso api://{clientId}. Esse URI é exclusivo, mas não é legível para humanos. Se você modificar o URI, verifique se o novo valor é exclusivo. O portal de registro de aplicativos garante que você use um domínio de editor configurado.

Para aplicativos cliente, os escopos aparecem como permissões delegadas e as funções de aplicativo aparecem como permissões de aplicativo para a API Web.

Os escopos também aparecem na janela de consentimento apresentada aos usuários do seu aplicativo. Portanto, forneça as cadeias de caracteres correspondentes que descrevam o escopo:

  • Como visto por um usuário.
  • Como visto por um administrador de locatários, que pode dar consentimento de administrador.

As funções de aplicativo não podem ser consentidas por um usuário (pois elas são usadas por um aplicativo que chama a API Web em seu próprio nome). Um administrador de locatário precisará consentir que os aplicativos cliente de sua API Web exponham funções de aplicativo. Veja Consentimento do administrador para obter detalhes.

Expor permissões delegadas (escopos)

Para expor permissões delegadas ou escopos, siga as etapas em Configurar um aplicativo para expor uma API Web.

Se você estiver acompanhando o cenário da API Web descrito neste conjunto de artigos, use estas configurações:

  • URI da ID do Aplicativo: aceite o URI de ID do aplicativo proposto (api://<clientId>) (se solicitado)
  • Nome do escopo: access_as_user
  • Quem pode consentir: administradores e usuários
  • Nome de exibição do consentimento do administrador: Acessar TodoListService como um usuário
  • Descrição do consentimento do administrador: Acessa a API Web do TodoListService como um usuário
  • Nome de exibição do consentimento do usuário: Acessar TodoListService como um usuário
  • Descrição do consentimento do usuário: Acessa a API Web do TodoListService como um usuário
  • Estado: Enabled

Dica

No caso do URI da ID do aplicativo, você tem a opção de configurá-lo para a autoridade física da API, por exemplo, https://graph.microsoft.com. Isso poderá ser útil se o URL da API que precisar ser chamada for conhecido.

Se a API Web for chamada por um serviço ou aplicativo daemon

Exponha aspermissões de aplicativo em vez de permissões delegadas se sua API deve ser acessada por daemons, serviços ou outros aplicativos não interativos (por um humano). Como os aplicativos do tipo daemon e de serviço são executados de modo autônomo e autenticados com a própria identidade, não há nenhum usuário para "delegar" sua permissão.

Expor permissões de aplicativo (funções de aplicativo)

Para expor as permissões do aplicativo, siga as etapas em Adicionar funções de aplicativo ao seu aplicativo.

No painel Criar função de aplicativo em Tipos de membro permitidos, selecione Aplicativos. Ou adicione a função usando o Editor de manifesto do aplicativo, conforme descrito no artigo.

Restringir tokens de acesso a aplicativos de clientes específicos

Funções de aplicativo são o mecanismo que um desenvolvedor de aplicativos usa para expor as permissões do aplicativo. O código da API Web deve verificar se há funções de aplicativo nos tokens de acesso recebidos dos chamadores.

Para adicionar outra camada de segurança, um administrador de locatários do Microsoft Entra pode configurar seu locatário para que a plataforma de identidade da Microsoft emita tokens de segurança apenas para os aplicativos cliente aprovados para acesso à API.

Para aumentar a segurança restringindo a emissão de tokens apenas para aplicativos cliente que receberam funções de aplicativo atribuídas:

  1. No centro de administração do Microsoft Entra, selecione seu aplicativo em Identidade>Aplicativos>Registros de aplicativos.
  2. Na página de Visão geral do aplicativo, em Essentials, localize e selecione o link Aplicativo gerenciado no diretório local para navegar até sua página Visão Geral do Aplicativo Enterprise.
  3. Em Gerenciar, selecione Propriedades.
  4. Defina Atribuição necessária? como Sim.
  5. Selecione Salvar.

Agora, o Microsoft Entra ID verificará se há atribuições de função de aplicativos cliente que solicitam tokens de acesso para sua API Web. Se um aplicativo cliente não tiver recebido funções de aplicativo, o Microsoft Entra ID retornará uma mensagem de erro ao cliente semelhante a _invalid_client: AADSTS501051: Application \<application name\> isn't assigned to a role for the \<web API\>_.

Aviso

NÃO use códigos de erro do AADSTS nem suas cadeias de caracteres de mensagem como literais no código do aplicativo. Os códigos de erro do "AADSTS" e as cadeias de caracteres de mensagem de erro retornados pelo Microsoft Entra ID não são imutáveis e podem ser alterados pela Microsoft a qualquer momento e sem o seu conhecimento. Se você tomar decisões de ramificação em seu código com base nos valores dos códigos do AADSTS ou de suas cadeias de caracteres de mensagem, colocará a funcionalidade e a estabilidade do aplicativo em risco.

Próxima etapa

O próximo artigo desta série é Configuração de código do aplicativo.