Registro personalizado de la aplicación cliente para la CLI del Agente 365

La CLI de Agente 365 necesita un registro de aplicación cliente personalizado en tu inquilino de Microsoft Entra ID para autenticar y administrar planos de identidad de agentes.

Este artículo desglosa el proceso en cuatro pasos principales:

Solicitud de registro
Establecer el URI de redirección
Copiar ID de la aplicación (cliente)
Configuración de permisos de APIRequiere privilegios de administrador

Si tienes problemas, consulta la sección de Solución de problemas .

Prerrequisitos

Antes de comenzar, asegúrese de que tiene acceso a Centro de administración Microsoft Entra y, si es necesario, uno de los roles de administrador necesarios para conceder consentimiento.

Para registrarse en la aplicación

De forma predeterminada, cualquier usuario del inquilino puede registrar aplicaciones en el Centro de administración de Microsoft Entra. Sin embargo, los administradores de inquilinos pueden restringir esta capacidad. Si no puedes registrar tu aplicación, contacta con tu administrador.

Necesitas uno de estos roles administrativos para 4. Configura los permisos de la API.

Administrador de Solicitudes: Recomendado - puede gestionar registros de aplicaciones y conceder el consentimiento
Administrador de aplicaciones en la nube: Puede gestionar registros de aplicaciones y conceder el consentimiento
Administrador Global: Tiene todos los permisos, pero no es obligatorio

Tip

¿No tienes acceso de administrador? Puedes completar los pasos 1-3 tú mismo y luego pedir a tu administrador de inquilinos que complete el paso 4. Proporciónales tu ID de aplicación (cliente) del paso 3 y un enlace a la sección Configurar permisos de API.

Tip

Los administradores globales pueden omitir el registro manual. Ejecute a365 setup requirements y, si la aplicación no se encuentra en el Agent 365 CLI inquilino, la CLI le pedirá que la cree y conceda el consentimiento del administrador automáticamente. Escriba C en la terminal para crear la aplicación en un solo paso. Si usa esta ruta de acceso automatizada, puede omitir los pasos de esta sección.

1. Solicitud de registro

Estas instrucciones resumen las instrucciones completas para crear un registro de una aplicación.

Vaya al Centro de administración de Microsoft Entra
Seleccione registros de aplicaciones
Seleccionar Nuevo registro
Escriba:
- Nombre: Introduce un nombre significativo para tu aplicación, como my-agent-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.
  
  Tip
  
  Si quieres usar el flujo sin configuración de a365 setup all --agent-name, nombra la aplicación exactamente Agent 365 CLI. La CLI busca automáticamente la aplicación cliente con este nombre de visualización conocido, por lo que no es necesario copiar el identificador de cliente en un archivo de configuración.
- Tipos de cuentas soportados: Cuentas solo en este directorio organizacional (Inquilino único)
- Redirigir URI: Selecciona Cliente público/nativo (móvil y escritorio) e introduce http://localhost:8400/
Seleccione Registrar.

La CLI requiere tres URI de redirección en total. La CLI agrega automáticamente los que faltan al ejecutar a365 setup requirements:

URI	Propósito
`http://localhost:8400/`	Biblioteca de autenticación de Microsoft (MSAL) autenticación interactiva del explorador
`http://localhost`	SDK de PowerShell en Microsoft Graph `Connect-MgGraph`
`ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}`	Uso del Administrador de cuentas web (WAM)

Consulte What the CLI auto-configures (Configuración automática de la CLI ) para obtener más información.

2. Establecer el URI de redirección

Ve a Resumen y copia el valor ID de la aplicación (cliente ).
Ve a Autenticación (vista previa) y selecciona Añadir URI de redirección.
Selecciona aplicaciones móviles y de escritorio y establece el valor en ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}, donde {client-id} es el valor de la aplicación (ID del cliente) que copiaste.
Selecciona Configurar para añadir el valor.

3. Copiar el ID de la aplicación (cliente)

Desde la página de Resumen de la app, copia el ID de la aplicación (cliente) en formato GUID. Este valor se usa al ejecutar a365 setup all o al crear a365.config.jsonmanualmente .

