API da Web protegida: registro de aplicativo

  • Artigo

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

Para conhecer as etapas comuns para registrar um aplicativo, consulte Guia de 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, consulte Tokens de acesso.

A versão do token que sua API pode aceitar depende da seleção de tipos de conta com suporte quando você cria seu registro de aplicativo de API Web no portal do Azure.

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

Depois de 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, selecione 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 da Web aceita tokens v2.0.
    • Se o valor for null, a API da Web aceitará tokens v1.0.
  4. Se você alterou a versão do token, selecione Salvar.

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

Sem URI de redirecionamento

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

API exposta

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

Escopos e o URI da ID do Aplicativo

Os escopos geralmente têm a forma 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 âmbitos
  • Uma ou mais funções de aplicativo

Por padrão, o portal de registro do aplicativo recomenda que você use o URI api://{clientId}do recurso . Este URI é único, mas não legível por humanos. Se você alterar o URI, verifique se o novo valor é exclusivo. O portal de registro de aplicativo garantirá que você use um domínio de editor configurado.

Para aplicativos cliente, os escopos aparecem como permissões delegadas e as funções do aplicativo aparecem como permissões de aplicativo para sua API da 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 descrevem o escopo:

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

As funções do aplicativo não podem ser consentidas por um usuário (pois são usadas por um aplicativo que chama a API da Web em nome próprio). Um administrador de locatário precisará consentir que os aplicativos cliente de sua API da Web exponham funções de aplicativo. Consulte 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 da Web.

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

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

Gorjeta

Para o URI de ID do aplicativo, você tem a opção de defini-lo como a autoridade física da API, por exemplohttps://graph.microsoft.com. Isso pode ser útil se a URL da API que precisa ser chamada for conhecida.

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

Exponha permissõ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 serviço são executados sem supervisão e autenticados com sua 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 permissões de aplicativo, siga as etapas em Adicionar funções de aplicativo ao seu aplicativo.

No painel Criar função de aplicativo, em Tipos de membros 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 clientes específicos

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

Para adicionar outra camada de segurança, um administrador de locatário 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 token apenas a aplicativos cliente aos quais foram atribuídas funções de aplicativo:

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

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

Aviso

NÃO use códigos de erro AADSTS ou suas cadeias de caracteres de mensagem como literais no código do seu aplicativo. Os códigos de erro "AADSTS" e as cadeias de caracteres de mensagem de erro retornadas 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 AADSTS ou suas cadeias de caracteres de mensagem, você coloca a funcionalidade e a estabilidade do seu aplicativo em risco.

Próximo passo

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