Guía de inicio rápido: Autenticar usuarios e invocar API descendentes con el SDK de Microsoft Entra para el ID de agente en TypeScript

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 el identificador del agente 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 Node.js 18.x o posterior.
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 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 de 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:

Inicie sesión en el Centro de administración de Microsoft Entra como mínimo un Desarrollador de Aplicaciones.
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.
Vaya a Entra ID>Registros de aplicaciones y seleccione Nuevo registro.
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.

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 multitenant y quieres que los usuarios de cualquier entidad 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 personales de Microsoft	Para aplicaciones multitenant que admiten cuentas de Microsoft personales y organizativas (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).

Seleccione Registrar para completar el registro de la aplicación.
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)

Incorporación de un URI de redirección

La aplicación de ejemplo TypeScript 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:

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

Adición de credenciales de cliente

El SDK de Microsoft Entra para ID de agente usa credenciales de cliente para autenticar y adquirir tokens para las API descendentes. 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
# Replace <your-pfx-password> with a strong password and store it securely (for example, in a secret store).
$pfxPath = "agentid-client-certificate.pfx"
$certPassword = ConvertTo-SecureString -String "<your-pfx-password>" -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)"

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

Carga del certificado en Microsoft Entra ID

Siga estos pasos para subir el archivo .cer creado en su directorio actual al centro de administración de Microsoft Entra:

Abra el registro de la aplicación en el Centro de administración Microsoft Entra
En Administrar, seleccione Certificados y secretos.
En la pestaña Certificados, seleccione Cargar certificado.
Seleccione el .cer archivo que generó (por ejemplo, agentid-client-cert.cer).
Proporcione una descripción (por ejemplo, "Certificado de desarrollo local de AgentID").
Selecciona Agregar.
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. Los certificados autofirmados solo deben usarse para el desarrollo y las pruebas locales.

Configuración de permisos de API

Siga estos pasos para configurar los permisos delegados para 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.

En el registro de la aplicación, en Manage, seleccione API permissions>Add a permission>Microsoft Graph.
Seleccione Permisos delegados. Microsoft Graph expone muchos permisos, con el más usado en la parte superior de la lista.
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 identificador de agente llama a las API mediante su propia identidad (sin un contexto de usuario), configure los permisos de aplicación:

En la página permisos API, seleccione Agregar un permiso>Microsoft Graph.
Seleccione Permisos de aplicación.
En Seleccionar permisos, busque y seleccione User.Read.All.
Seleccione Agregar permisos.
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 endpoint del SDK de identificador de /validate agente con tokens emitidos específicamente para su aplicación (mediante el ámbito api://<application-client-id>/access_as_user), debe completar este paso. Si solo está probando Microsoft Graph escenarios con permisos delegados, puede omitir esta sección. Siga estos pasos para exponer una API que contenga los ámbitos necesarios:

En Administrar, seleccione Exponer una API.
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.
Seleccione Agregar un ámbito como se muestra:
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 ID de Agente como usuario
- Descripción del consentimiento del administrador: permitir el acceso a las API del SDK de id. de agente como usuario que ha iniciado sesión
- Estado: habilitado
Selecciona la opción Agregar un ámbito.

Inicio del SDK de Microsoft Entra para AgentID

El SDK de Microsoft Entra para el ID del agente es un servicio web contenedorizado que gestiona la adquisición de tokens, la validación y las llamadas API seguras de nivel inferior. 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 ID de Agente requiere un archivo de configuración para conectarse a su aplicación de Microsoft Entra. Cree un directorio para la configuración y cree un appsettings.json archivo:

# Create a directory for the Agent ID 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": "<your-pfx-password>"
            }
        ]
    },
    "DownstreamApis": {
        "me": {
            "BaseUrl": "https://graph.microsoft.com/v1.0/",
            "RelativePath": "me",
            "Scopes": [ "User.Read" ]
        }
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning"
        }
    },
    "AllowedHosts": "*"
}

Ejecutar y extraer el contenedor del SDK de Agent ID