Tip

No confunda este valor con el identificador de objeto : necesita el identificador de aplicación (cliente).

Si llamó a su aplicación Agent 365 CLI en el paso 1, puede omitir este paso cuando use a365 setup all --agent-name. La CLI resuelve automáticamente el identificador de cliente por el nombre de pantalla.

4. Configurar permisos de la API

Importante

Necesitas privilegios de administrador para este paso. Si eres un desarrollador sin acceso de administrador, envía tu ID de aplicación (cliente) desde el Paso 3 a tu administrador de inquilinos y que complete este paso.

Nota:

A partir de diciembre de 2025, los permisos AgentIdentityBlueprint.*, AgentInstance.* y AgentIdentity.* son API beta y es posible que no estén visibles en el Centro de administración Microsoft Entra. Si estos permisos están generalmente disponibles en tu entorno, puedes usar la Opción A para todos los permisos.

Elige el método adecuado:

Opción A: Utiliza el centro de administración de Microsoft Entra para gestionar todos los permisos (si los permisos beta están visibles)
Option B: Use Microsoft Graph API para agregar todos los permisos (recomendado si los permisos beta no están visibles)

Opción A: Centro de administración Microsoft Entra (método estándar)

Use este método si puede ver los permisos de la versión beta en su entorno.

En el registro de la aplicación, vaya a Permisos de API.
Seleccione Agregar un permiso>Microsoft Graph>Permisos delegados.

Importante

Debe usar permisos delegados (no permisos de aplicación). La CLI se autentica de forma interactiva: tú inicias sesión y actúa en tu nombre. Para más información, consulte Tipo de permiso incorrecto.

Agregue estos trece permisos uno por uno:

Permiso	Propósito
`AgentIdentityBlueprintPrincipal.Create`	Crear el principal de servicio de Agent Blueprint (API beta)
`AgentIdentityBlueprint.ReadWrite.All`	Configurar configuraciones de Agent Blueprint (API beta)
`AgentIdentityBlueprint.UpdateAuthProperties.All`	Actualizar permisos heredables de Agent Blueprint (API beta)
`AgentIdentityBlueprint.AddRemoveCreds.All`	Adición o eliminación de secretos de cliente y credenciales de identidad federada en planos técnicos (API beta)
`AgentIdentityBlueprint.DeleteRestore.All`	Eliminar aplicaciones de Modelo de Agente durante la limpieza (API beta)
`AgentInstance.ReadWrite.All`	Registro y administración de instancias de agente a través de la API del Registro del agente (API beta)
`AgentIdentity.Create.All`	Creación de identidades de agente a partir de planos técnicos (API beta)
`AgentIdentity.DeleteRestore.All`	Eliminación de entidades de servicio de identidad del agente durante la limpieza (API beta)
`AgentIdentity.Read.All`	Leer datos de identidad del agente (API beta)
`AgentRegistration.ReadWrite.All`	Leer y escribir todos los registros de agente
`DelegatedPermissionGrant.ReadWrite.All`	Conceder permisos para planos de agentes
`Directory.Read.All`	Leer datos de directorios para validación
`User.Read`	Leer el perfil de usuario que ha iniciado sesión para la asignación del propietario del plano técnico

Nota:

AgentRegistration.ReadWrite.All es necesario para la configuración del agente. La CLI adquiere este permiso automáticamente a través de .default, y el validador de la CLI del Agente 365 no lo comprueba explícitamente, pero debe estar presente en el registro de la aplicación y contar con el consentimiento del administrador.

Para cada permiso:

En el cuadro de búsqueda, escribe el nombre del permiso (por ejemplo, AgentIdentityBlueprint.ReadWrite.All).
Marca la casilla de verificación junto al permiso.
Seleccione Agregar permisos.
Repita los trece permisos.

