Compartilhar via

Adquirir tokens e chamar APIs downstream com o Microsoft Entra SDK para Agent ID

O Microsoft Entra SDK for Agent ID é um serviço Web em contêineres que lida com a aquisição de token, validação e chamadas de API downstream para agentes. Esse SDK se comunica com seu aplicativo por meio de APIs HTTP, fornecendo padrões consistentes de integrações, independentemente da pilha de tecnologia. Em vez de inserir a lógica de identidade diretamente no código do aplicativo, o Microsoft Entra SDK for Agent ID gerencia chamadas de aquisição, validação e API de token por meio de solicitações HTTP padrão.

Pré-requisitos

Antes de começar, verifique se você tem:

Implantar seu serviço em contêineres

Implante o SDK do Microsoft Entra para Identidade do Agente como um serviço containerizado em seu ambiente. Siga as instruções no guia Configurar o SDK do Microsoft Entra para iD do Agente para configurar o serviço com os detalhes da identidade do agente.

Configurar o SDK do Microsoft Entra para configurações de ID do Agente

Siga estas etapas para definir o SDK do Microsoft Entra para configurações de ID do Agente:

Aviso

Os segredos do cliente não devem ser usados como credenciais de cliente em ambientes de produção para blueprints de identidade do agente devido a riscos de segurança. Em vez disso, use métodos de autenticação mais seguros, como fic (credenciais de identidade federadas) com identidades gerenciadas ou certificados de cliente. Esses métodos fornecem segurança aprimorada eliminando a necessidade de armazenar segredos confidenciais diretamente na configuração do aplicativo.

  1. Configure os componentes necessários na ID do Microsoft Entra. Registre seu aplicativo no hospedador do Microsoft Entra ID.

  2. Configure suas credenciais de cliente. Essa credencial pode ser um segredo do cliente, um certificado ou uma identidade gerenciada que você está usando como uma credencial de identidade federada.

  3. Se você estiver chamando uma API downstream, verifique se as permissões necessárias serão concedidas. Chamar uma API Web personalizada exige que você forneça os detalhes de registro da API na configuração do SDK.

Para obter mais informações, consulte Definir o SDK do Microsoft Entra para configurações de AgentID

Adquirir tokens usando o SDK do Microsoft Entra para o ID do Agente

Estas são as etapas para adquirir tokens usando o Microsoft Entra SDK for Agent ID:

  1. Adquira o token usando o SDK do Microsoft Entra para o ID do Agente. Isso varia de acordo com se o agente está operando de forma autônoma ou em nome de um usuário. Há três cenários a serem considerados:

    • Agentes autônomos: agentes que operam em seu próprio nome usando entidades de serviço criadas para agentes (autônomos).
    • Usuário do agente autônomo: agentes que operam em seu próprio nome usando identidades de usuário criadas especificamente para agentes (por exemplo, agentes que mantêm sua própria caixa de correio).
    • Agentes interativos: agentes que operam em nome de usuários humanos.

    Especifique a API downstream incluindo seu nome na URL de solicitação com base na configuração do SDK da ID do agente. O ponto de extremidade do cabeçalho de autorização utiliza o formato /AuthorizationHeader/{serviceName}, onde serviceName é o nome da API downstream configurada nas configurações do SDK.

  2. Para adquirir um token somente de aplicativo para um agente autônomo, você fornece a ID do cliente de identidade do agente na solicitação.

    GET /AuthorizationHeader/Graph?AgentIdentity=<agent-id-client-ID>
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

  3. Para adquirir um token para um usuário agente autônomo, forneça a ID do objeto de usuário ou o Nome de Usuário Principal, mas não ambos. Isso significa fornecer um AgentUsername ou AgentUserId. Fornecer ambos causa um erro de validação. Você também deve fornecer a AgentIdentity para especificar qual identidade de agente usar para aquisição de token. Se o parâmetro de identidade do agente estiver ausente, a solicitação falhará com um erro de validação.

    GET /AuthorizationHeader/Graph?AgentIdentity=<agent-id-client-id>&AgentUserId=<agent-user-object-id>
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

    GET /AuthorizationHeader/Graph?AgentIdentity=<agent-id-client-id>&AgentUsername=<agent-user-principal-name>
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

  4. Para agentes interativos, use o fluxo em nome. O agente primeiro valida o token de usuário concedido a ele antes de adquirir o token de recurso para chamar a API downstream.

    A API Web do agente recebe o token de usuário do aplicativo de chamada e valida o token através do SDK de ID do /Validate no endpoint Acquire token do agente. Para APIs downstream, chame /AuthorizationHeader usando apenas o cabeçalho de autorização de entrada AgentIdentity.

    # Step 1: Validate incoming user token
GET /Validate
Authorization: Bearer <user-token>

# Step 2: Get authorization header on behalf of the user
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>
Authorization: Bearer <user-token>

Chamar uma API

Ao obter o cabeçalho de autorização para chamar uma API downstream, o SDK da Microsoft Entra para ID do Agente retorna o valor do cabeçalho Authorization, que pode ser usado diretamente em suas chamadas à API.

Você pode usar esse cabeçalho para chamar a API downstream. A API da Web deve validar o token chamando o /Validate endpoint do Microsoft Entra SDK para Agent ID. Esse endpoint retorna declarações de token para decisões de autorização adicionais.

Conteúdo relacionado

  • Last updated on