Compartir a través de

Inicio de sesión de usuarios y llamada a las API de bajada con el SDK de Microsoft Entra para AgentID en Python

En este inicio rápido, usará una aplicación web de ejemplo para aprender a iniciar sesión a usuarios o agentes y llamar a las API de bajada mediante su propia identidad. La aplicación de ejemplo usa el SDK de Microsoft Entra para AgentID para validar los tokens de usuario para el acceso delegado y usa la identidad de la aplicación para la comunicación entre servicios con las API de nivel inferior, como Microsoft Graph.

Prerrequisitos

  • Instale el administrador de paquetes UV. UV es un instalador rápido de paquetes de Python y solucionador escrito en Rust.

  • Instale Docker Desktop.

  • Una cuenta de Azure con una suscripción activa. Si aún no tiene una, cree una cuenta de forma gratuita.

  • Esta cuenta de Azure debe tener permisos para administrar aplicaciones. Cualquiera de los siguientes roles de Microsoft Entra incluye los permisos necesarios:

    • Administrador de aplicaciones
    • Desarrollador de aplicaciones

  • Un inquilino trabajador Puede usar el directorio predeterminado o configurar un nuevo inquilino.

Creación y configuración de la aplicación Microsoft Entra

Para completar el resto del inicio rápido, primero debe registrar una aplicación en microsoft Entra ID.

Creación de un registro de aplicación

Siga estos pasos para crear el registro de la aplicación:

  1. Inicie sesión en el Centro de administración de Microsoft Entra como al menos un desarrollador de aplicaciones.

  2. Si tiene acceso a varios inquilinos, use el icono Configuración del menú superior para cambiar al inquilino en el que desea registrar la aplicación.

  3. Vaya a Entra ID>Registros de Aplicaciones y seleccione Nuevo registro.

  4. Escriba un nombre descriptivo para la aplicación, como identity-client-app. Los usuarios de la aplicación ven este nombre y puede cambiarlo en cualquier momento. Puede tener varios registros de aplicaciones con el mismo nombre.

  5. En Tipos de cuenta admitidos, especifique quién puede usar la aplicación. Seleccione Cuentas solo en este directorio organizativo para la mayoría de las aplicaciones. Consulte la tabla para obtener más información sobre cada opción.

    Tipos de cuenta admitidos Description
    Solo las cuentas de este directorio organizativo En el caso de las aplicaciones de Inquilino único que usarán solo los usuarios (o invitados) en su inquilino.
    Cuentas en cualquier directorio organizativo Para las aplicaciones multicliente, quieres que los usuarios de cualquier inquilino de Microsoft Entra puedan usar tu aplicación. Ideal para aplicaciones de software como servicio (SaaS) que pretende proporcionar a varias organizaciones.
    Cuentas en cualquier directorio organizativo y cuentas Microsoft personales Para aplicaciones multitenant que admiten cuentas personales y organizativas de Microsoft (por ejemplo, Skype, Xbox, Live, Hotmail).
    Cuentas personales de Microsoft Para las aplicaciones que solo usan las cuentas personales de Microsoft (por ejemplo, Skype, Xbox, Live, Hotmail).

  6. Seleccione Registrar para completar el registro de la aplicación.

    Captura de pantalla del Centro de administración de Microsoft Entra en un explorador web que muestra el panel Registrar una aplicación.

  7. Se muestra la página Información general de la aplicación. Registre los valores siguientes en la página Información general de la aplicación para su uso posterior:

    • Id. de aplicación (cliente)
    • Id. de directorio (inquilino)

    Captura de pantalla del Centro de administración de Microsoft Entra en un explorador web, en la que se muestra el panel Información general del registro de la aplicación.

Incorporación de un URI de redirección

La aplicación de ejemplo de Python usa la autenticación interactiva con un flujo de inicio de sesión basado en explorador. Configure un URI de redirección para controlar la respuesta de autenticación:

  1. En el registro de la aplicación, en Administrar, seleccione Autenticación.
  2. Seleccione Agregar una plataforma.
  3. Seleccione Aplicaciones móviles y de escritorio.
  4. En URI de redirección personalizados, escriba http://localhost.
  5. Seleccione Configurar.

