Compartilhar via


Início Rápido: Chamar uma API Web em um aplicativo daemon de exemplo

Aplica-se a: Círculo verde com um símbolo de marca de seleção branca que indica que o conteúdo a seguir se aplica aos locatários da força de trabalho. Locatários da força de trabalho Círculo verde com um símbolo de marca de seleção branca que indica que o conteúdo a seguir se aplica a locatários externos. Locatários externos (saiba mais)

Neste início rápido, você usará um aplicativo daemon de exemplo para adquirir um token de acesso e chamar uma API Web protegida usando a MSAL (Biblioteca de Autenticação da Microsoft).

Antes de começar, use o seletor Escolher um tipo de locatário na parte superior desta página para selecionar o tipo de locatário. A ID do Microsoft Entra fornece duas configurações de locatário, força de trabalho e externo. Uma configuração de tenant de força de trabalho é para seus funcionários, aplicativos internos e outros recursos organizacionais. Um cliente externo é para seus aplicativos voltados para o consumidor.

O aplicativo de exemplo usado neste início rápido adquire um token de acesso para chamar a API do Microsoft Graph.

Pré-requisitos

  • Uma conta do Azure com uma assinatura ativa. Se você ainda não tiver uma, crie uma conta gratuitamente.
  • Essa conta do Azure deve ter permissões para gerenciar aplicativos. Qualquer uma das seguintes funções do Microsoft Entra inclui as permissões necessárias:
    • Administrador de aplicativos
    • Desenvolvedor de aplicativos
    • Administrador de Aplicativos na Nuvem
  • Um cliente da força de trabalho. Você pode usar o Diretório Padrão ou configurar um novo locatário.
  • Registre um novo aplicativo no Centro de administração do Microsoft Entra, configurado apenas para Contas neste diretório organizacional. Consulte Registrar um aplicativo para obter mais detalhes. Registre os seguintes valores na página visão geral do aplicativo para uso posterior:
    • ID do aplicativo (cliente)
    • ID do diretório (locatário)
  • Adicione um segredo do cliente ao registro do aplicativo. Não use segredos do cliente em aplicativos de produção. Em vez disso, use certificados ou credenciais federadas. Para obter mais informações, consulte adicionar credenciais ao seu aplicativo.

Conceder permissões de API ao aplicativo daemon

Para que o aplicativo daemon acesse dados na API do Microsoft Graph, conceda a ele as permissões necessárias. O aplicativo daemon precisa de permissões de tipo de aplicativo. Os usuários não podem interagir com um aplicativo daemon, portanto, o administrador do locatário deve consentir com essas permissões. Use as seguintes etapas para conceder e consentir com as permissões:

Para o aplicativo daemon .NET, você não precisa conceder e consentir com nenhuma permissão. Esse aplicativo do tipo daemon lê suas próprias informações de registro de aplicativo, permitindo que ele faça isso sem precisar de permissões de aplicativo.

Clonar ou baixar o aplicativo de exemplo

Para obter o aplicativo de exemplo, você pode cloná-lo do GitHub ou baixá-lo como um arquivo .zip .

  • Para clonar o exemplo, abra um prompt de comando e navegue até onde deseja criar o projeto e insira o seguinte comando:
git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git
  • Baixe o arquivo .zip. Extraia-o para um caminho de arquivo em que o comprimento do nome tenha menos de 260 caracteres.

Configurar o projeto

Para usar os detalhes de registro do seu aplicativo no exemplo de aplicativo cliente daemon, use as seguintes etapas:

  1. Abra uma janela do console e navegue até o diretório ms-identity-docs-code-dotnet/console-daemon :

    cd ms-identity-docs-code-dotnet/console-daemon
    
  2. Abra Program.cs e substitua o conteúdo do arquivo pelo snippet a seguir;

     // Full directory URL, in the form of https://login.microsoftonline.com/<tenant_id>
     Authority = " https://login.microsoftonline.com/Enter_the_tenant_ID_obtained_from_the_Microsoft_Entra_admin_center",
     // 'Enter the client ID obtained from the Microsoft Entra admin center
     ClientId = "Enter the client ID obtained from the Microsoft Entra admin center",
     // Client secret 'Value' (not its ID) from 'Client secrets' in the Microsoft Entra admin center
     ClientSecret = "Enter the client secret value obtained from the Microsoft Entra admin center",
     // Client 'Object ID' of app registration in Microsoft Entra admin center - this value is a GUID
     ClientObjectId = "Enter the client Object ID obtained from the Microsoft Entra admin center"
    
    • Authority - A autoridade é uma URL que indica um diretório do qual a MSAL pode solicitar tokens. Substitua Enter_the_tenant_ID_obtained_from_the_Microsoft_Entra_admin_center pelo valor de ID do diretório (inquilino) que foi registrado anteriormente.
    • ClientId - O identificador do aplicativo, também conhecido como o cliente. Substitua o texto entre aspas pelo valor Application (client) ID registrado anteriormente na página de visão geral do aplicativo registrado.
    • ClientSecret - O segredo do cliente criado para o aplicativo no Centro de administração do Microsoft Entra. Insira o valor do segredo do cliente.
    • ClientObjectId - A ID do objeto do aplicativo cliente. Substitua o texto entre aspas pelo Object ID valor que você registrou anteriormente na página de visão geral do aplicativo registrado.

