Compartir a través de

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

Importante

Debe formar parte del programa de versión preliminar de Frontier para obtener acceso anticipado a Microsoft Agent 365. Frontier le conecta directamente con las innovaciones de inteligencia artificial más recientes de Microsoft. Las versiones preliminares de Frontier están sujetas a los términos de vista previa existentes en tus acuerdos con clientes. Dado que estas características siguen en desarrollo, su disponibilidad y funcionalidades pueden cambiar con el tiempo.

La CLI del Agente 365 requiere un registro personalizado de la aplicación cliente en tu tenant Microsoft Entra ID para autenticar y gestionar los Planos de Identidad del Agente.

Prerrequisitos

Para registrar la aplicación (Pasos 1 y 2):

Para añadir permisos y conceder consentimiento (Paso 3):

Sugerencia

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

Paso 1: Registrar la solicitud

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

  1. Visita el centro de administración de Microsoft Entra
  2. Selecciona registros de aplicaciones
  3. Seleccionar Nuevo registro
  4. Entrar:
    • Nombre: Agent365 CLI (o tu nombre preferido)
    • Tipos de cuentas soportados: Cuentas solo en este directorio organizacional (Inquilino único)
    • Redirigir URI: Seleccione cliente público/nativo (móvil y escritorio) → Enter http://localhost:8400/
  5. Seleccione Registrar.

Paso 2: 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) (formato GUID). Introduce este valor cuando uses el a365 config init comando.

Sugerencia

No confundas este valor con el ID de objeto : necesitas el ID de aplicación (cliente).

Paso 3: Configurar permisos de API

Importante

Se requieren 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 2 a tu administrador de inquilinos y que complete el Paso 3.

Nota:

A diciembre de 2025, ambos AgentIdentityBlueprint.* permisos son APIs beta y puede que no sean visibles en el centro de administración de Microsoft Entra. Si estos permisos se vuelven generalmente disponibles en tu inquilino, puedes usar la Opción A para todos los permisos.

Elige el método adecuado:

  • Opción A: Usar el centro de administración de Microsoft Entra para todos los permisos (si los permisos beta son visibles)
  • Opción B: Usar la API de Microsoft Graph para añadir todos los permisos (recomendado si los permisos beta no son visibles)

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

Utiliza este método si los permisos beta son visibles en tu tenant.

  1. En el registro de tu app, ve a permisos de la API

  2. Seleccione Añadir permiso → Microsoft Graph → Permisos delegados

    Importante

    DEBES 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. Consulta Tipo de permiso incorrecto si accidentalmente añades permisos de aplicación.

  3. Añade estos cinco permisos uno por uno:

    Permiso Propósito
    AgentIdentityBlueprint.ReadWrite.All Configurar configuraciones de Agent Blueprint (API beta)
    AgentIdentityBlueprint.UpdateAuthProperties.All Actualizar permisos heredables de Agent Blueprint (API beta)
    Application.ReadWrite.All Crear y gestionar aplicaciones y planos de agentes
    DelegatedPermissionGrant.ReadWrite.All Conceder permisos para planos de agentes
    Directory.Read.All Leer datos de directorios para validación

    Para cada permiso:

    • En el cuadro de búsqueda, escribe el nombre del permiso (por ejemplo, AgentIdentityBlueprint.ReadWrite.All)
    • Marca la casilla junto al permiso
    • Seleccione Agregar permisos.
    • Repite para los cinco permisos

  4. Seleccione Conceder consentimiento administrativo para [Su Inquilino]

    • ¿Por qué es esto obligatorio? Los Planos de Identidad de Agente son recursos a nivel de inquilino que múltiples usuarios y aplicaciones pueden consultar. 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.

  5. Verifica que todos los permisos muestren marcas de verificación verdes bajo Estado

Si los permisos beta (AgentIdentityBlueprint.*) no son visibles, proceda a la Opción B.

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

Utiliza este método si AgentIdentityBlueprint.* los permisos no son visibles en el centro de administración de Microsoft Entra.

Advertencia

Si utilizas este método de API, NO uses el botón "Conceder consentimiento de administrador" del centro de administración de Microsoft Entra después. El método de la API otorga el consentimiento del administrador automáticamente, y usar el botón del centro de administración de Microsoft Entra elimina tus permisos beta. Consulta permisos beta desaparecidos para más detalles.

  1. Open Graph Explorer

  2. Inicia sesión con tu cuenta de administrador (Administrador de Aplicaciones o Administrador de Aplicaciones en la Nube)

  3. Concede el consentimiento del administrador usando la API de Graph. Para completar esto, necesitas:

    • ID del principal de servicio. Necesitarás un SP_OBJECT_ID valor variable.
    • ID de recurso en el grafo. Necesitarás un GRAPH_RESOURCE_ID valor variable.
    • Crear (o actualizar) permisos delegados usando el tipo de recurso oAuth2PermissionGrant con los SP_OBJECT_ID valores de variables y GRAPH_RESOURCE_ID .

Utiliza la información de las siguientes secciones para completarlo.

Consigue tu ID de principal de servicio