El SDK de ID de agente está disponible como una imagen de contenedor precompilada del 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 Agent ID 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, use 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 identificación de agente se está ejecutando correctamente mediante una llamada al endpoint de verificación de estado:/healthz

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

Este punto de conexión devuelve Healthy, lo que confirma que el SDK de Agent ID se está ejecutando correctamente y está listo para manejar las solicitudes. No finalice el SDK de Identificación de Agente 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 ejemplo typeScript.

Ejecutar la aplicación de ejemplo TypeScript

La aplicación de ejemplo TypeScript muestra cómo usar el SDK de Microsoft Entra para el Agent ID para validar los tokens de usuario. La aplicación es un servidor Express.js que valida las solicitudes entrantes a través del SDK de identificador de agente. El SDK de ID de agente también puede llamar a las API descendentes, como Microsoft Graph en tu nombre.

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

Descargue la aplicación de ejemplo TypeScript 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

Después de clonar el repositorio, vaya a la aplicación de ejemplo TypeScript:

cd microsoft-identity-web/tests/DevApps/SidecarAdapter/typescript

La aplicación de ejemplo typeScript consta de tres archivos principales que funcionan juntos para demostrar patrones de autenticación con el SDK de Microsoft Entra para AgentID.

sidecar.ts: proporciona la SidecarClient clase, que es un cliente de TypeScript que se comunica con el contenedor del SDK de ID de agente. Envía tokens de portador al punto de conexión del SDK de ID del /Validate Agente, recibe el token validado junto con las afirmaciones del usuario y gestiona los errores de validación de tokens.

app.ts: un servidor web Express.js que autentica todas las solicitudes entrantes. Extrae tokens portadores del encabezado de autorización y los valida con SidecarClient. Si se produce un error en la validación, el servidor devuelve una respuesta 401 No autorizada. Cuando la validación se realiza correctamente, adjunta los reclamos del usuario al objeto de solicitud a través de req.sidecarValidation, para su uso en los controladores de ruta descendentes.

sidecar.test.ts: contiene pruebas de integración automatizadas que comprueban el flujo de autenticación completo. El conjunto de pruebas comienza iniciando el servidor Express y, a continuación, usa MSAL Node para realizar la autenticación interactiva del explorador y adquirir un token de acceso con los ámbitos necesarios. A continuación, realiza una solicitud HTTP al servidor con el token adquirido y comprueba que el SDK de identificador de agente valida el token correctamente antes de devolver las notificaciones de usuario esperadas.

Instalación de dependencias

Vaya al directorio de ejemplo de TypeScript e instale los paquetes necesarios:

cd d:\SDKs\microsoft-identity-web\tests\DevApps\SidecarAdapter\typescript
npm install

Configuración de la aplicación de ejemplo

Antes de ejecutar la aplicación de ejemplo, configúrela con los detalles de la aplicación de la siguiente manera:

Abra sidecar.test.ts y actualice el identificador de cliente, el identificador de inquilino y los ámbitos para que coincidan con el registro de la aplicación.
Cree un archivo .env en el directorio typescript para las variables de entorno.
```
# Create .env file
New-Item -ItemType File -Path ".env" -Force
```
Agregue la siguiente configuración a .env:
```
PORT=5555
SIDECAR_BASE_URL=http://localhost:5178
```

Iniciar el servidor Express

Inicie la aplicación de ejemplo TypeScript ejecutando npm start. El servidor se inicia en http://localhost:5555 y está listo para aceptar solicitudes autenticadas. Debería mostrarse una salida similar a esta:

Server listening on port 5555
Sidecar base URL: http://localhost:5178

Mantenga abierta esta ventana de terminal. El servidor Express debe seguir ejecutándose para controlar las solicitudes de prueba en la sección siguiente.

Prueba la aplicación de ejemplo de TypeScript

Ahora que tanto el contenedor del SDK de ID de agente como el servidor Express se están ejecutando, puede probar los escenarios de autenticación y llamadas a la API.

Prueba con permisos delegados por el usuario

En este escenario se muestra cómo iniciar sesión en un usuario, adquirir un token y llamar al servidor Express con ese token.