Executar e testar o aplicativo

Você configurou seu aplicativo de exemplo. Você pode continuar a executá-lo e testá-lo.

Na janela do console, execute o seguinte comando para compilar e executar o aplicativo:

dotnet run

Depois que o aplicativo é executado com êxito, ele exibe uma resposta semelhante ao snippet a seguir (abreviado para brevidade):

{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications/$entity",
"id": "00001111-aaaa-2222-bbbb-3333cccc4444",
"deletedDateTime": null,
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"applicationTemplateId": null,
"disabledByMicrosoftStatus": null,
"createdDateTime": "2021-01-17T15:30:55Z",
"displayName": "identity-dotnet-console-app",
"description": null,
"groupMembershipClaims": null,
...
}

Como funciona

Um aplicativo daemon adquire um token em nome de si mesmo (não em nome de um usuário). Os usuários não podem interagir com um aplicativo daemon porque ele requer sua própria identidade. Esse tipo de aplicativo solicita um token de acesso usando sua identidade de aplicativo apresentando sua ID do aplicativo, credencial (segredo ou certificado) e um URI de ID do aplicativo. O aplicativo daemon usa o fluxo de concessão de credenciais do cliente OAuth 2.0 padrão para adquirir um token de acesso.

O aplicativo adquire um token de acesso da plataforma de identidade da Microsoft. O token de acesso tem como escopo a API do Microsoft Graph. Em seguida, o aplicativo usa o token de acesso para solicitar seus próprios detalhes de registro de aplicativo da API do Microsoft Graph. O aplicativo pode solicitar qualquer recurso da API do Microsoft Graph, desde que o token de acesso tenha as permissões certas.

O exemplo demonstra como um trabalho autônomo ou serviço Windows pode ser executado com uma identidade de aplicativo, em vez da identidade de um usuário.

Pré-requisitos

  • Uma conta do Azure com uma assinatura ativa. Se você ainda não tiver uma, crie uma conta gratuitamente.
  • Essa conta do Azure deve ter permissões para gerenciar aplicativos. Qualquer uma das seguintes funções do Microsoft Entra inclui as permissões necessárias:
    • Administrador de aplicativos
    • Desenvolvedor de aplicativos
    • Administrador de Aplicativos na Nuvem
  • Um inquilino externo. Para criar um, escolha entre os seguintes métodos:
    • (Recomendado) Use a extensão de ID Externa do Microsoft Entra para configurar um tenant externo diretamente no Visual Studio Code.
    • Crie um novo locatário externo no Centro de administração do Microsoft Entra.
  • Registre um novo aplicativo no Centro de administração do Microsoft Entra com a configuração a seguir. Para obter mais informações, consulte Registrar um aplicativo.
    • Nome: ciam-daemon-app
    • Tipos de conta com suporte: contas somente neste diretório organizacional (locatário único)
  • Visual Studio Code ou outro editor de código.
  • .NET 7.0 ou posterior.
  • Node.js (somente para implementação em Node.js)

Criar um segredo do cliente

Crie um segredo de cliente para o aplicativo registrado. O aplicativo usa o segredo do cliente para provar sua identidade quando solicita tokens:

  1. Na página Registros de Aplicativos, selecione o aplicativo que você criou (como segredo do cliente do aplicativo web) para abrir sua página Visão Geral.
  2. Em Gerenciar, selecione Certificados &segredos> Segredos >Novo segredo do cliente.
  3. Na caixa Descrição , insira uma descrição para o segredo do cliente (por exemplo, segredo do cliente do aplicativo Web).
  4. Em Expira, selecione uma duração para a qual o segredo é válido (de acordo com as regras de segurança da sua organização) e selecione Adicionar.
  5. Registre o valor do segredo. Use esse valor para configuração em uma etapa posterior. O valor do segredo não será exibido novamente e não poderá ser recuperado por qualquer meio depois que você navegar para fora dos Certificados e segredos. Certifique-se de que você grave.