Adición de credenciales de cliente

El SDK de Microsoft Entra para AgentID usa credenciales de cliente para autenticar y obtener tokens para las API de nivel inferior. Para el desarrollo y las pruebas locales, use un certificado autofirmado para la autenticación.

Generación de un certificado autofirmado

Ejecute PowerShell como administrador y use los siguientes comandos para generar un certificado autofirmado:

# Generate a self-signed certificate
$cert = New-SelfSignedCertificate `
    -Subject "CN=AgentID-Client-Certificate" `
    -CertStoreLocation "Cert:\CurrentUser\My" `
    -KeyExportPolicy Exportable `
    -KeySpec Signature `
    -KeyLength 2048 `
    -KeyAlgorithm RSA `
    -HashAlgorithm SHA256 `
    -NotAfter (Get-Date).AddDays(7)

# Export public key (CER) for upload to Azure
$cerPath = "agentid-client-certificate.cer"
Export-Certificate -Cert $cert -FilePath $cerPath

# Export private key (PFX) for the Agent ID SDK container
$pfxPath = "agentid-client-certificate.pfx"
$certPassword = ConvertTo-SecureString -String "YourSecurePassword123!" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath $pfxPath -Password $certPassword


Write-Host "Certificate generated successfully!"
Write-Host "CER file (public key): $cerPath"
Write-Host "PFX file (private key): $pfxPath"
Write-Host "Certificate Thumbprint: $($cert.Thumbprint)"
Write-Host "Certificate Password: YourSecurePassword123!"

Registre la huella digital del certificado que se muestra en la salida de PowerShell. Debe comprobar que el certificado del Centro de administración de Microsoft Entra coincide con el instalado localmente.

Cargar el certificado en microsoft Entra ID

Siga estos pasos para cargar el .cer archivo creado en el directorio actual en el Centro de administración de Microsoft Entra:

  1. Abra el registro de la aplicación en el Centro de administración de Microsoft Entra.
  2. En Administrar, seleccione Certificados y secretos.
  3. En la pestaña Certificados, seleccione Cargar certificado.
  4. Seleccione el .cer archivo que generó (por ejemplo, agentid-client-cert.cer).
  5. Proporcione una descripción (por ejemplo, "Certificado de desarrollo local de AgentID").
  6. Selecciona Agregar.
  7. Registre la huella digital del certificado que se muestra (debe coincidir con la de la generación de certificados).

Nota:

En entornos de producción, use certificados emitidos por una entidad de certificación (CA) de confianza y almacénelos en Azure Key Vault con acceso a identidad administrada. Use certificados autofirmados solo para desarrollo y pruebas locales.

Configuración de permisos de API

Siga estos pasos para configurar permisos delegados en Microsoft Graph. Con estos permisos, la aplicación cliente puede realizar operaciones en nombre del usuario que ha iniciado sesión, como leer su correo electrónico.

  1. En el registro de la aplicación, en Administrar, seleccione Permisos> de APIAgregar un permiso>de Microsoft Graph.
  2. Seleccione Permisos delegados. Microsoft Graph expone muchos permisos, los más frecuentes se muestran en la parte superior de la lista.
  3. En Seleccionar permisos, seleccione y agregue User.Read.

Configuración de permisos de aplicación

Para probar los flujos solo de aplicación en los que el SDK de AgentID llama a las API mediante su propia identidad (sin un contexto de usuario), configure los permisos de aplicación:

  1. En la página Permisos de API , seleccione Agregar un permiso>de Microsoft Graph.
  2. Seleccione Permisos de aplicación.
  3. En Seleccionar permisos, busque y seleccione User.Read.All.
  4. Seleccione Agregar permisos.
  5. Seleccione Conceder consentimiento del administrador para [Su inquilino] y confirme.

Nota:

Los permisos de aplicación requieren el consentimiento del administrador. Sin este paso, fallarán los puntos de conexión solo de la aplicación en la sección de pruebas.