Seleccione Conceder consentimiento administrativo para [Tu Inquilino].
- ¿Por qué es esto necesario? Los esquemas de identidad del agente son recursos a nivel de inquilino a los que pueden hacer referencia varios usuarios y aplicaciones. Sin el consentimiento de todo el inquilino, la CLI falla durante la autenticación.
- ¿Y si falla? Necesitas un rol de Administrador de Aplicaciones, Administrador de Aplicaciones en la Nube o Administrador Global. Pide ayuda a tu administrador de inquilino.
Verifica que todos los permisos muestren marcas de verificación verdes en Estado.

Si los permisos beta (AgentIdentityBlueprint.*) no están visibles, continúe con la opción B.

Opción B: Microsoft Graph API (para permisos beta)

Use este método si Centro de administración Microsoft Entra no muestra los permisos AgentIdentityBlueprint.*.

Advertencia

Si usa este método de API, no use el botón "Conceder consentimiento de administrador" del centro de administración de Microsoft Entra después. El método de API concede el consentimiento del administrador automáticamente y el uso del botón Centro de administración Microsoft Entra elimina los permisos beta. Para más información, véase Desaparición de permisos Beta.

Abra el Explorador de Graph.
Inicia sesión con tu cuenta de administrador (Administrador de Aplicaciones o Administrador de Aplicaciones en la Nube).
Conceda el consentimiento del administrador mediante Graph API. Para completar este paso, necesita lo siguiente:
- ID del principal de servicio. Necesitas un SP_OBJECT_ID valor variable.
- ID de recurso en el grafo. Necesitas un GRAPH_RESOURCE_ID valor variable.
- Crear (o actualizar) permisos delegados usando el tipo de recurso oAuth2PermissionGrant con los valores de las variables SP_OBJECT_ID y GRAPH_RESOURCE_ID.

Utiliza la información de las siguientes secciones para completar estos pasos.

Consigue tu ID de principal de servicio

Un principal de servicio es la identidad de tu aplicación en tu inquilino. Lo necesitas antes de poder conceder permisos a través de la API.

Configura el método Graph Explorer en GET y usa esta URL. Sustituye <YOUR_CLIENT_APP_ID> por el ID real de tu cliente de aplicación del Paso 3: Copiar ID de aplicación (cliente):
```
https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '<YOUR_CLIENT_APP_ID>'&$select=id
```
Seleccione Ejecutar consulta.
- Si la consulta tiene éxito, el valor devuelto es tu SP_OBJECT_ID.
- Si la consulta falla por un error de permisos, selecciona la pestaña Modificar permisos , consiente los permisos requeridos y luego selecciona Ejecutar consulta de nuevo. El valor devuelto es su SP_OBJECT_ID.
- Si la consulta devuelve resultados vacíos ("value": []), crea el principal de servicio usando los siguientes pasos:
  1. Establecer el método para POST y usar esta URL:
```
https://graph.microsoft.com/v1.0/servicePrincipals
```
    Cuerpo de la solicitud (reemplazar YOUR_CLIENT_APP_ID por el ID real de tu cliente de la Aplicación):
```
{
   "appId": "YOUR_CLIENT_APP_ID"
}
```
  2. Seleccione Ejecutar consulta. Deberías recibir una 201 Created respuesta. El valor devuelto de id es su SP_OBJECT_ID.

Consigue tu ID de recurso de Graph

Configura el método Explorador de Grafos en GET y usa esta URL:

https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'&$select=id

Seleccione Ejecutar consulta.
- Si la consulta tiene éxito, copia el id valor. Este valor es tu GRAPH_RESOURCE_ID.
- Si la consulta falla por un error de permisos, selecciona la pestaña Modificar permisos , consiente los permisos requeridos y luego selecciona Ejecutar consulta de nuevo. Copie el valor id. Este valor es tu GRAPH_RESOURCE_ID.

Crear permisos delegados

Esta llamada API concede el consentimiento del administrador a nivel de inquilino para los trece permisos, incluidos los permisos beta que no son visibles en el Centro de administración de Microsoft Entra.

Configura el método Explorador de Grafos en POST y usa esta URL y cuerpo de la solicitud:

https://graph.microsoft.com/v1.0/oauth2PermissionGrants

Cuerpo de la solicitud:

