Creación de un plano técnico de identidad del agente

Un plano técnico de identidad del agente se usa para crear identidades de agente y solicitar tokens mediante esas identidades de agente. En esta guía se explica cómo crear un esquema de identidad de agente utilizando la API de REST de Microsoft Graph y Microsoft Graph PowerShell.

Prerrequisitos

Antes de crear el plano técnico de identidad del agente, asegúrese de que tiene:

comprender los planos de identidad del agente
Administrador de roles con privilegios necesarios para conceder permisos
Uno de los siguientes roles es necesario para crear un plan maestro: Desarrollador de ID de Agente o Administrador de ID de Agente. Prefiere el rol Administrador de ID de Agente.

Autorizar a un cliente para crear esquemas de identidad de agente

En este artículo, usará Microsoft Graph PowerShell u otro cliente para crear la plantilla de identidad del agente. Debe autorizar a este cliente para crear un esquema de identidad de agente. El cliente requiere uno de los siguientes permisos de Microsoft Graph:

AgentIdentityBlueprint.Create (permiso delegado)
AgentIdentityBlueprint.Create (permiso de aplicación)

Solo un administrador global o un administrador de roles con privilegios puede conceder estos permisos al cliente. Para conceder estos permisos, un administrador puede:

Use el comando Connect-MgGraph.
Ejecute un script para crear un oAuth2PermissionGrant o un appRoleAssignment en el cliente.

Creación de un plano técnico de identidad del agente

La creación de un plano técnico de identidad del agente funcional en el inquilino requiere dos pasos:

Cree un AgentIdentityBlueprint en el inquilino.
Cree un AgentIdentityBlueprintPrincipal en el inquilino.

La principal creada en este caso es diferente de la identidad del agente utilizada por el agente.

API de Microsoft Graph
Microsoft Graph PowerShell

En primer lugar, obtenga un token de acceso con el permiso AgentIdentityBlueprint.Create. Una vez que tenga un token de acceso, realice la siguiente solicitud.

Sugerencia

Incluya siempre el encabezado OData-Version al usar @odata.type.

POST https://graph.microsoft.com/beta/applications/
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "@odata.type": "Microsoft.Graph.AgentIdentityBlueprint",
  "displayName": "My Agent Identity Blueprint",
  "sponsors@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/<id>",
  ],
	"owners@odata.bind": [
	  "https://graph.microsoft.com/v1.0/users/<id>"
	]
}

Connect-MgGraph -Scopes "AgentIdentityBlueprint.Create","User.Read" -TenantId <your-tenant>

# Get the current user's ID
$currentUser = Get-MgContext | Select-Object -ExpandProperty Account
$user = Get-MgUser -UserId $currentUser

Write-Host "Current user: $($user.DisplayName) ($($user.Id))"

# Construct the body for the POST request
$body = @{
    "@odata.type" = "Microsoft.Graph.AgentIdentityBlueprint"
    "displayName" = "My Agent Identity Blueprint"
    "sponsors@odata.bind" = @("https://graph.microsoft.com/v1.0/users/$($user.Id)")
    "owners@odata.bind" = @("https://graph.microsoft.com/v1.0/users/$($user.Id)")
} | ConvertTo-Json -Depth 5

# Make the POST request to create the agent identity blueprint application
$response = Invoke-MgGraphRequest `
    -Method POST `
    -Uri "https://graph.microsoft.com/beta/applications/graph.agentIdentityBlueprint" `
    -Body $body `
    -ContentType "application/json"

# Output the response
$response

Después de crear un plano técnico de identidad del agente, registre su appId para los pasos siguientes en la guía. A continuación, cree una entidad de servicio para el plano técnico de identidad del agente:

API de Microsoft Graph
Microsoft Graph PowerShell

Para crear el principal de servicio, primero deberá obtener un token de acceso con el permiso AgentIdentityBlueprint.Create. Una vez que tenga un token de acceso, realice la solicitud siguiente:

Sugerencia

Incluya siempre el encabezado OData-Version al usar @odata.type.

POST https://graph.microsoft.com/beta/serviceprincipals/graph.agentIdentityBlueprintPrincipal
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "appId": "<agent-blueprint-app-id>"
}