Ao criar credenciais para um aplicativo cliente confidencial:

  • A Microsoft recomenda que você use um certificado em vez de um segredo do cliente antes de mover o aplicativo para um ambiente de produção. Para obter mais informações sobre como usar um certificado, consulte as instruções nas credenciais de certificado de autenticação de aplicativo da plataforma de identidade da Microsoft.

  • Para fins de teste, você pode criar um certificado autoassinado e configurar seus aplicativos para se autenticar com ele. No entanto, em produção, você deve comprar um certificado assinado por uma autoridade de certificação conhecida e, em seguida, usar o Azure Key Vault para gerenciar o acesso ao certificado e o tempo de vida.

Conceder permissões de API ao aplicativo daemon

  1. Na página Registros de aplicativo, selecione o aplicativo que você criou, como ciam-client-app.

  2. Em Gerenciar, selecione Permissões de API.

  3. Em Permissões configuradas, selecione Adicionar uma permissão.

  4. Selecione a guia APIs que minha organização usa.

  5. Na lista de APIs, selecione a API, como ciam-ToDoList-api.

  6. Selecione a opção Permissões de aplicativo . Selecionamos essa opção pois o aplicativo faz login como a própria aplicação, mas não em nome de um usuário.

  7. Na lista de permissões, selecione TodoList.Read.All, ToDoList.ReadWrite.All (use a caixa de pesquisa, se necessário).

  8. Selecione o botão Adicionar permissões .

  9. 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:

    1. Selecione Conceder consentimento do administrador para <o nome> do locatário e selecione Sim.
    2. Selecione Atualizar e verifique se Concedido para <o nome do seu locatário> aparece em Status para ambas as permissões.

Configurar funções de aplicativo

Uma API precisa publicar no mínimo uma função de aplicativo, também chamada de permissão de aplicativo, para que os aplicativos clientes obtenham um token de acesso em seu próprio nome. 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 de forma independente e não precisem que os usuários façam login. Para publicar uma permissão de aplicativo, siga estas etapas:

  1. Na página Registros de aplicativo, selecione o aplicativo que você criou (como ciam-ToDoList-api) para abrir sua página visão geral .

  2. Em Gerenciar, selecione funções de aplicativo.

  3. Selecione Criar função de aplicativo e, em seguida, insira os seguintes valores e, em seguida, selecione Aplicar para salvar suas alterações:

    Propriedade Value
    Nome de exibição ToDoList.Read.All
    Tipos de membro permitidos Aplicativos
    Value ToDoList.Read.All
    Description Permitir que o aplicativo leia a lista ToDo de cada usuário usando o 'TodoListApi'
    Deseja habilitar essa função de aplicativo? Mantenha-o marcado
  4. Selecione Criar função de aplicativo novamente e, em seguida, insira os seguintes valores para a segunda função de aplicativo e selecione Aplicar para salvar suas alterações:

    Propriedade Value
    Nome de exibição ToDoList.ReadWrite.All
    Tipos de membro permitidos Aplicativos
    Value ToDoList.ReadWrite.All
    Description Permitir que o aplicativo leia e escreva a lista ToDo de cada usuário usando o 'ToDoListApi'
    Deseja habilitar essa função de aplicativo? Mantenha-o marcado

Configurar declarações opcionais

Você pode adicionar a declaração opcional idtyp para ajudar a API Web a determinar se um token é um token de aplicativo ou um aplicativo + token de 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 aplicativo + token de usuário. Por exemplo, o valor dessa declaração é app quando o token é um token exclusivo para aplicativo.

Clonar ou baixar o aplicativo daemon de exemplo e a API Web

Para obter o aplicativo de exemplo, você pode cloná-lo do GitHub ou baixá-lo como um arquivo .zip.

  • Para clonar o exemplo, abra um prompt de comando e navegue até onde deseja criar o projeto e insira o seguinte comando:

    git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git
    
  • Como alternativa, baixe o arquivo .zip dos exemplos e, em seguida, extraia para um caminho de arquivo em que o comprimento do nome tenha menos de 260 caracteres.

