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

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. O 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

.NET

• Uma conta do Azure com uma assinatura ativa. Se ainda não tiver uma, Crie uma conta gratuitamente.
• Um requisito mínimo do SDK do .NET 6.0.
• Visual Studio 2022 ou Visual Studio Code.

Nó

• Node.js.
• Visual Studio Code ou outro editor de código.

Python

• Python 3+.
• Visual Studio Code ou outro editor de código.

Java

• Java Development Kit (JDK) 8 ou posterior.
• Maven.
• Um editor de código adequado.

Registar a aplicação e registar os identificadores

Para concluir o registro, forneça um nome ao aplicativo e especifique os tipos de conta suportados. Depois de registado, o painel Visão Geral do aplicativo exibe os identificadores necessários no código-fonte do aplicativo.

1. Entre no centro de administração do Microsoft Entra.

2. Se tiver acesso a vários locatários, utilize o ícone Definições no menu superior para mudar para o locatário no qual pretende registar a aplicação através do menu Diretórios + subscrições.

3. Navegue até Identidade>Aplicações>Registos de aplicações, selecione Novo registo.

4. Insira um Nome para a aplicação, como identity-client-daemon-app.

5. Para Tipos de contas compatíveis, selecione Contas apenas neste diretório organizacional. Para obter informações sobre diferentes tipos de conta, selecione a opção Ajude-me a escolher.

6. Selecione Registo.

   

7. O painel Visão geral do do aplicativo é exibido quando o registro é concluído. Registe o ID do Diretório (locatário) ,, o ID do Aplicativo (cliente) , e o ID do Objeto ,, para serem usados no código-fonte do seu aplicativo.

   

   Observação

   Os Tipos de conta suportados podem ser alterados consultando Modificar as contas suportadas por um aplicativo.

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

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:

.NET

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.

Nó

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. Na guia APIs da Microsoft, selecione a permissões do Microsoft Graph >> Aplicativo. Selecionamos a opção Permissões da aplicação quando a aplicação faz login como ela mesma, mas não em nome de um utilizador.

5. Na lista 'Selecionar permissões' , pesquise e, em seguida, selecione User.Read.All. Concedemos essa permissão para que o aplicativo queira ler os perfis completos de todos os usuários.

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

7. 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. Você, como administrador do locatário, 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 Atualizare, em seguida, verifique se Concedido para <o nome do locatário> aparece em Status para ambas as permissões.

Python

1. Na página de registos da aplicação , 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. Na guia APIs da Microsoft, selecione a permissões do Microsoft Graph >> Aplicativo. Selecionamos a opção Permissões do aplicativo, uma vez que a aplicação faz a autenticação em seu próprio nome, mas não em nome de um utilizador.

5. Na lista "Selecionar permissões", pesquise e, em seguida, selecione User.Read.All. Concedemos essa permissão para que o aplicativo queira ler os perfis completos de todos os usuários.

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

7. 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. Você, como administrador do locatário, 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 Atualizare, em seguida, verifique se Concedido para <o nome do locatário> aparece em Status para ambas as permissões.

Java

1. Na página registros do 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. Na guia APIs da Microsoft, selecione a permissões do Microsoft Graph >> Aplicativo. Selecionamos a opção Permissões do aplicativo quando o aplicativo faz login como ele próprio, mas não em nome de um usuário.

5. Na lista Selecionar permissões, pesquise User.Read.All e, em seguida, selecione User.Read.All. Concedemos essa permissão para que o aplicativo queira ler os perfis completos de todos os usuários.

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

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

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:

.NET

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.

Nó

git clone https://github.com/azure-samples/ms-identity-javascript-nodejs-console.git 

• Baixe o arquivo .zip. Extraia-o para um caminho de arquivo onde o comprimento do nome é inferior a 260 caracteres.

Python

git clone https://github.com/Azure-Samples/ms-identity-python-daemon.git 

• Baixe o arquivo .zip. Extraia-o para um caminho de arquivo onde o comprimento do nome é inferior a 260 caracteres.

Java

git clone https://github.com/Azure-Samples/ms-identity-java-daemon.git

• Baixe o arquivo .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:

.NET

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 Mifcrosoft 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 o aplicativo no centro de administração do 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.

Nó

No seu editor, abra o arquivo .env e substitua os espaços reservados:

