Registro personalizado de la aplicación cliente para Agent 365 CLI

La interfaz de línea de comandos (CLI) de Agent 365 requiere un registro de aplicación de cliente personalizado en su inquilino de Microsoft Entra ID para autenticar y gestionar los modelos de identidad del agente.

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

1. Registrar aplicación
2. Establecer el URI de redireccionamiento
3. Copiar identificador de aplicación (cliente)
4. Configurar permisos de APRequiere privilegios de administrador
5. Agregar la reclamación de rol wids

Si tiene problemas, consulte la sección de Solución de problemas.

Requisitos previos

Antes de comenzar, asegúrese de tener acceso al Centro de administración Microsoft Entra y, si es necesario, uno de los roles administrativos requeridos para conceder el consentimiento.

Para registrar la aplicación

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

Para agregar permisos y conceder consentimiento

Necesita uno de estos roles administrativos para 4. Configurar permisos de la API.

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

1. Registrar aplicación

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

1. Vaya al Centro de administración Microsoft Entra

2. Seleccione Registros de aplicaciones

3. Seleccione Nuevo registro

4. Introduzca:

   • Nombre: Introduzca un nombre significativo para su 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 quiere usar el flujo a365 setup all --agent-name sin configuración, nombre la aplicación exactamente Agent 365 CLI. La CLI busca automáticamente la aplicación cliente por este nombre para mostrar bien conocido, así que no necesita copiar el ID del cliente en un archivo de configuración.

   • Tipos de cuenta admitidos: cuentas de este directorio organizativo solo (inquilino único)

   • URI de redireccionamiento: Seleccione Cliente público/nativo (móvil y escritorio) e introduzca http://localhost:8400/

5. Seleccione Registrar

La CLI requiere tres URI de redirección en total. La CLI agrega automáticamente las que faltan cuando ejecuta a365 setup requirements:

Consulte Qué configura automáticamente la CLI para obtener más información.

2. Configure la URI de redireccionamiento

1. Vaya a Resumen y copie el valor de ID de aplicación (cliente).
2. Vaya a Autenticación (versión preliminar) y seleccione Agregar 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 ID de aplicación (cliente) que copió.
4. Seleccione Configurar para agregar el valor.

3. Copiar Id. de aplicación (cliente)

En la página Información general, copie el Id. de aplicación (cliente) en formato GUID. Utilizará este valor cuando ejecute a365 setup all o cuando cree a365.config.json manualmente.

4. Configurar permisos de API

Elija el método adecuado:

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

Opción: 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 inquilino.

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

2. Seleccione Agregar permiso>Microsoft Graph>Permisos delegados.

   Importante

   Debe usar Permisos delegados (no Permisos de aplicación). La CLI se autentica de forma interactiva: usted inicia sesión y actúa en su nombre. Para obtener más información, consulte Tipo de permiso incorrecto.

3. Sume estos siete permisos uno a uno:

   Permiso	Finalidad
   AgentIdentityBlueprint.ReadWrite.All	Creación de blueprints, gestión de secretos de clientes, permisos heredados, credenciales de identidad federadas y eliminación (API beta)
   AgentIdentityBlueprintPrincipal.Create	Crear la entidad de servicio de Agent Blueprint (API beta)
   AgentIdentity.Read.All	Comprobación de idempotencia y búsqueda de entidades de servicio de identidad de agentes (API beta)
   AgentIdentity.DeleteRestore.All	Eliminación de entidades de servicio de identidad del agente durante la limpieza (API beta)
   AgentRegistration.ReadWrite.All	Lectura y escritura de todas las inscripciones de agentes
   Application.Read.All	Búsqueda de una entidad de servicio por id. de aplicación (alternativa más específica a Directory.Read.All)
   User.Read	Leer el perfil del usuario que ha iniciado sesión para conocer la asignación del propietario y el patrocinador del plano técnico

   Nota

   AgentRegistration.ReadWrite.All se requiere para la configuración del agente. El validador CLI comprueba explícitamente este permiso. Debe estar presente en el registro de la aplicación y contar con el consentimiento de administrador concedido.

   Para cada permiso:

   • En el cuadro de búsqueda, escribe el nombre del permiso (p. ej., AgentIdentityBlueprint.ReadWrite.All).
   • Marque la casilla de verificación junto al permiso.
   • Seleccione Agregar permisos.
   • Repita para los siete permisos.

