Partilhar via

Guia de início rápido: chamar uma API da Web em um aplicativo daemon de exemplo

Aplica-se a: círculo verde com um símbolo de marca de verificação branco. Inquilinos da força de trabalho círculo verde com um símbolo de marca de verificação branco. Inquilinos externos (saiba mais)

Neste guia de início rápido, irás usar uma aplicação daemon de exemplo para adquirir um token de acesso e chamar uma API web protegida utilizando a Microsoft Authentication Library (MSAL).

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

O aplicativo de exemplo que você usa 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 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
    • Programador de Aplicações
    • Administrador de aplicativos na nuvem
  • Um inquilino de habitação para trabalhadores. Você pode usar seu diretório padrão ou configurar um novo locatário.
  • 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)
  • Adicione um segredo de cliente ao registro do seu aplicativo. Não use segredos de 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 para o aplicativo daemon

Para que o aplicativo daemon acesse dados na API do Microsoft Graph, você concede a ele as permissões necessárias. A aplicação daemon precisa de permissões de tipo de aplicação. 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 as permissões:

Para o aplicativo daemon .NET, você não precisa conceder e consentir nenhuma permissão. Este aplicativo daemon lê suas próprias informações de registro do aplicativo, para que possa fazê-lo sem receber nenhuma permissão de aplicativo.

Clone ou baixe 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 digite o seguinte comando:
git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git
  • Baixe o ficheiro .zip. Extraia-o para um caminho de arquivo onde o comprimento do nome é inferior a 260 caracteres.

Configurar o projeto

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

  1. Abra uma janela do console e navegue até ao 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 seguinte trecho;

     // 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 ID do Diretório (locatário) que foi anotado anteriormente.
    • ClientId - O identificador do aplicativo, também conhecido como cliente. Substitua o texto entre aspas pelo valor Application (client) ID que foi registrado anteriormente na página de visão geral do aplicativo registrado.
    • ClientSecret - O segredo do cliente criado para a aplicação no centro de administração Microsoft Entra. Insira o valor do segredo do cliente.
    • ClientObjectId - O ID do objeto do aplicativo cliente. Substitua o texto entre aspas pelo valor Object ID 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