Connect-MgGraph -Scopes "AgentIdentityBlueprintPrincipal.Create" -TenantId <your-test-tenant>
$body = @{
    appId   = "<agent-blueprint-client-id>"
}
Invoke-MgGraphRequest -Method POST `
        -Uri "https://graph.microsoft.com/beta/serviceprincipals/graph.agentIdentityBlueprintPrincipal" `
        -Headers @{ "OData-Version" = "4.0" } `
        -Body ($body | ConvertTo-Json)

Configuración de credenciales para el modelo de identidad del agente

Para solicitar tokens de acceso mediante el modelo de identidad del agente, tienes que agregar una credencial de cliente. Se recomienda usar una identidad administrada como una credencial de identidad federada para las implementaciones de producción. Para el desarrollo y las pruebas locales, use un secreto de cliente.

Agregue una identidad administrada como credencial mediante la solicitud siguiente:

API de Microsoft Graph
Microsoft Graph PowerShell

Para enviar esta solicitud, primero debe obtener un token de acceso con el permiso AgentIdentityBlueprint.AddRemoveCreds.All.

POST https://graph.microsoft.com/beta/applications/<agent-blueprint-object-id>/federatedIdentityCredentials
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
    "name": "my-msi",
    "issuer": "https://login.microsoftonline.com/<my-test-tenant-id>/v2.0",
    "subject": "<msi-principal-id>",
    "audiences": [
        "api://AzureADTokenExchange"
    ]
}

Connect-MgGraph -Scopes "AgentIdentityBlueprint.AddRemoveCreds.All" -TenantId <your-test-tenant>

$applicationId = "<agent-blueprint-object-id>"

$federatedCredential = @{
  Name             = "my-msi"
  Issuer           = "https://login.microsoftonline.com/<my-test-tenant-id>/v2.0"
  Subject          = "<msi-principal-id>"
  Audiences         = @("api://AzureADTokenExchange")
}

New-MgApplicationFederatedIdentityCredential `
  -ApplicationId $applicationId `
  -BodyParameter $federatedCredential

En algunos entornos, también se admiten otros tipos de credenciales de aplicación, como keyCredentials, passwordCredentials y trustedSubjectNameAndIssuers. Estos tipos de credenciales no se recomiendan para producción, pero pueden ser cómodos para el desarrollo y las pruebas locales. Para agregar una credencial de contraseña:

API de Microsoft Graph
Microsoft Graph PowerShell

Para enviar esta solicitud, primero debe obtener un token de acceso con el permiso delegado. AgentIdentityBlueprint.AddRemoveCreds.All

POST https://graph.microsoft.com/beta/applications/<agent-blueprint-object-id>/addPassword
Content-Type: application/json
Authorization: Bearer <token>

{
  "passwordCredential": {
    "displayName": "My Secret",
    "endDateTime": "2026-08-05T23:59:59Z"
  }
}

Connect-MgGraph -Scopes "AgentIdentityBlueprint.AddRemoveCreds.All" -TenantId <your-tenant>

$applicationId = "<agent-blueprint-object-id>"

# Define the secret properties
$displayName = "My Secret"
$endDate = (Get-Date).AddYears(1).ToString("o")  # 1 year from now, in ISO 8601 format

# Construct the password credential
$passwordCredential = @{
    displayName = $displayName
    endDateTime = $endDate
}

# Add the password (client secret)
$response = Add-MgApplicationPassword -ApplicationId $applicationId -PasswordCredential $passwordCredential

# Output the generated secret (only returned once!)
Write-Host "Secret Text: $($response.secretText)"

Asegúrese de almacenar de forma segura el passwordCredential valor generado. No se puede ver después de la creación inicial. También puede usar certificados de cliente como credenciales; consulte Adición de una credencial de certificado.

Configurar el identificador URI y el ámbito

Para recibir solicitudes entrantes de usuarios y otros agentes, debe definir un URI de identificador y un ámbito de OAuth para el plano técnico de identidad del agente:

API de Microsoft Graph
Microsoft Graph PowerShell

Para enviar esta solicitud, primero debe obtener un token de acceso con el permiso AgentIdentityBlueprint.ReadWrite.All.

PATCH https://graph.microsoft.com/beta/applications/<agent-blueprint-object-id>
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
    "identifierUris": ["api://<agent-blueprint-id>"],
    "api": {
      "oauth2PermissionScopes": [
        {
          "adminConsentDescription": "Allow the application to access the agent on behalf of the signed-in user.",
          "adminConsentDisplayName": "Access agent",
          "id": "<generate-a-guid>",
          "isEnabled": true,
          "type": "User",
          "value": "access_agent"
        }
      ]
  }
}

Connect-MgGraph -Scopes "AgentIdentityBlueprint.ReadWrite.All" -TenantId <your-tenant>

$AppId = "<agent-blueprint-object-id>"
$IdentifierUri = "api://<agent-blueprint-id>"
$ScopeId = [guid]::NewGuid()

# Construct the OAuth2 permission scope
$scope = @{
    adminConsentDescription = "Allow the application to access the agent on behalf of the signed-in user."
    adminConsentDisplayName = "Access agent"
    id = $ScopeId
    isEnabled = $true
    type = "User"
    value = "access_agent"
}

Update-MgApplication -ApplicationId $AppId `
    -IdentifierUris @($IdentifierUri) `
    -Api @{ oauth2PermissionScopes = @($scope) }

Creación y eliminación de identidades de agente

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-11-19

Compartir a través de

Creación de un plano técnico de identidad del agente

Prerrequisitos

Autorizar a un cliente para crear esquemas de identidad de agente

Creación de un plano técnico de identidad del agente

Configuración de credenciales para el modelo de identidad del agente

Configurar el identificador URI y el ámbito

Contenido relacionado

Comentarios

Recursos adicionales