Exposición de una API (para pruebas de validación de tokens)

Para llamar al punto de conexión del SDK de /validate AgentID con tokens emitidos específicamente para su aplicación (mediante el api://<application-client-id>/access_as_user ámbito), debe completar este paso. Si solo está probando escenarios de Microsoft Graph con permisos delegados, puede omitir esta sección. Siga estos pasos para exponer una API que contenga los ámbitos necesarios:

  1. En Administrar, seleccione Exponer una API.

  2. En la parte superior de la página, seleccione Agregar junto a URI de identificador de aplicación. Este valor tiene api://<application-client-id>como valor predeterminado . El URI del identificador de aplicación actúa como prefijo para los ámbitos a los que hará referencia en el código de la API y debe ser único globalmente. Haga clic en Guardar.

  3. Seleccione Agregar un ámbito como se muestra:

    Captura de pantalla del panel Exponer una API del registro de una aplicación en el Centro de administración de Microsoft Entra.

  4. A continuación, especifique los atributos del ámbito en el panel Agregar un ámbito , como se indica a continuación:

    • Nombre de ámbito: access_as_user
    • Quién puede dar su consentimiento: administradores y usuarios
    • Nombre para mostrar del consentimiento del administrador: Acceso al SDK de AgentID como usuario
    • Descripción del consentimiento del administrador: permitir el acceso a las API del SDK de AgentID como usuario que ha iniciado sesión
    • Estado: habilitado

  5. Selecciona la opción Agregar un ámbito.

Inicio del SDK de Microsoft Entra para AgentID

El SDK de Microsoft Entra para AgentID es un servicio web contenedorizado que gestiona la adquisición, validación de tokens y las llamadas seguras a la API de downstream. Se ejecuta como un contenedor complementario junto con la aplicación, lo que le permite descargar la lógica de identidad en un servicio dedicado.

Creación de un archivo de configuración

El SDK de AgentID requiere un archivo de configuración para conectarse a la aplicación Microsoft Entra. Cree un directorio para la configuración y cree un appsettings.json archivo:

# Create a directory for the AgentID SDK configuration
New-Item -ItemType Directory -Path "agentid-config" -Force
cd agentid-config

# Create the appsettings.json file
New-Item -ItemType File -Path "appsettings.json"

Abra appsettings.json en el editor de texto preferido y agregue la siguiente configuración, reemplazando los valores de marcador de posición por los detalles de la aplicación De Microsoft Entra:

{
    "AzureAd": {
        "Instance": "https://login.microsoftonline.com/",
        "TenantId": "YOUR_TENANT_ID_HERE",
        "ClientId": "YOUR_CLIENT_ID_HERE",
        "ClientCredentials": [
            {
                "SourceType": "Path",
                "CertificateStorePath": "agentid-client-certificate.pfx",
                "CertificateDistinguishedName": "YourSecurePassword123!"
            }
        ]
    },
    "DownstreamApis": {
        "me": {
            "BaseUrl": "https://graph.microsoft.com/v1.0/",
            "RelativePath": "me",
            "Scopes": [ "User.Read" ]
        }
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning"
        }
    },
    "AllowedHosts": "*"
}

Descargar y ejecutar el contenedor del SDK de AgentID

El SDK de AgentID está disponible como una imagen de contenedor precompilada de Microsoft Container Registry (MCR). Antes de extraer la imagen de contenedor, compruebe que Docker Desktop se está ejecutando. Si Docker no se está ejecutando, abra Docker Desktop y espere a que el estado muestre "Docker Desktop está en ejecución".

Vaya al directorio de configuración y ejecute los siguientes comandos:

# Navigate to your config directory
cd agentid-config

# Pull the AgentID SDK container image from MCR
docker pull mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0-rc.2-azurelinux3.0-distroless

# Run the container
docker run -d `
    --name agentid-sdk `
    -p 5178:8080 `
    -e ASPNETCORE_ENVIRONMENT=Development `
    mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0-rc.2-azurelinux3.0-distroless

