Expor escopos numa API Web protegida

Aplica-se a: Inquilinos da força de trabalho (saiba mais)

Este artigo explica como adicionar escopos a um aplicativo para uma API da Web protegida.

Pré-requisitos

• Registre um novo aplicativo no centro de administração do Microsoft Entra, configurado para Contas somente neste diretório organizacional. Consulte Registar uma candidatura para obter mais detalhes. Registre os seguintes valores na página Visão geral do aplicativo para uso posterior:
  • ID da aplicação (cliente)
  • ID do diretório (inquilino)

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 garante 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 precisa consentir que os aplicativos cliente de sua API Web exponham funções de aplicativo. Consulte Consentimento do administrador para obter detalhes.

Expor permissões delegadas (âmbitos)

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

Se a sua API da Web for chamada por um serviço ou aplicação 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 utilizando o editor de manifesto de Aplicação, 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 aplicação nos tokens de acesso que recebe dos solicitantes.

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 somente para os aplicativos cliente que o administrador do locatário aprovou 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 o aplicativo em Entra ID>.
2. Na página Visão geral do aplicativo, nos Essenciais, localize e selecione o link Aplicativo gerido no diretório local para navegar até à página Visão geral do Aplicativo Empresarial.
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 dos aplicativos cliente que solicitam tokens de acesso da sua API 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\>_.

Próximo passo

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