Tutorial: Prepare seu locatário externo para autorizar um aplicativo daemon Node.js
Essa série de tutoriais demonstra como criar um aplicativo daemon Node.js de cliente e prepará-lo para autenticação no centro de administração do Microsoft Entra. Você vai usar o fluxo de concessão de credenciais de cliente do OAuth (Open Authorization) 2.0 e, a seguir, configurá-lo para adquirir um token de acesso para chamar uma API web.
Neste tutorial;
- Registrar uma API web no centro de administração do Microsoft Entra e registrar seus identificadores
- Configurar funções de aplicativo para a API web
- Registrar um aplicativo daemon de cliente
- Conceder permissões para o aplicativo daemon
- Criar um segredo de cliente para seu aplicativo daemon
Se você já registrou um aplicativo daemon cliente e uma API Web no centro de administração do Microsoft Entra, ignore as etapas neste tutorial e, em seguida, prossiga para Adquirir token de acesso para chamar uma API.
Pré-requisitos
- Um locatário externo. Para criar um, você pode utilizar um dos seguintes métodos:
- (Recomendado) Use a extensão de ID Externa do Microsoft Entra para configurar um locatário externo diretamente no Visual Studio Code.
- Crie um novo locatário externo no centro de administração do Microsoft Entra.
Registrar um aplicativo da API Web
Faça login no Centro de administração do Microsoft Entra como pelo menos um Desenvolvedor de aplicativos.
Se tiver acesso a vários locatários, use o ícone Configurações
no menu superior para alternar para o seu locatário externo no menu Diretórios + assinaturas.Navegue até Identidade>Aplicativos>Registros do aplicativo.
Selecione + Novo Registro.
Na página Registrar um aplicativo que aparece, insira as informações de registro do aplicativo:
Na seção Nome, insira algo fácil de lembrar para ser exibido aos usuários do aplicativo, por exemplo, ciam-ToDoList-api.
Em Tipos de contas com suporte, selecione Contas somente neste diretório organizacional.
Selecione Registrar para criar o aplicativo.
O painel Visão geral do aplicativo é exibido quando o registro for concluído. Registre a ID do Diretório (locatário) e a ID do aplicativo (cliente) a ser usada no código-fonte do aplicativo.
Configurar funções de aplicativo
Uma API precisa publicar pelo menos uma função de aplicativo, também chamada de Permissão de Aplicativo, para que os aplicativos cliente possam obter um token de acesso em nome deles próprios. As permissões de aplicativo são o tipo de permissões que as APIs devem publicar quando desejam permitir que os aplicativos cliente se autentiquem com êxito como eles mesmos e não precisem conectar usuários. Para publicar uma permissão de aplicativo, siga estas etapas:
Na página Registros de aplicativo, selecione o aplicativo que você criou (como ciam-ToDoList-api) para abrir sua página Visão geral.
Em Gerenciar, selecione Funções do aplicativo.
Selecione Criar função do aplicativo, insira os seguintes valores e selecione Aplicar para salvar suas alterações:
Propriedade Valor Nome de exibição ToDoList.Read.All Tipos de membro permitidos Aplicativos Valor ToDoList.Read.All Descrição Permitir que o aplicativo leia a lista ToDo de cada usuário usando "TodoListApi" Selecione Criar função de aplicativo novamente, insira os seguintes valores para a segunda função de aplicativo e selecione Aplicar para salvar suas alterações:
Propriedade Valor Nome de exibição ToDoList.ReadWrite.All Tipos de membro permitidos Aplicativos Valor ToDoList.ReadWrite.All Descrição Permitir que o aplicativo leia e grave na lista ToDo de cada usuário usando 'TodoListApi'
Configurar declaração de token idtyp
Você pode fazer uma reivindicação opcionall idtyp para ajudar a API da Web a determinar se um token é um token de aplicativo ou um token de aplicativo + usuário. Embora você possa usar uma combinação de declarações scp e funções para a mesma finalidade, usar a declaração idtyp é a maneira mais fácil de diferenciar um token de aplicativo e um token de aplicativo + usuário. Por exemplo, o valor dessa declaração é app quando o token é um token somente de aplicativo.
Registrar um aplicativo daemon
Para permitir a entrada de usuários com o Microsoft Entra no seu aplicativo, a ID externa do Microsoft Entra deve estar ciente do aplicativo criado. O registro do aplicativo estabelece uma relação de confiança entre o aplicativo e o Microsoft Entra. Quando você registra um aplicativo, o External ID gera um identificador exclusivo conhecido como ID do Aplicativo (cliente), um valor usado para identificar seu aplicativo ao criar solicitações de autenticação.
As etapas a seguir mostram como registrar seu aplicativo no centro de administração do Microsoft Entra:
Faça login no Centro de administração do Microsoft Entra como pelo menos um Desenvolvedor de aplicativos.
Se tiver acesso a vários locatários, use o ícone Configurações
no menu superior para alternar para o seu locatário externo no menu Diretórios + assinaturas.Navegue até Identidade>Aplicativos>Registros do aplicativo.
Selecione + Novo Registro.
Na página Registrar um aplicativo que aparece;
- Insira um Nome de aplicativo relevante que será exibido aos usuários do aplicativo, por exemplo,ciam-client-app.
- Em Tipos de contas com suporte, selecione Contas somente neste diretório organizacional.
Selecione Registrar.
O painel Visão geral do aplicativo será exibido após o registro bem-sucedido. Grave a ID do aplicativo (cliente) que será usada no código-fonte do aplicativo.
Criar um segredo do cliente
Crie um segredo do cliente para o aplicativo registrado. O aplicativo usa o segredo do cliente para confirmar sua identidade ao solicitar tokens.
- Na página Registros de aplicativo, selecione o aplicativo que você criou (como ciam-client-app) para abrir sua página Visão geral.
- Em Gerenciar, selecione Certificados e segredos.
- Selecione Novo segredo do cliente.
- Na caixa Descrição, insira uma descrição para o segredo do cliente (por exemplo, ciam app client secret).
- Em Expira, selecione o período pelo qual o segredo será válido (conforme as regras de segurança da sua organização) e selecione Adicionar.
- Registre o Valor do segredo. Você usará esse valor para uma configuração em uma etapa posterior. O valor secreto não será exibido novamente e não poderá ser recuperado de forma nenhuma depois que você sair dos Certificados e segredos. Certifique-se de registrá-lo.
Conceder permissões de API para o aplicativo daemon
Na página Registros de aplicativo, selecione o aplicativo que você criou, como ciam-client-app.
Em Gerenciar, selecione Permissões de API.
Em Permissões Configuradas, selecione Adicionar uma permissão.
Selecione a guia APIs que a minha organização usa.
Na lista de APIs, selecione a API como ciam-ToDoList-api.
Selecione a opção Permissões de aplicativo. Selecionamos essa opção quando o aplicativo faz login como ele mesmo, mas não em nome de um usuário.
Na lista de permissões, selecione TodoList.Read.All, ToDoList.ReadWrite.ALL (use a caixa de pesquisa, se necessário).
Selecione o botão Adicionar permissões.
Neste ponto, você atribuiu as permissões corretamente. No entanto, como o aplicativo daemon não permite que os usuários interajam com ele, os próprios usuários não podem consentir com essas permissões. Para resolver esse problema, você, como administrador, deve consentir com essas permissões em nome de todos os usuários no locatário:
- Selecione Dar consentimento de administrador para <nome do seu locatário> e selecione Sim.
- Selecione Atualizar e verifique se Concedido para <nome do seu locatário> aparece em Status para ambas as permissões.
Colete os detalhes de registro do seu aplicativo
Na próxima etapa, você preparará seu aplicativo daemon. Verifique os detalhes a seguir:
- A ID do Aplicativo (cliente) do aplicativo daemon cliente que você registrou.
- O subdomínio do Diretório (locatário) onde você registrou o aplicativo daemon. Se você não tiver o nome do locatário, saiba como ler os detalhes do locatário.
- O valor do segredo do aplicativo daemon que você criou.
- A ID do Aplicativo (cliente) do aplicativo de API Web que você registrou.