{
"clientId": "<SP_OBJECT_ID>",
"consentType": "AllPrincipals",
"principalId": null,
"resourceId": "<GRAPH_RESOURCE_ID>",
"scope": "AgentIdentityBlueprintPrincipal.Create AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All AgentIdentityBlueprint.AddRemoveCreds.All AgentIdentityBlueprint.DeleteRestore.All AgentInstance.ReadWrite.All AgentIdentity.Create.All AgentIdentity.DeleteRestore.All AgentIdentity.Read.All AgentRegistration.ReadWrite.All DelegatedPermissionGrant.ReadWrite.All Directory.Read.All User.Read"
}

Seleccione Ejecutar consulta.
- Si recibes 201 Created respuesta: ¡Éxito! El scope campo de la respuesta muestra los trece nombres de permisos. Ya ha terminado.
- Si la consulta falla con un error de permisos (probablemente DelegatedPermissionGrant.ReadWrite.All), selecciona la pestaña Modificar permisos , consiente a DelegatedPermissionGrant.ReadWrite.All, y luego selecciona Ejecutar consulta de nuevo.
- Si recibes error Request_MultipleObjectsWithSameKeyValue: Ya existe una subvención. Quizá alguien añadió permisos antes. Consulta los siguientes permisos delegados de actualización.

Advertencia

La solicitud consentType: "AllPrincipals" en POSTya concede el consentimiento administrativo para todo el inquilino. NO selecciones "Conceder consentimiento del administrador" en el centro de administración de Microsoft Entra después de usar este método de API: si lo haces, elimina tus permisos beta porque el centro de administración de Microsoft Entra no puede ver los permisos beta y sobrescribe el consentimiento otorgado por la API solo con los permisos visibles.

Actualizar permisos delegados

Cuando detectes un Request_MultipleObjectsWithSameKeyValue error al usar los pasos para crear permisos delegados, usa estos pasos para actualizar los permisos delegados.

Configura el método Explorador de Grafos en GET y usa esta URL:

https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq 'SP_OBJECT_ID_FROM_ABOVE'

Seleccione Ejecutar consulta. Copie el valor id de la respuesta. Este valor es YOUR_GRANT_ID.

Configura el método Explorador de Grafos en PATCH y usa esta URL con YOUR_GRANT_ID.

https://graph.microsoft.com/v1.0/oauth2PermissionGrants/<YOUR_GRANT_ID>

Cuerpo de la solicitud:

{
   "scope": "AgentIdentityBlueprintPrincipal.Create AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All AgentIdentityBlueprint.AddRemoveCreds.All AgentIdentityBlueprint.DeleteRestore.All AgentInstance.ReadWrite.All AgentIdentity.Create.All AgentIdentity.DeleteRestore.All AgentIdentity.Read.All AgentRegistration.ReadWrite.All DelegatedPermissionGrant.ReadWrite.All Directory.Read.All User.Read"
}

Seleccione Ejecutar consulta. Debería obtener una respuesta 200 OK con los trece permisos en el campo scope.

Prácticas recomendadas de seguridad

Revisa estas pautas para mantener tu registro en la aplicación seguro y conforme a la normativa.

Sí:

Utiliza el registro de inquilino único.
Concede solo los permisos delegados necesarios.
Auditar permisos regularmente.
Quita la app cuando ya no sea necesaria.

No haga lo siguiente:

Conceda permisos de aplicación. Solo utiliza "delegated".
Comparte públicamente el ID del cliente.
Concede otros permisos innecesarios.
Usa la app para otros fines.

Lo que la CLI configura automáticamente

Al ejecutar a365 setup requirements, la CLI valida el registro de la aplicación y puede que tenga que realizar cambios. Antes de aplicar los cambios, la CLI muestra un resumen y solicita confirmación:

WARNING: The CLI needs to make the following changes to your app registration (<app-id>):

  - Add redirect URI(s): http://localhost
  - Enable 'Allow public client flows' (isFallbackPublicClient = true)

Do you want to proceed? (y/N):