# Copy configuration files into the container
docker cp appsettings.json agentid-sdk:/app/appsettings.json
docker cp agentid-client-certificate.pfx agentid-sdk:/app/agentid-client-certificate.pfx

# Restart the container to apply the configuration
docker restart agentid-sdk

Nota:

Para los hosts de Windows, utilice la variante del contenedor de Windows: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0-rc.2-windows

Puede administrar el contenedor del SDK de ID de Agente mediante los siguientes comandos de Docker:

  • Visualización de registros de contenedor: docker logs agentid-sdk
  • Visualización de registros en tiempo real: docker logs -f agentid-sdk
  • Detenga el contenedor: docker stop agentid-sdk
  • Vuelva a iniciar el contenedor: docker start agentid-sdk
  • Retire el contenedor: docker rm agentid-sdk

Verifique que el contenedor se está ejecutando

Puede comprobar si el contenedor del SDK de AgentID se está ejecutando correctamente mediante una llamada al punto de conexión de comprobación de estado:/healthz

Invoke-RestMethod -Uri "http://localhost:5178/healthz" -ErrorAction SilentlyContinue

Este punto de conexión devuelve Healthy, que confirma que el SDK de AgentID se está ejecutando correctamente y listo para controlar las solicitudes. No finalice el SDK de AgentID durante las pruebas. El contenedor debe seguir ejecutándose en segundo plano para que funcionen todas las llamadas api y autenticación de la aplicación de Python.

Ejecución de la aplicación de ejemplo de Python

La aplicación de ejemplo de Python muestra cómo usar el SDK de Microsoft Entra para AgentID para las llamadas api y autenticación. El SDK de AgentID se ejecuta como un servicio web local y actúa como proxy de autenticación. Valida los tokens de usuario y llama a las API de bajada como Microsoft Graph en su nombre.

El ejemplo incluye scripts de Python que muestran dos patrones de autenticación:

  • Permisos delegados: el SDK de AgentID valida el token de usuario y llama a las API en nombre del usuario que inició sesión.
  • Permisos de aplicación: el SDK de AgentID usa su propia identidad para llamar a las API sin un contexto de usuario.

Este enfoque centraliza la administración de tokens y el acceso a api en un único servicio que las aplicaciones pueden consumir a través de solicitudes HTTP sencillas.

Clonación o descarga de la aplicación de ejemplo de Python

Descargue la aplicación de ejemplo de Python y extráigala en un directorio local. Como alternativa, clone el repositorio, para ello, abra una ventana de comandos, vaya a la ubicación del proyecto que desee y ejecute el siguiente comando:

git clone https://github.com/AzureAD/microsoft-identity-web.git
cd microsoft-identity-web/tests/DevApps/SidecarAdapter/python

La aplicación de ejemplo contiene los siguientes scripts de Python:

  • get_token.py – Adquiere tokens de acceso de usuario a través de la Biblioteca de autenticación de Microsoft (MSAL).
  • main.py : interfaz de línea de comandos que llama a los puntos de conexión del SDK de AgentID y muestra respuestas JSON.
  • MicrosoftIdentityWebSidecarClient.py – contenedor de cliente HTTP para los endpoints /Validate, /AuthorizationHeader y /DownstreamApi del SDK de AgentID.

Los scripts de Python usan el parámetro me al llamar a los puntos de conexión del SDK de AgentID. Este parámetro hace referencia a la configuración de API de bajada denominada "me" en los SDK appsettings.jsonde AgentID :

"DownstreamApis": {
    "me": {
        "BaseUrl": "https://graph.microsoft.com/v1.0/",
        "RelativePath": "me",
        "Scopes": [ "User.Read" ]
    }
}

Cuando se llama a un punto de conexión del SDK de AgentID con el me parámetro , el SDK usa la dirección URL base y la ruta de acceso relativa de la configuración para construir el punto de conexión de API completo, solicita los ámbitos especificados y llama al punto de conexión de Microsoft Graph /me para recuperar el perfil del usuario que ha iniciado sesión. Puede agregar configuraciones adicionales de APIs descendentes a appsettings.json con nombres y puntos de conexión diferentes para llamar a APIs adicionales.