• Enter_the_Application_Id_Here com o ID do aplicativo (cliente) do aplicativo que você registrou anteriormente.
• Enter_the_Tenant_Id_Here com o ID do locatário do seu inquilino da força de trabalho.
• Enter_the_Client_Secret_Here com o segredo do cliente que criaste anteriormente.
• Enter_the_Cloud_Instance_Id_Here com https://login.microsoftonline.com.
• Enter_the_Graph_Endpoint_Here com https://graph.microsoft.com/.

Python

1. Navegue até o diretório 1-Call-MsGraph-WithSecret.

2. No editor, abra o arquivo parameters.json e substitua os marcadores:

   • Enter_the_Application_Id_Here com o ID da aplicação (cliente) da aplicação que registaste anteriormente.
   • Enter_the_Tenant_Id_Here com o ID do inquilino da sua força de trabalho.
   • Enter_the_Client_Secret_Here com o segredo do cliente que criaste anteriormente.

Java

1. Navegue até o diretório msal-client-credential-secret.

2. No seu editor, abra o ficheiro src\main\resources\application.properties e substitua os marcadores de posição:

   • Enter_the_Application_Id_Here com o ID do aplicativo (cliente) do aplicativo que você registrou anteriormente.
   • Enter_the_Tenant_Id_Here com o ID de inquilino do seu sistema de gestão de pessoal.
   • Enter_the_Client_Secret_Here com o segredo do cliente que criaste anteriormente.

Executar e testar o aplicativo

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

.NET

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.

Nó

1. Para instalar dependências, execute o seguinte comando:

   npm install
   

2. Use o seguinte comando para executar o aplicativo:

   node . --op getUsers
   

Se o aplicativo for executado com êxito, você verá uma saída formatada em JSON representando uma lista de todos os usuários do locatário da força de trabalho. É semelhante ao seguinte trecho:

{
  '@odata.context': 'https://graph.microsoft.com/v1.0/$metadata#users',
  value: [
    {
      businessPhones: [],
      displayName: 'Casey Jensen',
      givenName: 'Jense',
      jobTitle: null,
      mail: null,
      mobilePhone: null,
      officeLocation: null,
      preferredLanguage: null,
      surname: 'Casey',
      userPrincipalName: 'jensen@contoso.onmicrosoft.com',
      id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
    },
    ...
  ]
}

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, a aplicação utiliza o token de acesso para ler todos os utilizadores no inquilino a partir 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. Nesse caso, concedemos ao aplicativo a permissão de aplicativo User.Read.All para que ele leia os perfis completos de todos os utilizadores.

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.

Python

1. Para instalar dependências, execute o seguinte comando:

   pip install -r requirements.txt
   

2. Para executar o aplicativo, use o seguinte comando:

   python confidential_client_secret_sample.py parameters.json
   

Se o aplicativo for executado com êxito, você verá uma saída formatada em JSON representando uma lista de todos os usuários do locatário da força de trabalho. É semelhante ao seguinte trecho:

{
  '@odata.context': 'https://graph.microsoft.com/v1.0/$metadata#users',
  value: [
    {
      businessPhones: [],
      displayName: 'Casey Jensen',
      givenName: 'Jense',
      jobTitle: null,
      mail: null,
      mobilePhone: null,
      officeLocation: null,
      preferredLanguage: null,
      surname: 'Casey',
      userPrincipalName: 'jensen@contoso.onmicrosoft.com',
      id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
    },
    ...
  ]
}

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, a aplicação usa o token de acesso para ler todos os utilizadores na entidade da Microsoft Graph API. O aplicativo pode solicitar qualquer recurso da API do Microsoft Graph, desde que o token de acesso tenha as permissões corretas. Nesse caso, concedemos ao aplicativo permissão User.Read.All aplicativo para que ele leia os perfis completos de todos os usuários.

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.

Java

Você pode testar o aplicativo de exemplo executando o método principal de ClientCredentialGrant.java do seu IDE ou

1. No console, execute o seguinte comando:

   $ mvn clean compile assembly:single
   

   Este comando gera um arquivo msal-client-credential-secret-1.0.0.jar no diretório /targets.

2. Navegue até o diretório /targets e execute o arquivo executável Java usando o seguinte comando:

   $ java -jar msal-client-credential-secret-1.0.0.jar
   

Se o aplicativo for executado com êxito, você verá uma saída formatada em JSON representando uma lista de todos os usuários do locatário da força de trabalho. É semelhante ao seguinte trecho:

