Microsoft Entra SDK para AgentID: Información general

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. Al centralizar las operaciones de identidad en el SDK de Microsoft Entra para AgentID, elimina la necesidad de insertar lógica compleja de administración de tokens en cada servicio, lo que reduce la duplicación de código y las posibles vulnerabilidades de seguridad.

Si va a compilar con Kubernetes, servicios en contenedores con Docker o microservicios modernos en Azure, el SDK de Microsoft Entra para AgentID proporciona una manera estandarizada de controlar la autenticación y la autorización en aplicaciones nativas de la nube.

¿Qué es microsoft Entra SDK para AgentID?

El SDK de Microsoft Entra para AgentID se comunica con la aplicación a través de una API HTTP para la autenticación y autorización, lo que proporciona patrones de integración coherentes independientemente de la pila de tecnología. En lugar de insertar la lógica de identidad directamente en el código de la aplicación, el SDK de Microsoft Entra para AgentID controla la administración de tokens, la validación y las llamadas API a través de solicitudes HTTP estándar.

Este enfoque permite arquitecturas de microservicios poliglot en las que se pueden escribir distintos servicios en Python, Node.js, Go, Java y otros, a la vez que se mantienen patrones de autenticación coherentes.

La arquitectura típica es la siguiente:

Aplicación cliente → Your Web API → Microsoft Entra SDK para AgentID → Microsoft Entra ID

Para ver las etiquetas de versión y imagen de contenedor más recientes, consulte La imagen de contenedor para empezar.

Security

Asegúrese de que la implementación del SDK de Microsoft Entra para AgentID sigue los procedimientos recomendados para una operación segura. El SDK debe ejecutarse en un entorno en contenedores con acceso restringido a la red para evitar el acceso no autorizado. Exponer la API del SDK públicamente puede provocar vulnerabilidades de seguridad, como la adquisición de tokens no autorizada.

Consulte Mejores Prácticas de Seguridad para obtener recomendaciones sobre la seguridad de la red, las credenciales y en tiempo de ejecución.

Quick Start

Para empezar a trabajar con Microsoft Entra SDK para AgentID, se recomiendan los pasos siguientes:

1. Elección de la implementación : seleccione Kubernetes, Docker o AKS.
2. Configuración de opciones : Configuración de variables de entorno
3. Elegir un escenario : siga un ejemplo guiado
4. Implementación en producción : revisión de los procedimientos recomendados de seguridad

Ventajas clave

La arquitectura separa los problemas de identidad de la lógica de negocios, lo que proporciona las siguientes ventajas:

Cuándo usar el SDK de Microsoft Entra para AgentID o Microsoft.Identity.Web

Consulte Comparación con Microsoft.Identity.Web para obtener instrucciones detalladas sobre cómo elegir entre los dos enfoques.

Validación de tokens

El SDK de Microsoft Entra para AgentID valida los tokens de acceso y los tokens de identificador emitidos por el identificador de Entra de Microsoft, comprobando sus firmas con las claves públicas de Microsoft Entra, comprobando los tiempos de expiración y asegurándose de que los tokens están diseñados para la aplicación. Una vez validado, puede extraer reclamaciones, roles y alcances de usuario para tomar decisiones de autorización informadas dentro de la lógica de la aplicación.

Creación de encabezado para obtención y autorización de tokens.

• Flujo de On-Behalf-Of OAuth 2.0 - delegación del contexto del usuario a las API descendentes
• Credenciales de cliente : autenticación de aplicación a aplicación
• Identidad administrada: autenticación de servicio de Azure nativa
• Identidad del agente : patrones de agente autónomos o delegados

Llamadas API descendentes

• Adquiere y adjunta tokens automáticamente
• Invalidaciones de solicitud opcionales (ámbitos, método, encabezados)
• Compatibilidad con solicitudes HTTP firmadas (PoP/SHR)

Escenarios y tutoriales

Las siguientes guías son tutoriales detallados completos con ejemplos de código prácticos que muestran cómo integrar Microsoft Entra SDK para AgentID en las aplicaciones. Cada escenario proporciona ejemplos completos de solicitud/respuesta, fragmentos de código e patrones de implementación adaptados a diferentes lenguajes de programación y marcos.

Patrones de arquitectura

Un flujo típico en el que el cliente llama a una API web, la API delega las operaciones de identidad al SDK de Microsoft Entra para AgentID a través de puntos de conexión HTTP. El SDK valida los tokens de entrada mediante el /Validate punto de conexión, adquiere tokens mediante /AuthorizationHeader y /AuthorizationHeaderUnauthenticatedy puede invocar directamente las API de bajada mediante /DownstreamApi y /DownstreamApiUnauthenticated.

Interactúa con microsoft Entra ID para la emisión de tokens y la recuperación de metadatos de Open ID Connect, con la arquitectura que se muestra en el siguiente fragmento de código:

%%{init: {
  "theme": "base",
  "themeVariables": {
    "background": "#121212",
    "primaryColor": "#1E1E1E",
    "primaryBorderColor": "#FFFFFF",
    "primaryTextColor": "#FFFFFF",
    "textColor": "#FFFFFF",
    "lineColor": "#FFFFFF",
    "labelBackground": "#000000"
  }
}}%%
flowchart LR
    classDef dnode fill:#1E1E1E,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF
    linkStyle default stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF

    client[Client Application]:::dnode -->| Bearer over HTTP | webapi[Web API]:::dnode
    subgraph Pod / Host
        webapi -->|"/Validate<br/>/AuthorizationHeader/{name}<br/>/DownstreamApi/{name}"| sidecar[Microsoft Entra SDK for AgentID]:::dnode
    end
    sidecar -->|Token validation & acquisition| entra[Microsoft Entra ID]:::dnode

Soporte y recursos

Los siguientes recursos proporcionan instrucciones completas y ayudan a solucionar problemas y respuestas a preguntas comunes.

Para obtener ayuda adicional:

• Notificar problemas en el repositorio Microsoft-identity-web
• Consulte las guías de solución de problemas de Microsoft Entra ID

Recursos adicionales

• Documentación de Microsoft Entra ID
• Documentación de la Plataforma de identidad de Microsoft
• Repositorio web de identidad de Microsoft
• Documentación de Kubernetes
• Documentación de Docker