Share via

Chamar uma API numa aplicação daemon .NET de exemplo

  • Artigo

Este artigo utiliza uma aplicação daemon .NET de exemplo para mostrar como uma aplicação daemon adquire um token para chamar uma API Web protegida. Microsoft Entra ID para clientes protege a API Web.

Uma aplicação daemon adquire um token em nome próprio (não em nome de um utilizador). Os utilizadores não podem interagir com uma aplicação daemon porque requer a sua própria identidade. Este tipo de aplicação pede um token de acesso através da respetiva identidade de aplicação e apresenta o ID da aplicação, a credencial (palavra-passe ou certificado) e o URI do ID da aplicação para O ID Externo.

Pré-requisitos

Registar uma aplicação daemon e uma API Web

Neste passo, vai criar o daemon e os registos de aplicações da API Web e especificar os âmbitos da API Web.

Registar uma aplicação API Web

  1. Inicie sessão no centro de administração do Microsoft Entra como, pelo menos, um Programador de Aplicações.

  2. Se tiver acesso a vários inquilinos, utilize o filtro Diretórios + subscrições no menu superior para mudar para o inquilino do cliente.

  3. Navegue paraAplicações> de Identidade>Registos de aplicações.

  4. Selecione + Novo registo.

  5. Na página Registar uma aplicação apresentada, introduza as informações de registo da aplicação:

    1. Na secção Nome, introduza um nome de aplicação relevante que será apresentado aos utilizadores da aplicação, por exemplo ciam-ToDoList-api.

    2. Em Tipos de conta suportados, selecione Contas apenas neste diretório organizacional.

  6. Selecione Registar para criar a aplicação.

  7. O painel Descrição Geral da aplicação é apresentado quando o registo estiver concluído. Registe o ID do Diretório (inquilino) e o ID da Aplicação (cliente) a utilizar no código fonte da aplicação.

Configurar funções de aplicação

Uma API tem de publicar um mínimo de uma função de aplicação para aplicações, também denominada Permissão de Aplicação, para que as aplicações cliente obtenham um token de acesso como elas próprias. As permissões da aplicação são o tipo de permissões que as APIs devem publicar quando pretendem permitir que as aplicações cliente se autentiquem com êxito como si mesmas e não precisem de iniciar sessão dos utilizadores. Para publicar uma permissão de aplicação, siga estes passos:

  1. Na página Registos de aplicações, selecione a aplicação que criou (como ciam-ToDoList-api) para abrir a respetiva página Descrição geral.

  2. Em Gerir, selecione Funções de aplicação.

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

    Propriedade Valor
    Nome a apresentar ToDoList.Read.All
    Tipos de membros permitidos Aplicações
    Valor ToDoList.Read.All
    Description Permitir que a aplicação leia a lista toDo de todos os utilizadores com a "TodoListApi"

  4. Selecione Criar função de aplicação novamente e, em seguida, introduza os seguintes valores para a segunda função de aplicação e, em seguida, selecione Aplicar para guardar as alterações:

    Propriedade Valor
    Nome a apresentar ToDoList.ReadWrite.All
    Tipos de membros permitidos Aplicações
    Valor ToDoList.ReadWrite.All
    Description Permitir que a aplicação leia e escreva a lista ToDo de todos os utilizadores com a "ToDoListApi"

Configurar afirmações opcionais

Os tokens devolvidos pela identidade da Microsoft são mantidos mais pequenos para garantir um desempenho ideal por parte dos clientes que os solicitam. Como resultado, várias afirmações já não estão presentes no token por predefinição e têm de ser pedidas especificamente por aplicação. Para esta aplicação, inclui a afirmaçã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 uma combinação de afirmações de scp e funções possa ser utilizada para o mesmo fim, a utilização da afirmação idtyp é a forma mais fácil de distinguir um token de aplicação e um token de aplicação+utilizador. Por exemplo, o valor desta afirmação é a aplicação quando o token é um token apenas de aplicação.

Utilize os seguintes passos para configurar a afirmação opcional do idtyp :

  1. Em Gerir, selecione Configuração de tokens.

  2. Selecione Adicionar afirmação opcional.

  3. Em Tipo de token, selecione Access.

  4. Selecione o idtyp de afirmação opcional.

  5. Selecione Adicionar para guardar as alterações.

Registar a aplicação daemon

Para permitir que a sua aplicação inicie sessão de utilizadores com Microsoft Entra, Microsoft Entra ID para os clientes tem de ter conhecimento da aplicação que criar. O registo da aplicação estabelece uma relação de confiança entre a aplicação e Microsoft Entra. Quando regista uma aplicação, o ID Externo gera um identificador exclusivo conhecido como ID de Aplicação (cliente), um valor utilizado para identificar a sua aplicação ao criar pedidos de autenticação.

Os passos seguintes mostram-lhe como registar a sua aplicação no centro de administração do Microsoft Entra:

  1. Inicie sessão no centro de administração do Microsoft Entra como, pelo menos, um Programador de Aplicações.

  2. Se tiver acesso a vários inquilinos, utilize o filtro Diretórios + subscrições no menu superior para mudar para o inquilino do cliente.

  3. Navegue paraAplicações> de Identidade>Registos de aplicações.

  4. Selecione + Novo registo.

  5. Na página Registar uma aplicação apresentada;

    1. Introduza um Nome de aplicação relevante que seja apresentado aos utilizadores da aplicação, por exemplo ciam-client-app.
    2. Em Tipos de conta suportados, selecione Contas apenas neste diretório organizacional.

  6. Selecione Registar.

  7. O painel Descrição Geral da aplicação é apresentado após o registo com êxito. Registe o ID da Aplicação (cliente) a ser utilizado no código fonte da aplicação.