4. Seleccione Conceder consentimiento de administrador para [Su inquilino].

   • ¿Por qué es esto obligatorio? Las blueprints de identidad de agente son recursos de alcance de inquilino que múltiples usuarios y aplicaciones pueden referenciar. Sin consentimiento en el nivel de inquilino, la CLI falla durante la autenticación.
   • ¿Qué ocurre si falla? Necesita el rol de Administrador de aplicaciones, Administrador de aplicaciones en la nube o Administrador global. Pida ayuda al administrador de su inquilino.

5. Verifique que todos los permisos muestren marcas de verificación verdes en la columna Estado.

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

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

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

1. Abra el Explorador de Graph.

2. Inicie sesión con su cuenta de administrador ("Administrador de aplicaciones" o "Administrador de aplicaciones en la nube").

3. Conceda el consentimiento de administrador usando Graph API. Para completar este paso, necesita:

   • Id. de entidad de servicio Necesita el valor de la variable SP_OBJECT_ID.
   • Id. de recurso en el grafo. Necesita el valor de la variable GRAPH_RESOURCE_ID.
   • Crear (o actualizar) permisos delegados usando el tipo de recurso oAuth2PermissionGrant con los valores de variables SP_OBJECT_ID y GRAPH_RESOURCE_ID.

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

Obtener el Id. de entidad de servicio

Una entidad de servicio es la identidad de su aplicación en su inquilino. Debe tenerlo antes de poder conceder permisos a través de la API.

1. En el Explorador de gráficos, seleccione el método GET y use esta URL. Sustituya <YOUR_CLIENT_APP_ID> por el Id. real de su 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 su SP_OBJECT_ID.

   • Si la consulta falla debido a un error de permisos, seleccione la pestaña Modificar permisos, conceda su consentimiento para los permisos requeridos y luego seleccione Ejecutar consulta nuevamente. El valor devuelto es su SP_OBJECT_ID.

   • Si la consulta devuelve resultados vacíos ("value": []), cree el principal de servicio siguiendo estos pasos:

     1. Establezca el método en POST y use esta URL:

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

        Cuerpo de la solicitud (reemplace YOUR_CLIENT_APP_ID por el Id. real de su aplicación cliente):

        {
           "appId": "YOUR_CLIENT_APP_ID"
        }
        

     2. Seleccione Ejecutar consulta. Debería obtener una respuesta 201 Created. El valor de id devuelto es su SP_OBJECT_ID.

Obtenga su Id. de recurso de Graph

1. En Graph Explorer, seleccione el método GET y use 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, copie el valor id. Este valor es su GRAPH_RESOURCE_ID.
   • Si la consulta falla debido a un error de permisos, seleccione la pestaña Modificar permisos, conceda su consentimiento para los permisos requeridos y luego seleccione Ejecutar consulta nuevamente. Copie el valor id. Este valor es su GRAPH_RESOURCE_ID.

Crear permisos delegados

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

1. En Graph Explorer, establezca el método en POST y utilice 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": "AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprintPrincipal.Create AgentIdentity.Read.All AgentIdentity.DeleteRestore.All AgentRegistration.ReadWrite.All Application.Read.All User.Read"
   }
   

2. Seleccione Ejecutar consulta.

   • Si recibe la respuesta 201 Created: ¡Éxito! El campo scope en la respuesta muestra los nombres de los siete permisos. Ya ha terminado.
   • Si la consulta falla debido a un error de permisos, seleccione la pestaña Modificar permisos, conceda su consentimiento para los permisos requeridos y luego seleccione Ejecutar consulta nuevamente.
   • Si recibe el error Request_MultipleObjectsWithSameKeyValue: Ya existe una concesión. Quizá alguien agregó permisos antes. Consulta los siguientes permisos delegados de actualización.