{
  '@odata.context': 'https://graph.microsoft.com/v1.0/$metadata#users',
  value: [
    {
      businessPhones: [],
      displayName: 'Casey Jensen',
      givenName: 'Jense',
      jobTitle: null,
      mail: null,
      mobilePhone: null,
      officeLocation: null,
      preferredLanguage: null,
      surname: 'Casey',
      userPrincipalName: 'jensen@contoso.onmicrosoft.com',
      id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
    },
    ...
  ]
}

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, a aplicação usa o token de acesso para ler todos os utilizadores no inquilino a partir 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. Nesse caso, concedemos ao aplicativo a permissão User.Read.All para que ele possa ler os perfis completos de todos os utilizadores.

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

.NET

• Aprenda criando este aplicativo Web ASP.NET com a série Tutorial: Registrar um aplicativo com a plataforma de identidade da Microsoft.

• Guia de início rápido: implantar um aplicativo Web ASP.NET no Serviço de Aplicativo do Azure

Nó

• Saiba como criar o seu aplicativo daemon Node.js que chama a API web.

Python

• Saiba como criar um aplicativo daemon Python que chama APIs da Web

Java

• Saiba como construir um aplicativo daemon Java que chama APIs da Web

Pré-requisitos

Nó

• Visual Studio Code ou outro editor de código.
• Node.js.
• .NET 7.0 ou posterior.
• Um locatário externo. Para criar um, escolha um dos seguintes métodos:
  • (Recomendado) Use o 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 Microsoft Entra.

.NET

• Visual Studio Code ou outro editor de código
• .NET 7.0 ou posterior.
• Um locatário externo. Para criar um, escolha um dos seguintes métodos:
  • (Recomendado) Use a extensão de ID Externa do Microsoft Entra para configurar um inquilino externo diretamente no Visual Studio Code.
  • Crie um novo inquilino externo no centro de administração da Microsoft Entra.

Registar as aplicações e os identificadores de registo

Nesta etapa, você registra o aplicativo daemon e o aplicativo de API da Web no centro de administração do Microsoft Entra e especifica os escopos da sua API da Web.

Registrar um aplicativo de API da Web

1. Entre no centro de administração do Microsoft Entra como pelo menos um Desenvolvedor de Aplicativos.

2. Se tiver acesso a vários locatários, utilize o ícone de Definições no menu superior para alternar para o seu locatário externo a partir do menu Diretórios + subscrições .

3. Navegue até Identidade>Aplicações>Registos de Aplicações.

4. Selecione + Novo registo.

5. Na página Registrar um aplicativo exibida, insira as informações de registro do seu aplicativo:

   1. Na seção Nome, insira um nome de aplicativo significativo que será exibido para os usuários do aplicativo, por exemplo, ciam-ToDoList-api.

   2. Em Tipos de conta suportados, selecione Somente contas neste diretório organizacional.

6. Selecione o Registo e o Registo para criar a aplicação.

7. O painel de visão geral do aplicativo é exibido quando a inscrição está concluída. Registre o de ID do Diretório (locatário) e o ID do Aplicativo (cliente) a serem usados no código-fonte do aplicativo.

Configurar funções do aplicativo

Uma API precisa publicar pelo menos uma função de aplicação, também chamada de de Permissão de Aplicativo, para que as aplicações cliente obtenham 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	ListaDeTarefas.Ler.Tudo
   Descrição	Permita que a aplicação tenha acesso à lista de tarefas de cada utilizador usando a 'TodoListApi'

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'

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 aplicação ou um token de aplicação + utilizador. Embora você possa usar uma combinação de scp e funções declaraçõ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 é de aplicativo quando o token é um token somente de aplicativo.

Registrar o aplicativo daemon

Para permitir que a sua aplicação autentique utilizadores com o Microsoft Entra, a ID Externa do Microsoft Entra deve ser informada sobre a aplicação que criou. O registo da aplicação estabelece uma relação de confiança entre a aplicação e o Microsoft Entra. Quando você registra um aplicativo, a ID externa 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:

1. Entre no centro de administração do Microsoft Entra como pelo menos um Desenvolvedor de Aplicativos.

2. Se tiver acesso a vários locatários, utilize o ícone Definições no menu superior para mudar para o seu locatário externo no menu Diretórios + subscrições.