Prueba de la interacción entre el SDK de Microsoft Entra para AgentID y la aplicación de Python

En este inicio rápido se muestra un patrón de autenticación de tres niveles:

  1. Autenticación de usuario: adquiere un token de acceso de usuario mediante MSAL para Python. Este token demuestra la identidad del usuario.
  2. Validación de tokens: el SDK de AgentID valida el token de usuario para asegurarse de que es auténtico y emitido para la aplicación.
  3. Intercambio de token: el SDK de AgentID utiliza el flujo On-Behalf-Of (OBO) para intercambiar el token de usuario por un nuevo token con ámbito de Microsoft Graph y, a continuación, llama a la API.

En escenarios de solo aplicación, el SDK de AgentID omite la autenticación de usuario y usa sus propias credenciales de cliente para adquirir tokens directamente. El SDK centraliza esta lógica de autenticación, por lo que la aplicación de Python solo necesita realizar solicitudes HTTP sencillas sin administrar flujos complejos de OAuth.

Adquisición de un token de acceso de usuario

Antes de probar los puntos de conexión del SDK de AgentID, obtenga un token de acceso válido. El get_token.py script usa MSAL para Python para adquirir tokens de forma interactiva a través de un flujo de inicio de sesión basado en explorador.

Ámbitos y audiencias de token:

El alcance que solicita determina la audiencia (aud declaración) del token, que debe coincidir con el punto de conexión que está utilizando.

  • Para las pruebas de validación de tokens, use api://<client-id>/access_as_user para probar el /validate punto de conexión.
  • Para las pruebas de Microsoft Graph, adquiera un nuevo token con User.Read ámbito para probar /authorizationheader y /downstreamapi puntos de conexión.

Use los siguientes comandos para establecer las variables de configuración y adquirir un token:

# Set your configuration
$clientId = "YOUR_CLIENT_ID_HERE"
$tenantId = "YOUR_TENANT_ID_HERE"
$authority = "https://login.microsoftonline.com/$tenantId"

# For testing AgentID SDK APIs (if you exposed the API)
$scope = "api://$clientId/access_as_user"

# Or for testing Microsoft Graph directly
# $scope = "User.Read"

# Acquire token
$token = uv run --with msal get_token.py --client-id $clientId --authority $authority --scope $scope

Al ejecutar el comando acquire token, el script inicia un flujo de inicio de sesión interactivo basado en explorador. Esta autenticación del explorador solo se produce en la primera ejecución. Después de la autenticación correcta, el token se almacena en caché localmente para su uso posterior. A continuación, el token de acceso se imprime en la consola y se almacena en la $token variable de PowerShell para su uso en comandos posteriores.

Prueba del SDK de Microsoft Entra para puntos de conexión AgentID con permisos delegados

Después de obtener un token de usuario válido, puede probar los puntos de conexión principales del SDK de AgentID. Estas operaciones usan permisos delegados, por lo que el SDK actúa en nombre del usuario que ha iniciado sesión.

En primer lugar, establezca la dirección URL base del SDK:

$side_car_url = "http://localhost:5178"

1. Validar el token de usuario

El /validate punto de conexión requiere un token emitido específicamente para tus aplicaciones mediante el api://<client-id>/access_as_user ámbito. Antes de probar la validación de tokens, asegúrese de completar los pasos descritos en la sección "Exponer una API". Use el siguiente comando para llamar al /validate punto de conexión.

uv run --with requests main.py --base-url $side_car_url --authorization-header "Bearer $token" validate

Respuesta esperada:

El /validate punto de conexión comprueba que el token es válido y extrae información de reclamaciones.

{
  "protocol": "Bearer",
  "token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6...",
  "claims": {
    "aud": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "iss": "https://login.microsoftonline.com/...",
    "name": "Your Name",
    "upn": "your.email@domain.com"
  }
}