Actualizar permisos delegados

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

1. En Graph Explorer, seleccione el método GET y use 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. Este valor es YOUR_GRANT_ID.

3. En Graph Explorer, seleccione el método PATCH y use esta URL con YOUR_GRANT_ID.

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

   Cuerpo de la solicitud:

   {
      "scope": "AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprintPrincipal.Create AgentIdentity.Read.All AgentIdentity.DeleteRestore.All AgentRegistration.ReadWrite.All Application.Read.All User.Read"
   }
   

4. Seleccione Ejecutar consulta. Debería recibir una respuesta 200 OK con los siete permisos en el campo scope.

5. Agregar la notificación de rol wids

La CLI de Agent 365 lee sus asignaciones de roles en el directorio Entra directamente desde el token de acceso para determinar si tiene privilegios de administrador. Esto requiere agregar la notificación wids a los tokens de acceso emitidos para el registro de la aplicación.

Sin esta afirmación, la CLI no puede detectar su rol y vuelve a mostrar instrucciones PowerShell para cada paso que requiere privilegios de administrador, incluso cuando es administrador. Complete este paso para adoptar el comportamiento correcto.

1. En el registro de la aplicación, vaya a Configuración de tokens.

2. Seleccione Agregar notificación opcional.

3. Para Tipo de token, seleccione Acceso.

4. En la lista de declaraciones, marque la casilla junto a wids.

5. Seleccione Add.

   Si se le pide activar el permiso de Microsoft Graph profile para habilitar la reclamación, seleccione Sí, agregar.

Prácticas recomendadas de seguridad

Revise estas directrices para mantener su registro de la aplicación seguro y conforme a la normativa.

Sí:

• Utilice el registro para un solo inquilino.
• Conceda únicamente los permisos delegados necesarios.
• Audite los permisos regularmente.
• Elimine la aplicación cuando ya no la necesite.

No:

• Conceda permisos de aplicación. Utilice únicamente delegado.
• Comparta públicamente el Id. del cliente.
• No conceda otros permisos innecesarios.
• Use la app para otros fines.

Lo que la CLI configura automáticamente

Cuando ejecuta a365 setup requirements, la CLI valida el registro de su aplicación y podría necesitar hacer cambios. Antes de aplicar cualquier cambio, la CLI le muestra un resumen y le pide 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 (p. ej., en un entorno de CI), use la opción --yes:

a365 setup requirements --yes

La siguiente tabla describe cada cambio que la CLI puede hacer:

Si rechaza la solicitud, la CLI no modifica el registro de su aplicación. Si se requieren cambios para que la CLI funcione, puede configurarlos manualmente en el Centro de administración Microsoft Entra o volver a ejecutar la CLI con --yes.

Pasos siguientes

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

Solución de problemas

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

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

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

Solución: Utilice esta lista de comprobación para verificar que su registro de aplicación sea correcto:

# Run requirements validation to see validation messages
a365 setup requirements

Resultado esperado: CLI muestra Custom client app validation successful.

Si no obtiene el resultado esperado, verifique cada una de las siguientes comprobaciones:

Permisos delegados requeridos:

• AgentIdentityBlueprint.ReadWrite.All [Beta]
• AgentIdentityBlueprintPrincipal.Create [Beta]
• AgentIdentity.Read.All [Beta]
• AgentIdentity.DeleteRestore.All [Beta]
• AgentRegistration.ReadWrite.All
• Application.Read.All
• User.Read

Consentimiento de administrador concedido incorrectamente

Síntoma: La validación falla aunque se hayan agregado permisos.

Causa raíz: No se concedió el consentimiento de administrador, o se concedió de manera incorrecta.