Criar um segredo do cliente

Crie um segredo do cliente para a aplicação registada. A aplicação utiliza o segredo do cliente para provar a sua identidade quando pede tokens.

  1. Na página Registos de aplicações, selecione a aplicação que criou (como ciam-client-app) para abrir a respetiva página Descrição geral.
  2. Em Gerir, selecione Segredos de certificados&.
  3. Selecione Novo segredo do cliente.
  4. Na caixa Descrição , introduza uma descrição para o segredo do cliente (por exemplo, segredo do cliente da aplicação ciam).
  5. 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.
  6. Registe o Valor do segredo. Irá utilizar este valor para configuração num passo posterior.

Nota

O valor do segredo não será apresentado novamente e não será recuperável por nenhum meio, depois de navegar para fora da página Certificados e segredos , por isso certifique-se de que o grava.
Para maior segurança, considere utilizar certificados em vez de segredos do cliente.

Conceder permissões de API à aplicação daemon

  1. Na página Registos de aplicações, selecione a aplicação que criou, como ciam-client-app.

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

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

  4. Selecione o separador As Minhas APIs .

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

  6. Selecione a opção Permissões de aplicação . Selecionamos esta opção à medida que a aplicação inicia sessão como ela própria e não como utilizadores.

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

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

  9. Neste momento, atribuiu as permissões corretamente. No entanto, uma vez que a aplicação daemon não permite que os utilizadores interajam com a mesma, os próprios utilizadores não podem consentir estas permissões. Para resolver este problema, como administrador tem de dar consentimento a estas permissões em nome de todos os utilizadores no inquilino:

    1. Selecione Conceder consentimento ao administrador para <o seu nome> de inquilino e, em seguida, selecione Sim.
    2. Selecione Atualizar e, em seguida, verifique se Concedido para <o seu nome> de inquilino aparece em Estado para ambas as permissões.

Clonar ou transferir a aplicação daemon de exemplo e a API Web

Para obter o código de exemplo da aplicação Web, pode realizar uma das seguintes tarefas:

  • Transfira o ficheiro .zip ou clone a aplicação Web de exemplo a partir do GitHub ao executar o seguinte comando:

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

Se optar por transferir o ficheiro .zip , extraia o ficheiro de aplicação de exemplo para uma pasta onde o comprimento total do caminho seja de 260 ou menos carateres.

Configurar a aplicação daemon de exemplo e a API

Para utilizar o registo da aplicação no exemplo de aplicação Web cliente:

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

  2. Localize o marcador de posição:

    • 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 diretório (inquilino). Por exemplo, se o domínio primário do inquilino for contoso.onmicrosoft.com, utilize contoso. Se não tiver o seu nome de inquilino, saiba como ler os detalhes do inquilino.

    • Enter_the_Client_Secret_Here e substitua-o pelo valor do segredo da aplicação daemon que copiou anteriormente.

    • Enter_the_Web_Api_Application_Id_Here e substitua-o pelo ID da Aplicação (cliente) da API Web que copiou anteriormente.

Para utilizar o registo da aplicação no exemplo de API Web:

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

  2. Localize o marcador de posição:

    • Enter_the_Application_Id_Here e substitua-o pelo ID da Aplicação (cliente) da API Web que copiou.

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

    • Enter_the_Tenant_Subdomain_Here e substitua-o pelo subdomínio diretório (inquilino). Por exemplo, se o domínio primário do inquilino for contoso.onmicrosoft.com, utilize contoso. Se não tiver o seu nome de inquilino, saiba como ler os detalhes do inquilino.

Executar e testar a API e a aplicação daemon de exemplo

  1. Abra uma janela da consola e, em seguida, execute a API Web com os seguintes comandos:

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

  2. Execute o cliente daemon com os seguintes comandos:

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

Se a aplicação daemon e a API Web forem executadas com êxito, deverá ver algo semelhante à seguinte matriz JSON na janela da consola

Posting a to-do...
Retrieving to-do's from server...
To-do data:
ID: 1
User ID: 41b1e1a8-8e51-4514-8dab-e568afa2826c
Message: Bake bread
Posting a second to-do...
Retrieving to-do's from server...
To-do data:
ID: 1
User ID: 41b1e1a8-8e51-4514-8dab-e568afa2826c
Message: Bake bread
ID: 2
User ID: 41b1e1a8-8e51-4514-8dab-e568afa2826c
Message: Butter bread
Deleting a to-do...
Retrieving to-do's from server...
To-do data:
ID: 2
User ID: 41b1e1a8-8e51-4514-8dab-e568afa2826c
Message: Butter bread
Editing a to-do...
Retrieving to-do's from server...
To-do data:
ID: 2
User ID: 41b1e1a8-8e51-4514-8dab-e568afa2826c
Message: Eat bread
Deleting remaining to-do...
Retrieving to-do's from server...
There are no to-do's in server

Como funciona

A aplicação daemon utiliza a concessão de credenciais de cliente OAuth2.0 para adquirir um token de acesso para si e não para o utilizador. O token de acesso que a aplicação pede 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ções. Expôs estas permissões de aplicação na API Web anteriormente e, em seguida, concedeu-as à aplicação daemon. A aplicação daemon neste artigo utiliza a Biblioteca de Autenticação da Microsoft para .NET para simplificar o processo de aquisição de um token.

Do lado da API, a API Web tem de verificar se o token de acesso tem as permissões necessárias (permissões de aplicação). A API Web rejeita tokens de acesso que não têm as permissões necessárias.

Ver também

Veja o tutorial sobre como criar a sua própria aplicação daemon .NET que chama uma API