Esta respuesta confirma que:

  • El formato del token es correcto (token de portador)
  • La autoridad esperada emite el token.
  • La audiencia (aud) coincide con tu aplicación
  • Las declaraciones de identidad de usuario se encuentran presentes y son válidas

2. Obtener un encabezado de autorización para Microsoft Graph

El /authorizationheader punto de conexión recupera un encabezado de autorización con el formato correcto para llamar a las API de bajada:

uv run --with requests main.py --base-url $side_car_url --authorization-header "Bearer $token" get-auth-header me

Este extremo:

  • Valida el token de usuario entrante.
  • Adquiere un nuevo token para Microsoft Graph en nombre del usuario.
  • Devuelve el encabezado de autorización formateado.

3. Llamar a Microsoft Graph a través del SDK de Microsoft Entra para AgentID

El /downstreamapi punto de conexión llama directamente a Microsoft Graph y devuelve la respuesta:

uv run --with requests main.py --base-url $side_car_url --authorization-header "Bearer $token" invoke-downstream me

Respuesta esperada:

{
  "statusCode": 200,
  "headers": {...},
  "content": {
    "displayName": "Your Name",
    "mail": "your.email@domain.com",
    "userPrincipalName": "your.email@domain.com"
  }
}

El me parámetro corresponde a la configuración de API de bajada que definió en appsettings.json. El SDK de AgentID:

  1. Valida el token de usuario.
  2. Adquiere un nuevo token para Microsoft Graph mediante el flujo en nombre de (OBO)
  3. Llama al /me punto de conexión en Microsoft Graph
  4. Devuelve los datos del perfil de usuario.

4. Sobrescribir los ámbitos predeterminados y proporcionar un cuerpo de la solicitud

Puede personalizar las llamadas API reemplazando los ámbitos predeterminados configurados en appsettings.json o proporcionando un cuerpo de solicitud para las operaciones de escritura.

uv run --with requests main.py --base-url $side_car_url --authorization-header "Bearer $token" --scope <scopes> invoke-downstream <api-name> --body-file <path-to-file>

Este enfoque es útil cuando:

  • Prueba de diferentes niveles de permisos. Por ejemplo, puede especificar distintos ámbitos, como --scope User.Read Mail.Read para solicitar permisos adicionales.
  • La API de bajada requiere ámbitos no configurados de forma predeterminada
  • Debe solicitar permisos adicionales dinámicamente.
  • Al llamar a las APIs que requieren un cuerpo de solicitud (como al crear o actualizar recursos), puedes agregar el parámetro opcional --body-file, que se utiliza para las operaciones POST/PUT.

Probar puntos de conexión solo para aplicaciones

El SDK de Microsoft Entra para AgentID también admite flujos de solo aplicación. En estos flujos, el SDK de AgentID usa su propia identidad de aplicación en lugar de actuar en nombre de un usuario. Estos puntos de conexión no requieren un encabezado de autorización de usuario.

Nota:

Los flujos de solo aplicación requieren que el registro de la aplicación tenga permisos de aplicación (como User.Read.All) en Microsoft Entra ID, no solo permisos delegados. Un administrador debe conceder consentimiento a estos permisos para poder probar estos puntos de conexión.

Consigue el encabezado de autorización sin contexto de usuario

Use este punto de conexión para recuperar un encabezado de autorización para llamar a Microsoft Graph con la identidad propia del SDK de AgentID:

uv run --with requests main.py --base-url $side_car_url get-auth-header-unauth me

Este extremo:

  • Usa las credenciales de cliente (identidad de aplicación) del SDK de AgentID para autenticarse.
  • Adquiere un token de acceso de solo aplicación para Microsoft Graph
  • Devuelve el encabezado de autorización.

Llamar a Microsoft Graph sin contexto de usuario

Use este punto de conexión para llamar directamente a Microsoft Graph mediante la identidad del SDK de AgentID:

uv run --with requests main.py --base-url $side_car_url invoke-downstream-unauth me