Solución: En el registro de su aplicación en el Centro de administración Microsoft Entra, vaya a permisos de la API y seleccione Conceder consentimiento de administrador para [Tu Inquilino]. Verifique que todos los permisos muestren marcas de verificación verdes en la columna Estado.

La creación de planos falla con «No se ha concedido el consentimiento del administrador»

Síntoma: a365 setup all imprime "Se ha asegurado correctamente el consentimiento de la aplicación delegada", pero después se produce un error inmediatamente durante la creación del blueprint con:

Admin consent has not been granted for this application.
Share this URL with an Application Administrator or Global Administrator to grant consent:
  https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent?client_id=<client-app-id>

Causa principal: Su inquilino ya tiene un oauth2PermissionGrant registro para su aplicación cliente personalizada (de una ejecución parcial anterior de la configuración, o de una acción previa de "Conceder consentimiento de administrador" en el Centro de administración Microsoft Entra para otros alcances), pero ese registro no incluye el alcance requerido (AgentIdentityBlueprint.ReadWrite.All). La CLI detecta el alcance faltante y muestra una URL de consentimiento para que un administrador complete la concesión.

Solución:

Comparta la URL de consentimiento impresa en la salida de error con un Administrador de aplicaciones o un Administrador global. La URL podría parecerse a esta:

https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent?client_id=<client-app-id>

Después de que el administrador dé su consentimiento, vuelve a ejecutar a365 setup all --agent-name <name>.

Si tiene acceso de administrador, puede abrir la URL directamente en un navegador para conceder el consentimiento sin esperar.

Tipo de permiso incorrecto

Síntoma: La CLI falla con errores de autenticación o errores de permisos denegados.

Causa raíz: Ha agregado Permisos de aplicación en lugar de Permisos delegados.

Esta tabla describe los diferentes tipos de permisos.

¿Por qué permisos delegados?

• Inicia sesión de forma interactiva (autenticación del navegador)
• CLI realiza acciones en su nombre (los registros de auditoría muestran su identidad)
• Más seguro: limitado por sus permisos actuales
• 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. Elimine todos los permisos de la aplicación. Estos permisos aparecen como Aplicación en la columna Tipo.
3. Agregue los mismos permisos que los permisos delegados.
4. Conceder consentimiento del administrador de nuevo.

Los permisos beta desaparecen tras el consentimiento del administrador del Centro de administración Microsoft Entra

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

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

Por qué sucede:

1. Usa la Microsoft Graph API (Opción B) para agregar los siete permisos, incluyendo los permisos beta.
2. La llamada API con consentType: "AllPrincipals"ya otorga el consentimiento de administrador en el nivel de inquilino.
3. Si va al Centro de administración Microsoft Entra, solo verá un subconjunto de permisos, ya que los permisos de la versión beta no aparecen en el portal.
4. Selecciona Conceder consentimiento de administrador pensando que es necesario.
5. El Centro de administración de Microsoft Entra anula el consentimiento otorgado a través de la API y solo muestra los permisos visibles.
6. Sus permisos beta se han eliminado.

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 accidentalmente eliminas permisos beta, vuelva a ejecutar la opción B Paso 3 (conceder el consentimiento del administrador usando la API de Microsoft Graph) para restaurarlos. Si obtiene un error Request_MultipleObjectsWithSameKeyValue, siga los pasos para actualizar permisos delegados.
• Para verificar que los siete permisos están listados, marque el campo scope en la respuesta POST o PATCH.

Aplicación no encontrada durante la validación

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

Solución:

1. Verifique que ha copiado el Id. de aplicación (cliente) en formato GUID, no el Id. de objeto:

   • Vaya a Centro de administración Microsoft Entra>Registro de aplicación> Su aplicación >Información general
   • Copie el valor bajo Identificador de aplicación (cliente)
   • El formato debe ser: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

2. Verifique que la aplicación exista en su 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>"
   

Aprender a registrar una aplicación en Microsoft Entra ID.