3. Navegue até Identidade>Aplicativos>Registros de aplicativos.

4. Selecione + Novo registo.

5. No Registar a página de candidatura que aparece;

   1. Insira um nome significativo para a aplicação Nome que será apresentado aos utilizadores da aplicação, por exemplo, ciam-client-app .
   2. Em Tipos de conta suportados, selecione Apenas contas neste diretório organizacional.

6. Selecione Registo.

7. O painel Visão Geral da aplicação é exibido após o registro bem-sucedido. Registe o ID de aplicação (cliente) a ser usado no código-fonte da sua aplicação.

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 a aplicação que criou (como segredo do cliente de aplicativo web ) para abrir a página de Visão geral .
2. Em Gerenciar, selecione Certificados & segredos>Segredos do cliente>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, 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 você navegar para fora 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 obter mais informações sobre como usar um certificado, consulte as instruções em 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 autenticação com ele. No entanto, no de produção, deve-se comprar um certificado assinado por uma autoridade de certificação conhecida e, em seguida, usar o Key Vault do Azure para gerir o acesso e o tempo de vida do certificado.

Conceder permissões de API para o aplicativo daemon

1. Na página de registros do aplicativo , selecione o aplicativo 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 Atualizare, em seguida, verifique se Concedido para <o nome do locatário> aparece em Status para ambas as permissões.

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.

Nó

• 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
   

.NET

• 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-dotnet-tutorial.git
  

• Baixe o arquivo .zip. Extraia-o para um caminho de arquivo onde o comprimento do nome é inferior a 260 caracteres.

Configurar o aplicativo 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:

Nó

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 do aplicativo (cliente) do aplicativo daemon que você registrou anteriormente.

   • Enter_the_Tenant_Subdomain_Here e substitua-o pelo subdomínio Directory (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ódigos, 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 Directory (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, veja como ler os detalhes do locatário.

.NET

1. No editor de códigos, abra o ficheiro ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListClient/appsettings.json.

2. Encontre o espaço reservado:

   • Enter_the_Application_Id_Here e substitua-o pelo ID do aplicativo (cliente) do aplicativo daemon que você registrou anteriormente.
   • Enter_the_Tenant_Subdomain_Here e substitua-o pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do seu 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ódigos, abra arquivo ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/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 (inquilino) copiado anteriormente.
   • Enter_the_Tenant_Subdomain_Here e substitua-o pelo subdomínio Directory (tenant). Por exemplo, se o domínio principal do seu 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.

Nó

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ê exposto essas permissões de aplicativo na API da Web anteriormente e, em seguida, concedido 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 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.

.NET

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

   cd 2-Authorization\3-call-own-api-dotnet-core-daemon\ToDoListAPI
   dotnet run
   

2. Execute o cliente daemon usando os seguintes comandos:

   cd 2-Authorization\3-call-own-api-dotnet-core-daemon\ToDoListClient
   dotnet run
   

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

   Posting a to-do...
   Retrieving to-do's from server...
   To-do data:
   ID: 1
   User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
   Message: Bake bread
   Posting a second to-do...
   Retrieving to-do's from server...
   To-do data:
   ID: 1
   User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
   Message: Bake bread
   ID: 2
   User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
   Message: Butter bread
   Deleting a to-do...
   Retrieving to-do's from server...
   To-do data:
   ID: 2
   User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
   Message: Butter bread
   Editing a to-do...
   Retrieving to-do's from server...
   To-do data:
   ID: 2
   User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
   Message: Eat bread
   Deleting remaining to-do...
   Retrieving to-do's from server...
   There are no to-do's in server
   

Como funciona

O aplicativo daemon usa o de 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 em vez de escopos de usuário para tokens de aplicativo. Você expos essas permissões de aplicativo na API da Web anteriormente, depois concedeste ao aplicativo daemon. O aplicativo daemon neste artigo usa Microsoft Authentication Library for .NET para simplificar o processo de aquisição de um token.

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 rejeita tokens de acesso que não têm as permissões necessárias.

Conteúdo relacionado

Nó

• Adquira um token de acesso e, em seguida, chame uma API da Web em seu próprio aplicativo daemon Node.js.
• Use um certificado de cliente em vez de um segredo para autenticação em seu aplicativo Node.js confidencial.

.NET

• Use nossa série de tutoriais multipartes para criar este aplicativo daemon .NET desde o início