Para omitir el mensaje de confirmación (por ejemplo, en un entorno de CI), use la --yes marca :

a365 setup requirements --yes

En la tabla siguiente se describe cada cambio que podría realizar la CLI:

Cambiar	Motivo
Agregar URI de redirección `http://localhost`	SDK de PowerShell en Microsoft Graph requiere este URI para la autenticación del explorador. Sin él, las operaciones de concesión de OAuth2 se revierten a un token que carece de los permisos delegados necesarios y fallan con un error 403.
Agregar URI de redirección `http://localhost:8400/`	MSAL requiere este URI para la autenticación interactiva del explorador.
Agregar URI de redirección `ms-appx-web://Microsoft.AAD.BrokerPlugin/{id}`	Necesario para el Administrador de cuentas web (WAM), un agente de autenticación del sistema operativo Windows. Obtenga más información sobre la adquisición de tokens enlazados a dispositivos.
Habilitar "Permitir flujos de cliente públicos"	Se requiere para la autenticación alternativa con código de dispositivo en macOS, Linux, Subsistema de Windows para Linux (WSL), entornos sin interfaz gráfica y como alternativa de política de acceso condicional en Windows.
Adición de permisos que faltan al registro de aplicaciones	Mantiene el registro de la aplicación sincronizado con los permisos recién necesarios después de una actualización de la CLI.
Extensión de la concesión de consentimiento del administrador	Amplía la concesión de permisos de OAuth2 existente para incluir los permisos recién aprovisionados. Requiere que `DelegatedPermissionGrant.ReadWrite.All` ya haya dado su consentimiento.

Si rechaza el mensaje, la CLI no modifica el registro de la aplicación. Si los cambios son necesarios para que funcione la CLI, puede configurarlos manualmente en el Centro de administración de Microsoft Entra o volver a ejecutar el comando con --yes.

Pasos siguientes

Después de registrar la aplicación cliente personalizada, úsela con la CLI del Agente 365 para completar la configuración del agente 365:

Introducción al desarrollo del Agente 365

Solución de problemas

Esta sección describe cómo solucionar errores con el registro personalizado de la aplicación cliente.

Tip

La Guía de Resolución de Problemas del Agente 365 contiene recomendaciones de alto nivel para la solución de problemas, mejores prácticas y enlaces a contenido de solución de problemas para cada parte del ciclo de vida del desarrollo del Agente 365.

La validación de la CLI falla durante la configuración

Síntoma: La ejecución de a365 setup o a365 setup requirements falla con errores de validación sobre tu aplicación cliente personalizada.

Solución: Utiliza esta lista de comprobación para verificar que tu registro en la aplicación es correcto:

# Run requirements validation to see validation messages
a365 setup requirements

Resultado esperado: El CLI muestra Custom client app validation successful.

Si no obtienes el resultado esperado, verifica cada una de las siguientes comprobaciones:

Activar	Cómo verificar	Corregir
✅ Uso de ID correcto	Copiaste el ID de la aplicación (cliente ) (no el ID del objeto)	Vaya a la aplicación Visión general en el centro de administración de Microsoft Entra
✅ Permisos delegados	Permisos mostrar Tipo: Delegado en permisos API	Ver Tipo de permiso incorrecto
✅ Todos los permisos añadidos	Consulta todos los permisos listados a continuación	Sigue el Paso 4 de nuevo
✅ Consentimiento del administrador concedido	Todos muestran la marca de verificación verde bajo Estado	Ver Consentimiento del administrador concedido incorrectamente

Permisos delegados requeridos:

AgentIdentityBlueprintPrincipal.Create [Beta]
AgentIdentityBlueprint.ReadWrite.All [Beta]
AgentIdentityBlueprint.UpdateAuthProperties.All [Beta]
AgentIdentityBlueprint.AddRemoveCreds.All [Beta]
AgentIdentityBlueprint.DeleteRestore.All [Beta]
AgentInstance.ReadWrite.All [Beta]
AgentIdentity.Create.All [Beta]
AgentIdentity.DeleteRestore.All [Beta]
AgentIdentity.Read.All [Beta]
AgentRegistration.ReadWrite.All
DelegatedPermissionGrant.ReadWrite.All
Directory.Read.All
User.Read