Instale as dependências do projeto

  1. Abra uma janela do console e altere para o diretório que contém o aplicativo de exemplo Node.js:

    cd 2-Authorization\3-call-api-node-daemon\App
    
  2. Execute os seguintes comandos para instalar as dependências do aplicativo:

    npm install && npm update
    

Configurar o aplicativo daemon de exemplo e a API

Para usar os detalhes de registro do aplicativo no exemplo de aplicativo Web cliente, use as seguintes etapas:

  1. No editor de código, abra o arquivo App\authConfig.js.

  2. Localize o marcador de posição:

    • Enter_the_Application_Id_Here e substitua-a pela ID do aplicativo (cliente) do aplicativo daemon que você registrou anteriormente.

    • Enter_the_Tenant_Subdomain_Here e substitua-o pelo subdomínio diretório (locatário). Por exemplo, se o domínio primário da sua conta for contoso.onmicrosoft.com, use contoso. Se você não tiver o nome do locatário, saiba como ler os detalhes do locatário.

    • Enter_the_Client_Secret_Here e substitua-o pelo valor do segredo do app daemon copiado anteriormente.

    • Enter_the_Web_Api_Application_Id_Here e substitua-a pela ID do aplicativo (cliente) da API Web copiada anteriormente.

Para usar o registro do aplicativo no exemplo de API Web:

  1. No editor de código, abra o arquivo API\ToDoListAPI\appsettings.json.

  2. Localize o marcador de posição:

    • Enter_the_Application_Id_Here e substitua-a pela ID do aplicativo (cliente) da API Web copiada.

    • Enter_the_Tenant_Id_Here e substitua pelo identificador do Diretório (ID do inquilino) que você copiou anteriormente.

    • Enter_the_Tenant_Subdomain_Here e substitua-o pelo subdomínio diretório (locatário). Por exemplo, se o domínio primário da sua conta for contoso.onmicrosoft.com, use contoso. Se você não tiver o nome do locatário, saiba como ler os detalhes do locatário.

Executar e testar o aplicativo daemon de exemplo e a API

Você configurou seu aplicativo de exemplo. Você pode continuar a executá-lo e testá-lo.

  1. Abra uma janela do console e execute a API Web usando os seguintes comandos:

    cd 2-Authorization\3-call-api-node-daemon\API\ToDoListAPI
    dotnet run
    
  2. Execute o cliente do aplicativo Web usando os seguintes comandos:

    2-Authorization\3-call-api-node-daemon\App
    node . --op getToDos
    

Se o aplicativo daemon e a API Web forem executados com êxito, você deverá ver algo semelhante à seguinte matriz JSON na janela do console

{
    "id": 1,
    "owner": "3e8....-db63-43a2-a767-5d7db...",
    "description": "Pick up grocery"
},
{
    "id": 2,
    "owner": "c3cc....-c4ec-4531-a197-cb919ed.....",
    "description": "Finish invoice report"
},
{
    "id": 3,
    "owner": "a35e....-3b8a-4632-8c4f-ffb840d.....",
    "description": "Water plants"
}

Como funciona

O aplicativo Node.js usa o fluxo de concessão de credenciais do cliente OAuth 2.0 para adquirir um token de acesso para si mesmo e não para o usuário. O token de acesso que o aplicativo solicita contém as permissões representadas como funções. O fluxo de credenciais do cliente usa esse conjunto de permissões no lugar de escopos de usuário para tokens de aplicativo. Você expôs essas permissões de aplicativo na API Web anteriormente e as concedeu ao aplicativo daemon.

No lado da API, uma API Web .NET de exemplo, a API deve verificar se o token de acesso tem as permissões necessárias (permissões de aplicativo). A API Web não pode aceitar um token de acesso que não tenha as permissões necessárias.

Acesso aos dados

Um ponto de extremidade de API Web deve estar preparado para aceitar chamadas de usuários e aplicativos. Portanto, ele deve ter uma maneira de responder a cada solicitação adequadamente. Por exemplo, uma chamada de um usuário por meio de permissões ou escopos delegados recebe os dados da lista de tarefas do usuário. Por outro lado, uma chamada de um aplicativo por meio de permissões/funções de aplicativo pode receber toda a lista de to-do. No entanto, neste artigo, estamos fazendo apenas uma chamada de aplicativo, portanto, não precisamos configurar permissões/escopos delegados.