Un principal de servicio es la identidad de tu app en tu tenant, necesaria antes de conceder permisos mediante API.

  1. Configura el método Explorador de Grafos en GET y usa esta URL (sustituye <YOUR_CLIENT_APP_ID> por el ID real de tu cliente de aplicación en el Paso 2: Copiar ID de aplicación (cliente):

    https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '<YOUR_CLIENT_APP_ID>'&$select=id

  2. 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 tu SP_OBJECT_ID.

    • Si la consulta devuelve resultados vacíos ("value": []), crea el principal de servicio siguiendo 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 id valor devuelto es tu SP_OBJECT_ID.

Consigue tu ID de recurso de Graph

  1. 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

  2. Seleccione Ejecutar consulta.

    • Si la consulta tiene éxito, copia el id valor. Este 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 es tu GRAPH_RESOURCE_ID.

Crear permisos delegados

Esta llamada API otorga el consentimiento de administrador a nivel de inquilino para los cinco permisos, incluidos los dos permisos beta que no son visibles en el centro de administración de Microsoft Entra.

  1. 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": "Application.ReadWrite.All Directory.Read.All DelegatedPermissionGrant.ReadWrite.All AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All"
}

  2. Seleccione Ejecutar consulta.

    • Si recibes 201 Created respuesta: ¡Éxito! El scope campo en la respuesta muestra los cinco 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 , DelegatedPermissionGrant.ReadWrite.Ally luego selecciona Ejecutar consulta de nuevo.
    • Si recibes error Request_MultipleObjectsWithSameKeyValue: Ya existe una subvención. Quizá alguien añadió permisos antes. Consulta la siguiente actualización: permisos delegados.

Advertencia

La consentType: "AllPrincipals" solicitud POSTya otorga el consentimiento administrativo a todo el inquilino. NO selecciones "Conceder consentimiento de administrador" en el centro de administración de Microsoft Entra después de usar este método de API; hacerlo elimina tus permisos beta porque el centro de administración de Microsoft Entra no puede ver los permisos beta y sobrescribe tu consentimiento concedido por la API solo con los permisos visibles.

Actualizar permisos delegados

Cuando te den un Request_MultipleObjectsWithSameKeyValue error usando los pasos para crear permisos delegados, utiliza estos pasos para actualizar los permisos delegados.

  1. 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'

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

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

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

    Cuerpo de la solicitud:

    {
   "scope": "Application.ReadWrite.All Directory.Read.All DelegatedPermissionGrant.ReadWrite.All AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All"
}

  4. Seleccione Ejecutar consulta. Deberías recibir una 200 OK respuesta con los cinco permisos del scope campo.

Solución de problemas

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

Tipo de permiso incorrecto (Delegado vs Aplicación)

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.

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:

  1. Ve al centro >de administración de Microsoft EntraRegistros> de apps Permisos de la API de tu app >
  2. Elimina cualquier permiso de aplicación (estos aparecen como "Aplicación" en la columna de Tipo )
  3. Añadir los mismos permisos que permisos delegados
  4. Conceder de nuevo el consentimiento administrativo

Síntoma: Usaste la Opción B: API de Microsoft Graph (para permisos beta) para añadir permisos beta, pero desaparecieron tras seleccionar Conceder consentimiento de administrador en el centro de administración de Microsoft Entra.

Causa raíz: Microsoft Entra admin center no muestra permisos beta en la interfaz, así que cuando seleccionas Conceder consentimiento de administrador, solo concede los permisos visibles y sobrescribe el consentimiento concedido por la API.

Por qué sucede esto:

  1. Usas la API de Graph (Opción B) para añadir los cinco permisos, incluidos los permisos beta
  2. La llamada API ya consentType: "AllPrincipals"otorga el consentimiento de administrador a nivel de inquilino
  3. Vas al centro de administración de Microsoft Entra y solo ves tres permisos porque los permisos beta son invisibles
  4. Seleccionas Conceder consentimiento de administrador pensando que lo necesitas
  5. El centro de administración de Microsoft Entra sobrescribe tu consentimiento concedido por la API con solo los tres permisos visibles
  6. Tus dos permisos beta han sido eliminados

Solución:

  • Nunca uses el consentimiento de administrador del centro de administración de Microsoft Entra después del método API: El método API ya otorga el consentimiento de administrador
  • Si accidentalmente has eliminado permisos beta, vuelve a ejecutar la Opción B Paso 3 (Conceder el consentimiento del administrador usando la API de Graph) para restaurarlos. Aparece un Request_MultipleObjectsWithSameKeyValue error: sigue los pasos para actualizar permisos delegados.
  • Revisa el scope campo en o POSTPATCH respuesta para verificar que los cinco permisos están listados

Errores de validación

La CLI valida automáticamente tu aplicación cliente cuando se ejecuta a365 setup o a365 config init.

Problemas comunes:

  • No se ha encontrado la aplicación: Verifica que has copiado el ID de la aplicación (cliente ) (no el ID del objeto)
  • Permisos faltantes: Añadir los cinco permisos requeridos
  • No se concede el consentimiento del administrador:
  • Tipo de permiso incorrecto: Usa permisos delegados, no permisos de aplicación

Para una resolución detallada de problemas, consulte Registrar una aplicación en Microsoft Entra ID.

Procedimientos recomendados de seguridad

Haga lo siguiente:

  • Utiliza el registro de inquilino único
  • Concede solo los cinco permisos delegados requeridos
  • Auditar permisos regularmente
  • Elimina la app cuando ya no la necesites

No haga lo siguiente:

  • Permisos para conceder solicitudes (Usar solo Delegado)
  • Compartir el ID del cliente públicamente
  • Concede otros permisos innecesarios
  • Usa la app para otros fines

Pasos siguientes

Ahora que tienes registrada tu aplicación cliente personalizada, puedes usarla con la CLI de Agent 365:

  • Last updated on