Síntoma: Se produce un error en la validación aunque haya agregado permisos.

Causa principal: No concedió el consentimiento del administrador o lo concedió incorrectamente.

Solución: En el registro de la aplicación en el Centro de administración de Microsoft Entra, vaya a permisos de API y seleccione Otorgar consentimiento de administrador para [Su inquilino]. Verifica que todos los permisos muestren marcas de verificación verdes en Estado.

Tipo de permiso incorrecto

Síntoma: La CLI falla con errores de autenticación o denegación de permiso.

Causa raíz: Has añadido permisos de aplicación en lugar de permisos delegados.

Esta tabla describe los diferentes tipos de permisos.

Tipo de permiso	Cuándo usar	Cómo la utiliza la CLI del Agente 365
Delegado ("Alcance")	El usuario inicia sesión de forma interactiva	Agent 365 CLI utiliza esto : tú inicias sesión, CLI actúa en tu nombre
Aplicación ("Rol")	El servicio se ejecuta sin usuario	No usarlo - Solo para servicios en segundo plano/demonios

¿Por qué delegar?

Inicias sesión de forma interactiva (autenticación del navegador)
CLI realiza acciones como tú (las auditorías muestran tu identidad)
Más seguro, limitado por tus permisos reales
Garantiza la rendición de cuentas y el cumplimiento

Solución:

Vaya al centro de administración de Microsoft Entra>Registros de aplicaciones> Su aplicación >Permisos de API
Elimina cualquier permiso de la aplicación. Estos permisos aparecen como Aplicación en la columna de Tipo .
Añade los mismos permisos que los permisos delegados .
Concede el consentimiento administrativo de nuevo.

Síntoma: Ha usado Opción B: Microsoft Graph API (Para permisos beta) para agregar permisos beta, pero desaparecen después de seleccionar Conceder consentimiento de administrador en el centro de administración de Microsoft Entra.

Causa raíz: Centro de administración Microsoft Entra no muestra permisos beta en la interfaz de usuario. Cuando seleccionas Conceder consentimiento de administrador, el portal concede consentimiento solo para los permisos visibles y sobrescribe el consentimiento concedido por la API.

Por qué sucede esto:

Use el Graph API (opción B) para agregar todos los trece permisos, incluidos los permisos beta.
La llamada API consentType: "AllPrincipals"otorga ya el consentimiento de administrador a nivel de inquilino.
Vaya a Centro de administración Microsoft Entra y vea solo un subconjunto de permisos porque los permisos beta son invisibles en el portal.
Seleccionas Conceder consentimiento de administrador pensando que lo necesitas.
Centro de administración Microsoft Entra sobrescribe el consentimiento concedido por la API con solo los permisos visibles.
Ahora se eliminan los permisos beta.

Solución:

No use el consentimiento de administrador del centro de administración de Microsoft Entra después del método de API: el método de API ya concede el consentimiento de administrador.
Si elimina accidentalmente permisos beta, vuelva a ejecutar Option B paso 3 (Conceder consentimiento de administrador mediante Graph API) para restaurarlos. Si aparece un Request_MultipleObjectsWithSameKeyValue error, sigue los pasos para actualizar permisos delegados.
Para comprobar que se enumeran los trece permisos, compruebe el campo scope en la respuesta POST o PATCH.

App no encontrada durante la validación

Síntoma: CLI informa de Application not found o Invalid client ID errores.

Solution:

Verifica que has copiado el ID de la aplicación (cliente) en formato GUID, no el ID del objeto:
- Vaya al centro de administración Microsoft Entra>Registros de aplicaciones> Su aplicación >Visión general
- Copia el valor bajo ID de aplicación (cliente)
- El formato debe ser: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Verifica que la app exista en tu inquilino:

# Sign in to the correct tenant
az login

# List your app registrations
az ad app list --display-name "<The display name of your app>"

Learn cómo registrar una aplicación en Microsoft Entra ID.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-05-01