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

La CLI del Agente 365 necesita un registro de aplicación cliente personalizado en el inquilino de Microsoft Entra ID para autenticar y administrar planos técnicos de identidad del agente.

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

1. Solicitud de registro
2. Establecer el URI de redirección
3. Copiar ID de la aplicación (cliente)
4. Configuración de permisos de API

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.

Añadir permisos y conceder consentimiento

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

1. Solicitud de registro

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

1. Vaya a Microsoft Entra centro de administración

2. Seleccione registros de aplicaciones

3. Seleccionar Nuevo registro

4. Ingrese:

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

     Sugerencia

     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/

5. Seleccione Registrar.

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

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

1. Ve a Resumen y copia el valor ID de la aplicación (cliente ).
2. Ve a Autenticación (vista previa) y selecciona Añadir URI de redirección.
3. Seleccione Aplicaciones móviles y de escritorio y establezca el valor en ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}, donde {client-id} es el Application (id. de cliente) valor que copió.
4. 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. Introduce este valor cuando uses el a365 config init comando.

4. Configurar permisos de la API

Elige el método adecuado:

• Option A: Use Centro de administración Microsoft Entra para todos los permisos (si los permisos beta son 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.

1. En el registro de la aplicación, vaya a Permisos de API.

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

3. Agregue estos doce 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)
   AgentRegistrations.ReadWrite.All	Registro y administración de agentes a través de agent registrations API (API beta)
   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:

   AgentRegistrations.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 doce permisos.

4. Seleccione Conceder consentimiento administrativo para [Tu 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 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.*.

1. Abra el Explorador de Graph.

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

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

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

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

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 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 de API otorga su consentimiento a nivel de inquilino para los doce permisos, incluidos los 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": "AgentIdentityBlueprintPrincipal.Create AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All AgentIdentityBlueprint.AddRemoveCreds.All AgentIdentityBlueprint.DeleteRestore.All AgentInstance.ReadWrite.All AgentIdentity.Create.All AgentIdentity.DeleteRestore.All AgentRegistrations.ReadWrite.All DelegatedPermissionGrant.ReadWrite.All Directory.Read.All User.Read"
   }
   

2. Seleccione Ejecutar consulta.

   • Si recibes 201 Created respuesta: ¡Éxito! El scope campo de la respuesta muestra los doce 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.

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.

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 id valor de la respuesta. Este valor es YOUR_GRANT_ID.

3. 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 AgentRegistrations.ReadWrite.All DelegatedPermissionGrant.ReadWrite.All Directory.Read.All User.Read"
   }
   

4. Seleccione Ejecutar consulta. Debería recibir una 200 OK respuesta que incluya los doce permisos en el campo scope.

Procedimientos recomendados 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. Utilice únicamente delegado.
• 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 config init o a365 setup requirements, la CLI valida el registro de la aplicación y es posible 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 config init --yes

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

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

Pasos siguientes

Después de registrar tu aplicación cliente personalizada, úsala con la CLI de Agent 365 en el ciclo de vida de desarrollo de Agent 365:

Solución de problemas

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

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

Síntoma: la ejecución del a365 config init comando o a365 setup falla con errores de validación en la aplicación cliente personalizada.

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

# Run configuration to see validation messages
a365 config init

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

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

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]
• DelegatedPermissionGrant.ReadWrite.All
• Directory.Read.All
• User.Read

Consentimiento del administrador concedido incorrectamente

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.

Solution: En el registro de la aplicación en 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.

¿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. Vaya a Centro de administración Microsoft Entra>Registros de aplicaciones> Su aplicación >permisos de API
2. Elimina cualquier permiso de la aplicación. Estos permisos aparecen como Aplicación en la columna de Tipo .
3. Añade los mismos permisos que los permisos delegados .
4. Concede el consentimiento administrativo de nuevo.

Los permisos beta desaparecen después del consentimiento del administrador en el centro de administración de Microsoft Entra

Symptom: Ha usado Option B: Microsoft Graph API (Para permisos beta) para agregar permisos beta, pero desaparecen después de seleccionar Consiente de administrador en Centro de administración 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:

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

Solución:

• No uses el Centro de administración de Microsoft Entra para el consentimiento del administrador después del método de API: el método de API ya concede el consentimiento del 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 verificar que se muestran los once 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:

1. Verifica que has copiado el ID de la aplicación (cliente) en formato GUID, no el ID del objeto:

   • Vaya a Centro de administración Microsoft Entra>Registros de aplicaciones> Su aplicación >Descripción general
   • Copia el valor bajo ID de aplicación (cliente)
   • El formato debe ser: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

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