Quando o aplicativo é executado com êxito, ele exibe uma resposta semelhante ao seguinte trecho (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 de aplicativo, credencial (segredo ou certificado) e um URI de ID de aplicativo. O aplicativo daemon usa o fluxo de concessão de credenciais de 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 corretas.

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

Conteúdo relacionado

Pré-requisitos

  • Uma conta do Azure com uma assinatura ativa. Se 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
    • Programador de Aplicações
    • Administrador de aplicativos na nuvem
  • Um locatário externo. Para criar um, escolha um dos seguintes métodos:
  • Registre um novo aplicativo no Centro de administração do Microsoft Entra com a seguinte configuração. Para obter mais informações, consulte Registrar um aplicativo.
    • Nome: ciam-daemon-app
    • Tipos de conta suportados: Contas somente neste diretório organizacional (Cliente único)
  • Visual Studio Code ou outro editor de código.
  • .NET 7.0 ou posterior.
  • Node.js (apenas para implementação de Node)

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 de Registos de aplicações, selecione a aplicação que criou (como o segredo do cliente da aplicação Web ) para abrir a sua página de Visão geral .
  2. Em Gerenciar, selecione Certificados & segredos>Segredos do cliente>Novo segredo do cliente.
  3. Na caixa de 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, em seguida, selecione Adicionar.
  5. Registre o valor do segredo. Use esse valor para configuração em uma etapa posterior. O valor secreto não será exibido novamente e não poderá ser recuperado por nenhum meio, depois que saíres do Certificados e Segredos. Certifique-se de gravá-lo.

Quando você cria 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 mais informações sobre como usar um certificado, consulte as instruções em as credenciais de autenticação por certificado para aplicações na plataforma de identidade da Microsoft.

  • Para fins de teste, você pode criar um certificado autoassinado e configurar seus aplicativos para autenticação com ele. No entanto, na produção, deve comprar um certificado assinado por uma autoridade de certificação reconhecida e, em seguida, usar o Azure Key Vault para gerir o acesso e a validade do certificado.

Conceder permissões de API para o aplicativo daemon

  1. Na página registos de aplicações, selecione a aplicação que 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 esta opção quando a aplicação acede como ela própria, mas não em nome de um utilizador.

  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 de administrador para <o nome do seu inquilino>e, em seguida, selecione Sim.
    2. Selecione Atualizar e, em seguida, verifique se Concedido para <o nome do locatário> aparece em Status em ambas as permissões.

Configurar funções do aplicativo

Uma API precisa publicar pelo menos uma função de aplicação, também chamada de permissão de aplicação, para que as aplicações cliente possam obter um token de acesso em seu próprio nome. As permissões de aplicações são o tipo de permissões que as APIs devem publicar quando pretendem permitir que as aplicações clientes se autentiquem com êxito como elas próprias e sem necessidade de iniciar sessão os utilizadores. Para publicar uma permissão de aplicativo, execute estas etapas:

  1. Na página de registros de app , selecione o app que criou (como ciam-ToDoList-api) para abrir a sua página de Visão Geral .

  2. Em Gerenciar, selecione Funções do aplicativo.

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

    Propriedade Valor
    Nome para exibição ToDoList.Read.All
    Tipos de membros permitidos Aplicações
    Valor ToDoList.Read.All
    Descrição Permita que a aplicação tenha acesso à lista de tarefas de cada utilizador usando a 'TodoListApi'
    Deseja habilitar esta função da aplicação? Mantenha-o verificado

  4. Selecione Criar função de aplicativo novamente, insira os seguintes valores para a segunda função de aplicativo e selecione Aplicar para salvar as alterações:

    Propriedade Valor
    Nome para exibição ToDoList.ReadWrite.All
    Tipos de membros permitidos Aplicações
    Valor ToDoList.ReadWrite.All
    Descrição Permita que a aplicação leia e escreva a lista de tarefas de todos os utilizadores usando a 'ToDoListApi'
    Deseja habilitar esta função da aplicação? Mantenha-o verificado

Configurar declarações opcionais

Você pode adicionar a alegação opcional idtyp para ajudar a API web a determinar se um token é um token de aplicativo ou um token de aplicativo + usuário . Embora possa usar uma combinação de declarações scp e roles para a mesma finalidade, utilizar a declaração idtyp é a maneira mais fácil de distinguir entre um token de aplicação e um token de aplicação + usuário. Por exemplo, o valor desta afirmação é app quando o token é um token apenas de aplicativo.

Clone ou baixe o aplicativo daemon de exemplo e a API da 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 digite o seguinte comando:

    git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git

  • Em alternativa, descarregue o ficheiro de exemplos .zipe extraia-o para um caminho de ficheiro onde o nome tenha menos de 260 caracteres.

Instalar dependências do projeto

  1. Abra uma janela do console e mude 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 a aplicação de 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. Encontre o espaço reservado:

    • Enter_the_Application_Id_Here e substitua-o pelo ID da aplicação (cliente) da aplicação daemon que registou anteriormente.

    • Enter_the_Tenant_Subdomain_Here e substitua-o pelo subdomínio Directório (locatário). Por exemplo, se o domínio principal do locatário for contoso.onmicrosoft.com, use contoso. Se 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 secreto do aplicativo daemon copiado anteriormente.

    • Enter_the_Web_Api_Application_Id_Here e substitua-o pelo ID do aplicativo (cliente) da API da Web que você copiou anteriormente.

Para usar seu registro de aplicativo no exemplo de API da Web:

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

  2. Encontre o espaço reservado:

    • Enter_the_Application_Id_Here e substitua-o pelo ID do aplicativo (cliente) da API da Web que você copiou.

    • Enter_the_Tenant_Id_Here e substitua-o pelo ID do diretório (tenant) que copiou anteriormente.

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

Executar e testar o aplicativo de 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 da 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 da Web forem executados com êxito, você 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

A aplicação Node.js usa o fluxo de concessão de credenciais do cliente OAuth 2.0 para adquirir um token de acesso para ele próprio e não para o utilizador. O token de acesso que o aplicativo solicita contém as permissões representadas como funções. O fluxo de credenciais do cliente utiliza este conjunto de permissões em vez de âmbitos de utilizador para tokens de aplicação. Você expôs estas permissões da aplicação na API da Web anteriormente e, em seguida, concedeu-as à aplicação 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 da 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. Por conseguinte, deve ter uma forma de responder a cada pedido em conformidade. Por exemplo, uma chamada de um utilizador por meio de permissões/âmbitos delegados recebe a lista de dados do utilizador to-do. Por outro lado, uma chamada de um aplicativo através das permissões/funções atribuídas ao aplicativo pode ter acesso à lista completa de to-do. No entanto, neste artigo, estamos fazendo apenas uma chamada de aplicativo, portanto, não precisamos configurar permissões/escopos delegados.

Conteúdo relacionado