Adquisición de un token de usuario

El ejemplo incluye una prueba automatizada que adquiere un token de usuario mediante MSAL. Abra una nueva ventana de PowerShell (mantenga el servidor Express en ejecución) y ejecute lo siguiente:

cd d:\SDKs\microsoft-identity-web\tests\DevApps\SidecarAdapter\typescript
npm test

Este comando ejecuta la prueba de integración que:

Abre una ventana del explorador para la autenticación interactiva
Adquiere un token de acceso con el api://<your-client-id>/access_as_user alcance
Llama al servidor Express con el token
Comprueba que el SDK de ID de Agente valida el token correctamente.

En la primera ejecución, se le pedirá que inicie sesión con las credenciales de Microsoft Entra. La ventana del explorador se abre automáticamente. Después de la autenticación correcta, puede cerrar el explorador.

Pruebas manuales con la herramienta curl

Si prefiere pruebas manuales, puede adquirir un token y llamar directamente al servidor Express:

# First, get a token (you'll need to implement token acquisition or extract from test output)
$token = "YOUR_ACCESS_TOKEN_HERE"

# Call the Express server
Invoke-RestMethod -Uri "http://localhost:5555/api/protected" `
    -Headers @{ Authorization = "Bearer $token" } `
    -Method Get

La respuesta esperada es:

message                                                  protocol token          claims
-------                                                  -------- -----          ------
Request authenticated via Microsoft Identity Web Sidecar Bearer   ***redacted*** @{aud=api://"Your client ID"; iss=https://sts.win…

Prueba de autenticación solo para aplicaciones

En este escenario se muestra cómo invocar a las API posteriores mediante la propia identidad de la aplicación sin contexto de usuario.

Desde la ventana de PowerShell, llame directamente al SDK de ID de agente para probar el flujo exclusivo para aplicaciones.

# Call Microsoft Graph using application identity
Invoke-RestMethod -Uri "http://localhost:5178/DownstreamApiUnauthenticated/me" `
    -Method Get

Este extremo:

Autenticación mediante el certificado de la aplicación (configurado en appsettings.json)
Adquiere un token de acceso de solo aplicación para Microsoft Graph
Llama al punto de conexión del Graph API /me
Devuelve la información de la entidad de servicio.

Nota:

Este escenario requiere el permiso de User.Read.All aplicación con el consentimiento del administrador (configurado anteriormente en el inicio rápido).

Prueba de llamadas API descendentes personalizadas

Puede probar las configuraciones de API descendentes personalizadas agregándolas al SDK de ID de agente appsettings.json.

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

A continuación, reinicie el contenedor del SDK de ID de Agente y pruebe el nuevo punto de conexión:

# Restart container to reload configuration
docker restart agentid-sdk

# Test the new endpoint
Invoke-RestMethod -Uri "http://localhost:5178/DownstreamApiUnauthenticated/users" `
    -Method Get

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-04-19

Inicie sesión de usuarios y utilice las API descendentes con el SDK de Microsoft Entra para el identificador del agente en TypeScript

Prerrequisitos

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

Creación de un registro de aplicación

Incorporación de un URI de redirección

Adición de credenciales de cliente

Generación de un certificado autofirmado

Carga del certificado en Microsoft Entra ID

Configuración de permisos de API

Configuración de permisos de aplicación

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

Inicio del SDK de Microsoft Entra para AgentID

Creación de un archivo de configuración

Ejecutar y extraer el contenedor del SDK de Agent ID

Verifique que el contenedor se está ejecutando

Ejecutar la aplicación de ejemplo TypeScript

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

Instalación de dependencias

Configuración de la aplicación de ejemplo

Iniciar el servidor Express

Prueba la aplicación de ejemplo de TypeScript

Prueba con permisos delegados por el usuario

Adquisición de un token de usuario

Pruebas manuales con la herramienta curl

Prueba de autenticación solo para aplicaciones

Prueba de llamadas API descendentes personalizadas

Contenido relacionado

Comentarios

Recursos adicionales