En este ejemplo se muestra la comunicación entre servicios donde:

  • Ningún usuario participa en el flujo de autenticación
  • El SDK de AgentID se autentica mediante su propio identificador de cliente y certificado.
  • La llamada API usa permisos de aplicación, no permisos delegados
  • Este patrón es ideal para servicios en segundo plano, procesamiento por lotes o tareas automatizadas

Descripción de las respuestas

Estructura de respuesta de validación de tokens

La respuesta de validación proporciona información detallada sobre el token:

Campo Description
protocol El esquema de autenticación (siempre "Bearer" para los tokens de OAuth 2.0)
token El token de acceso original (truncado en ejemplos)
claims Pares clave-valor extraídos del payload del token
claims.aud Audiencia prevista (el identificador de cliente)
claims.iss Emisor de tokens (Microsoft Entra ID)
claims.name Nombre para mostrar del usuario que ha iniciado sesión
claims.upn Nombre principal de usuario (dirección de correo electrónico)

Estructura de respuesta de llamadas de Microsoft Graph

Campo Description
statusCode Código de estado HTTP de Microsoft Graph (200 = correcto)
headers Encabezados de respuesta de la llamada API
content Datos reales devueltos por Microsoft Graph
content.displayName Nombre de usuario mostrado en el directorio
content.mail Dirección de correo electrónico del usuario
content.userPrincipalName UPN del usuario

Solucionar los problemas comunes

Si se producen errores al probar el SDK de Microsoft Entra para puntos de conexión agentID, compruebe las siguientes soluciones a problemas comunes:

Cuestión Solución
Errores de "Conexión rechazada" Compruebe que el contenedor del SDK de AgentID se está ejecutando: docker ps -a. Si el estado del contenedor muestra "Exited", compruebe los registros: docker logs agentid-sdk. Reinicie el contenedor: docker start agentid-sdk y pruebe el endpoint de salud: Invoke-RestMethod -Uri "http://localhost:5178/healthz".
El contenedor devuelve Error Interno del Servidor 500 Vea los registros de contenedor para obtener errores detallados: docker logs agentid-sdk. Causas comunes: JSON no válido en appsettings.json, ruta de acceso de certificado incorrecta, contraseña de certificado incorrecta o valores TenantId/ClientId que faltan.
Errores de certificado no encontrados Asegúrese de que el archivo PFX se copió correctamente: docker exec agentid-sdk ls -la /app/agentid-client-certificate.pfx. Si falta, cópielo de nuevo: docker cp agentid-client-certificate.pfx agentid-sdk:/app/agentid-client-certificate.pfx y reinicie: docker restart agentid-sdk.
Errores de "Token no válido" o "Fallo en la validación de audiencia" Asegúrese de que la audiencia (aud declaración) del token coincida con el ID de cliente. Para el /validate punto, use el api://<client-id>/access_as_user alcance. Para las llamadas de Microsoft Graph, use User.Read. Borre la caché de los tokens: Remove-Item -Path "$env:USERPROFILE\.msal_token_cache.bin" -ErrorAction SilentlyContinue.
appsettings.json no se carga Compruebe que el archivo se copió en el contenedor: docker exec agentid-sdk cat /app/appsettings.json. Asegúrese de que json es válido (sin comentarios, sintaxis adecuada). Si falta el archivo o es incorrecto, cópielo de nuevo y reinicie el contenedor.
El contenedor no se iniciará después de los cambios de configuración Detener y eliminar el contenedor: docker stop agentid-sdk && docker rm agentid-sdk. Vuelva a ejecutar el contenedor con archivos de configuración actualizados siguiendo la sección "Extraer y ejecutar el contenedor del SDK de AgentID".

Pasos siguientes

  • Identidades de agente: Aprenda a usar el SDK de Microsoft Entra para AgentID con entidades de servicio e identidades administradas, mediante pruebas con los parámetros --agent-identity y --agent-username
  • API personalizada: agregue más configuraciones de API descendentes a appsettings.json para llamar a sus propias API protegidas.
  • Implementación de producción: configure el SDK de Microsoft Entra para AgentID para usar identidades administradas en lugar de certificados.
  • Last updated on