Semion Vasilevitzky e Jonathan Elkabas

A forma mais rápida de compreender o Agent ID é criá-lo de ponta a ponta uma única vez. Este guia prático não se destina a ser um script para copiar e colar, mas sim um passeio guiado que cria o objeto central que discutimos, para que os fluxos de tokens posteriores sejam mais fáceis de compreender.

O que irá adquirir ao concluir as etapas de avaliação prática:

  • Um objeto «Agent ID» real definido no seu tenant
  • Uma correspondência concreta entre os capítulos teóricos e os objetos Graph que pode enumerar
  • Uma base de referência simples que pode reutilizar para testar permissões, herança e registo

Utilizaremos o Microsoft Graph Explorer para as chamadas de administrador e o PowerShell 7 para a sessão de modelo de identidade do agente, sempre que for relevante. Por uma questão de simplicidade, a conta de administrador nesta demonstração possui o nível de acesso de Administrador Global.

NOTA: O ID do agente encontra-se atualmente em pré-visualização pública, e muitas das operações abaixo dependem de pontos de extremidade beta do Microsoft Graph, que podem sofrer alterações ao longo do tempo.

Vamos começar.


Criação de um modelo de identidade de agente e do seu principal do modelo

Para criar um modelo de identidade de agente, é necessário fornecer, no mínimo:

  • displayName
  • patrocinadores (pelo menos um)

Envie um pedido POST para o /applications/graph.agentIdentityBlueprint ponto final. (Atualização rápida: isto também já pode ser feito através do Centro de Administração do Entra). O principal que efetua a chamada precisa de AgentIdentityBlueprint.Create permissões.

Figura 1. Atribuição de um nome ao modelo de identidade do agente

Registe o ID do objeto blueprint a partir da resposta. (Iremos referir-nos a ele como <blueprint-id>.)

Figura 2. Registo do ID do objeto «blueprint» da identidade do agente

Em seguida, crie o principal do modelo (a instância do principal de serviço do modelo do inquilino). Envie um pedido POST para /servicePrincipals/graph.agentIdentityBlueprintPrincipal e incluir o ID do objeto do blueprint como parâmetro obrigatório. A permissão com o mínimo de privilégios para esta operação é AgentIdentityBlueprintPrincipal.Create.

Figura 3. Criação de um principal de modelo de identidade de agente com privilégios reduzidos

Registe o ID do objeto «blueprint principal» (entidade de serviço) a partir da resposta. (Iremos referir-nos a ele como <blueprint-sp-id>.)

Figura 4. O ID do objeto do diretor do projeto

Adicionar credenciais

No próximo passo, irá adicionar credenciais ao blueprint. Vamos mostrar como adicionar um certificado e um FIC; no entanto, na demonstração, utilizaremos um tipo de credencial de segredo de cliente, embora isso não seja recomendado (mais informações sobre este assunto no capítulo sobre configurações incorretas deste guia).

Para adicionar um FIC, ligue para /applications//federatedIdentityCredentials com os seguintes parâmetros.

Figura 5. Adição do agente FIC

Para obter um segredo de cliente, chame /applications//addPassword com um passwordCredential objeto (nome de exibição + data de validade). Isto requer AgentIdentityBlueprint.AddRemoveCreds.All.

Figura 6. Obter o segredo do cliente

Registe o secretText a partir da resposta. Este é o valor que irá utilizar para a autenticação posterior.


Autenticação do Blueprint

Mude para o PowerShell 7 e obtenha um token de acesso utilizando o e o segredo do cliente que acabou de criar.

Figura 7. Obtenção do token de acesso para a autenticação do blueprint

Agora, ao consultar os registos de início de sessão, irá ver o ID do entidade de serviço do blueprint.

Figura 8. O ID do principal de serviço aparece agora nos registos de início de sessão

Também é possível ver o ID do modelo de identidade do agente nos registos.

Figura 9. O ID do modelo de identidade do agente nos registos

Agora que já tem um token de acesso para o blueprint, pode descodificá-lo e ver o valor predefinido AgentIdentity.CreateAsManager autorização de que falámos anteriormente.

Figura 10. Visualização da autorização do gestor do agente

Criação da identidade do agente

Com o modelo autenticado, já pode utilizá-lo para criar uma identidade de agente.

Para tal, chame a função /servicePrincipals/Microsoft.Graph.AgentIdentity ponto final e forneça as seguintes propriedades: nome de exibição, lista de patrocinadores e o ID do modelo de identidade do agente.

Figura 11. Início do pedido de identificação do agente

Registe o ID do objeto de identidade do agente a partir da resposta. (Iremos referir-nos a ele como <agent-identity-id>.)

Figura 12. Visualização do ID do novo objeto de identidade do agente

Criação de um utilizador agente

Antes de criar um utilizador agente, referimos anteriormente que o modelo de identidade do agente deve dispor de permissões adicionais para esta operação. Podemos atribuir essas permissões chamando a função /servicePrincipals//appRoleAssignments ponto final e atribuir ao modelo o AgentIdUser.ReadWrite.IdentityParentedBy autorização da aplicação. Vamos utilizar uma conta de administrador do inquilino para realizar esta ação.

No corpo da solicitação, temos de incluir o ID do SP do blueprint, o ID do recurso (ID do SP do MS Graph) e o ID da função da aplicação, que podem ser consultados aqui.

Figura 13. Atribuição de permissões ao modelo de identidade do agente

Agora podemos criar um utilizador agente. Depois de obter um novo token para o blueprint utilizando o mesmo método que já utilizou, poderá ver a função recém-atribuída refletida no token do blueprint.

Figura 14. Visualização da função de gestor recém-criada no nosso novo token

Agora podemos utilizar este token para criar um utilizador agente, chamando a função /users/microsoft.graph.agentUser ponto final e fornecendo um nome de exibição, um nome principal de utilizador, um apelido de e-mail, o ID de identidade do agente como pai do utilizador do agente e, por fim, um indicador que especifica se a conta está ativada ou desativada.

Figura 15. Introdução de dados relativos ao novo utilizador agente

Registe o ID do objeto de utilizador do agente a partir da resposta. (Iremos referir-nos a ele como <agent-user-id>.)

Figura 16. Obtenção do ID do objeto de utilizador do agente

Lembrete: Cada identidade de agente pode ter apenas um utilizador de agente como filho (relação 1:1).

Parabéns! Criou uma identidade de agente.

No próximo capítulo do nosso guia, aprofundamos a análise dos atributos da identidade do agente.


Explore o guia