Agente del conector de Microsoft Graph

El uso de conectores locales requiere la instalación del software del agente del conector de Microsoft Graph . Permite la transferencia de datos segura entre los datos locales y las API del conector. En este artículo se le guía por la instalación y configuración del agente.

Instalación

Descargue la versión más reciente del agente del conector de Microsoft Graph e instale el software mediante el asistente de configuración de instalación. Las notas de la versión del software del agente del conector están disponibles aquí

Comprobación de la directiva de ejecución

La directiva de ejecución debe establecerse para permitir la ejecución de scripts firmados remotos. Si alguna directiva de nivel de grupo o máquina restringe lo mismo, se produce un error en la instalación de GCA. Ejecute el siguiente comando para obtener la directiva de ejecución:

Get-ExecutionPolicy -List

Para más información y establecer la directiva de ejecución correcta, consulte Directiva de ejecución.

Configuración recomendada

Con la configuración recomendada de la máquina, la instancia del agente del conector puede controlar hasta tres conexiones. Las conexiones posteriores podrían degradar el rendimiento de todas las conexiones en el agente. Esta es la configuración recomendada:

• Windows 10, Windows Server 2016 R2 y versiones posteriores
• .NET Framework 4.7.2
• Entorno de ejecución de escritorio de .NET Core 8.0 (x64)
• 8 núcleos, 3 GHz
• 16 GB de RAM, 2 GB de espacio en disco
• Acceso de red al origen de datos e Internet a través de 443

Si los servidores proxy o firewalls de su organización bloquean la comunicación con dominios desconocidos, agregue las reglas siguientes a la lista "permitir":

M365 Enterprise	M365 GCC	M365 GCCH
1. *.servicebus.windows.net	1. *.servicebus.usgovcloudapi.net	1. *.servicebus.usgovcloudapi.net
2. *.events.data.microsoft.com	2. *.events.data.microsoft.com	2. *.events.data.microsoft.com
3. *.office.com	3. *.office.com	3. *.office.com, *.office365.us
4. https://login.microsoftonline.com	4. https://login.microsoftonline.com	4. https://login.microsoftonline.com, https://login.microsoftonline.us
5. https://gcs.office.com/	5. https://gcsgcc.office.com	5. https://gcs.office365.us/
6. https://graph.microsoft.com/	6. https://graph.microsoft.com	6. https://graph.microsoft.com/, https://graph.microsoft.us/

Nota:

No se admite la autenticación de proxy. Si el entorno tiene un proxy que requiere autenticación, se recomienda permitir que el agente del conector omita el proxy.

Actualización

El agente del conector de Graph se puede actualizar de dos maneras:

1. Descargar e instalar graph Connector Agent manualmente desde el vínculo proporcionado en la sección de instalación.

2. Al hacer clic en el botón "Actualizar" disponible en el panel de conexión, como se muestra en la imagen:

El botón de actualización no está disponible para los agentes que actualizan de la versión 1.x a la versión 2.x. Siga estos pasos si el agente está actualizando de la versión 1.x a la 2.x:

1. Descargue el instalador del vínculo proporcionado en la sección de instalación.

2. El instalador le pide que instale el entorno de ejecución de .NET 8 Desktop, si aún no está instalado.

3. Permitir la comunicación con el punto de conexión *.office.com.

4. Después de la instalación, se reinicia la aplicación de configuración de GCA. Si GCA no está registrado, inicie sesión y continúe con el registro.

5. Si GCA ya está registrado, la aplicación de configuración de GCA muestra el siguiente mensaje de éxito:

6. Si observa algún error, siga los pasos sugeridos de mitigación en el mensaje de error y cierre & vuelva a abrir la aplicación de configuración de GCA.

7. Si el mensaje de error indica: "No se puede determinar el estado del agente. Si el error persiste, póngase en contacto con el soporte técnico.", reinicie GcaHostService (pasos mencionados en la sección de solución de problemas) y vuelva a abrir la aplicación de configuración de GCA.

8. Puede ejecutar las comprobaciones en cualquier momento cerrando y abriendo la aplicación GCA Config o usando el botón "Comprobación de estado" situado junto al botón "Editar" en la pantalla de detalles del registro.

Creación y configuración de una aplicación para el agente

En primer lugar, inicie sesión y tenga en cuenta que el privilegio mínimo necesario en la cuenta es administrador de búsqueda. A continuación, el agente le pide que proporcione detalles de autenticación. Siga los pasos para crear una aplicación y generar los detalles de autenticación necesarios.

Crear una aplicación

1. Vaya a Azure Portal e inicie sesión con las credenciales de administrador del inquilino.

2. Vaya a Microsoft Entra ID ->Registros de aplicaciones en el panel de navegación y seleccione Nuevo registro.

3. Proporcione un nombre para la aplicación y seleccione Registrar.

4. Anote el identificador de la aplicación (cliente).

5. Abra permisos de API en el panel de navegación y seleccione Agregar un permiso.

6. Seleccione Microsoft Graph y, a continuación, Permisos de aplicación.

7. Busque los permisos siguientes y seleccione Agregar permisos.

   Permiso	¿Cuándo es necesario el permiso?
   ExternalItem.ReadWrite.OwnedBy o ExternalItem.ReadWrite.All	Siempre
   ExternalConnection.ReadWrite.OwnedBy	Siempre
   Directory.Read.All	Necesario para el recurso compartido de archivos, los conectores MS SQL y Oracle SQL

8. Seleccione Conceder consentimiento de administrador para [TenantName] y confirme seleccionando Sí.

9. Compruebe que los permisos están en el estado "concedido".

   

Configurar la autenticación

Puede proporcionar detalles de autenticación mediante un secreto de cliente o un certificado. Siga los pasos que prefiera.

Configuración del secreto de cliente para la autenticación

1. Vaya a Azure Portal e inicie sesión con las credenciales de administrador del inquilino.

2. Abra Registro de aplicaciones en el panel de navegación y vaya a la aplicación adecuada. En Administrar, seleccione Certificados y secretos.

3. Seleccione Nuevo secreto de cliente y seleccione un período de expiración para el secreto. Copie el secreto generado y guárdelo porque no se muestra de nuevo.

4. Use este secreto de cliente y el identificador de aplicación para configurar el agente. Se aceptan caracteres alfanuméricos. No se pueden usar espacios en blanco en el campo Nombre del agente.

Uso de un certificado para la autenticación

Hay tres pasos sencillos para usar la autenticación basada en certificados:

1. Creación u obtención de un certificado
2. Carga del certificado en Azure Portal
3. Asignación del certificado al agente

Paso 1: Obtener un certificado

Puede usar el script para generar un certificado autofirmado. Es posible que su organización no permita certificados autofirmados. En ese caso, use esta información para comprender los requisitos y adquirir un certificado de acuerdo con las directivas de su organización.

$dnsName = "<TenantDomain like agent.onmicrosoft.com>" # Your DNS name
$password = "<password>" # Certificate password
$folderPath = "D:\New folder\" # Where do you want the files to get saved to? The folder needs to exist.
$fileName = "agentcert" # What do you want to call the cert files? without the file extension
$yearsValid = 10 # Number of years until you need to renew the certificate
$certStoreLocation = "cert:\LocalMachine\My"
$expirationDate = (Get-Date).AddYears($yearsValid)
$certificate = New-SelfSignedCertificate -DnsName $dnsName -CertStoreLocation $certStoreLocation -NotAfter $expirationDate -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256
$certificatePath = $certStoreLocation + '\' + $certificate.Thumbprint
$filePath = $folderPath + '\' + $fileName
$securePassword = ConvertTo-SecureString -String $password -Force -AsPlainText
Export-Certificate -Cert $certificatePath -FilePath ($filePath + '.cer')
Export-PfxCertificate -Cert $certificatePath -FilePath ($filePath + '.pfx') -Password $securePassword

Paso 2: Carga del certificado en Azure Portal

1. Abra la aplicación y vaya a la sección certificados y secretos del panel izquierdo.

2. Seleccione Cargar certificado y cargue el archivo .cer.

3. Abra Registro de aplicaciones y seleccione Certificados y secretos en el panel de navegación. Copie la huella digital del certificado.

Paso 3: Asignar el certificado al agente

El uso del script de ejemplo para generar un certificado guardaría el archivo PFX en la ubicación identificada en el script.

1. Descargue el archivo pfx del certificado en la máquina del agente.

2. Haga doble clic en el archivo pfx para iniciar el cuadro de diálogo de instalación del certificado.

3. Seleccione Máquina local para la ubicación del almacén al instalar el certificado.

4. Después de instalar el certificado, abra Administrar certificados de equipo mediante el menú Inicio .

5. Seleccione el certificado recién instalado enCertificadospersonales>.

6. Seleccione y mantenga presionado (o haga clic con el botón derecho) en el certificado y seleccione Todas las tareas>Administrar claves privadas Opción.

7. En el cuadro de diálogo permisos, seleccione agregar opción. Aparece una nueva ventana. Seleccione la opción "Ubicaciones" en ella. Seleccione la máquina en la que se instala el agente entre las ubicaciones mostradas y seleccione Aceptar.

8. En el cuadro de diálogo de selección de usuario, escriba: NT Service\GcaHostService y seleccione Aceptar. No seleccione el botón Comprobar nombres .

9. Seleccione Aceptar en el cuadro de diálogo de permisos. La máquina del agente ahora está configurada para que el agente genere tokens mediante el certificado.

Solución de problemas

Error de instalación

Si se produce un error de instalación, compruebe los registros de instalación ejecutando: msiexec /i "< path to msi >\GcaInstaller.msi" /L*V "< destination path >\install.log". Asegúrese de que no recibe ninguna excepción de seguridad. Por lo general, estas excepciones surgen debido a una configuración de directiva incorrecta. La directiva de ejecución debe estar firmada de forma remota. Para más información, consulte la sección "Instalación" de este documento.

Si los errores no se pueden resolver, envíe un correo electrónico para admitirlo mediante MicrosoftGraphConnectorsFeedback@service.microsoft.com los registros.

Error de registro

Si se produce un error al iniciar sesión para configurar la aplicación y se muestra el error "Error de inicio de sesión, seleccione el botón de inicio de sesión para volver a intentarlo", incluso después de que la autenticación del explorador se realice correctamente, abra services.msc y compruebe si GcaHostService se está ejecutando. Si no se inicia, inícielo manualmente. En el Administrador de tareas, vaya a la pestaña Servicios y compruebe si GcaHostService está en estado en ejecución. Si no es así, haga clic con el botón derecho e inicie el servicio.

Cuando el servicio no se inicie con el error "El servicio no se inició debido a un error de inicio de sesión", compruebe si la cuenta virtual: "NT Service\GcaHostService" tiene permiso para iniciar sesión como servicio en la máquina. Consulte este vínculo para obtener instrucciones. Si la opción para agregar un usuario o grupo está atenuada en Directivas locales\Asignación de derechos de usuario, significa que el usuario que intenta agregar esta cuenta no tiene privilegios de administrador en esta máquina o que hay una directiva de grupo que la reemplaza. La directiva de grupo debe actualizarse para permitir que el servicio host inicie sesión como servicio.

Error posterior al registro

Después del registro, algunas configuraciones locales pueden afectar a la conectividad del agente.

El agente está sin conexión

El agente se considera sin conexión si no puede ponerse en contacto con los servicios del conector de grafos. En tales casos, siga estos pasos:

1. Compruebe si el agente está en ejecución: inicie sesión en la máquina donde está instalado el agente y compruebe si se está ejecutando. En el Administrador de tareas, vaya a la pestaña Servicios y compruebe si GcaHostService está en estado en ejecución. Si no es así, haga clic con el botón derecho e inicie el servicio.

   

2. Compruebe si se puede acceder a gcs.office.com de dominio. (Para un inquilino de GCC, sustituya gcsgcc.office.com y, por un inquilino de GCCHigh, sustituya gcs.office365.us, como se muestra en la tabla inicial). Siga estos pasos:

   • Desde PowerShell, ejecute el siguiente comando:

   tnc gcs.office.com -Port 443
   

   La respuesta debe contener la salida "TcpTestSucceeded: True" como se muestra:

   

   Si es false, compruebe que el dominio está permitido en el proxy o firewall y que las solicitudes pasan por el proxy.

   • Para una prueba más específica o si no puede ejecutar tnc porque el ping ICMP está bloqueado en la red, ejecute el siguiente comando:

   wget https://gcs.office.com/v1.0/admin/AdminDataSetCrawl/healthcheck
   

   La salida debe contener "StatusCode: 200".

   

   Si no es 200, compruebe que el dominio está permitido en el proxy o firewall y que las solicitudes pasan por el proxy.

3. Si los pasos se han superado correctamente y el agente sigue sin conexión, compruebe los registros de GCA para ver si hay problemas de proxy de red.

   • Los registros de GcaHostService se pueden encontrar en la ubicación especificada (es posible que tenga que navegar manualmente a esta ruta de acceso: es posible que copiar pegar en el Explorador de archivos no funcione):
     1. Para el sistema operativo Windows Server 2016: C:\Users\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
     2. Para todas las demás versiones compatibles del sistema operativo Windows: C:\Windows\ServiceProfiles\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
   • Ordene los archivos de registro en la carpeta en orden inverso de "Tiempo de modificación" y abra los dos archivos más recientes.
   • Compruebe si hay mensajes de error con el siguiente texto: "No se pudo realizar ninguna conexión porque la máquina de destino la rechazó activamente".
     1. Esto indica que hay un problema con la configuración de red que impide que la cuenta virtual GcaHostService se ponga en contacto con el https://gcs.office.com punto de conexión.
     2. Consulte con el equipo de red o proxy para permitir que la cuenta virtual (NT Service\GcaHostService) envíe tráfico a este dominio.
     3. Puede comprobar que el problema se resuelve si el archivo de registro ya no contiene estos errores.

4. Si ninguno de los pasos soluciona el problema, póngase en contacto con el soporte técnico enviando un correo electrónico a MicrosoftGraphConnectorsFeedback@service.microsoft.comy proporcione los dos archivos de registro más recientes desde la ubicación mencionada anteriormente.

No se puede acceder al agente

Al configurar la conexión si el agente no es accesible, verá esta pantalla:

Con el espacio de nombres de Service Bus proporcionado en los detalles del error, siga estos pasos para solucionar problemas:

1. Desde PowerShell, ejecute el siguiente comando:

   tnc <yournamespacename>.servicebus.windows.net -port 443
   

   La respuesta debe contener la salida "TcpTestSucceeded: True":

   

   Si es false, compruebe que el dominio está permitido en el proxy o firewall y que las solicitudes pasan por el proxy.

2. Si no puede ejecutar tnc porque el ping ICMP está bloqueado en la red, ejecute el siguiente comando en PowerShell:

   wget https://<yournamespacename>.servicebus.windows.net/
   

   La salida debe contener "StatusCode: 200":

   

   Si es false, compruebe que el dominio está permitido en el proxy o firewall y que las solicitudes pasan por el proxy.

3. Si ninguno de los pasos soluciona el problema, póngase en contacto con el soporte técnico enviando un correo electrónico a MicrosoftGraphConnectorsFeedback@service.microsoft.comy proporcione los dos archivos de registro más recientes desde la ubicación mencionada anteriormente.

Actualización en curso

Este error aparece cuando ya hay una actualización en curso y el error debe desaparecer después de un máximo de 30 minutos.

Si el error persiste después de 30 minutos, siga estos pasos:

1. Compruebe si el agente está en ejecución: inicie sesión en la máquina donde está instalado el agente y compruebe si se está ejecutando. En el Administrador de tareas, vaya a la pestaña Servicios y compruebe si GcaHostService está en estado en ejecución. Si no es así, haga clic con el botón derecho e inicie el servicio.

2. Si el problema se sigue viendo, póngase en contacto con el soporte técnico enviando un correo electrónico a MicrosoftGraphConnectorsFeedback@service.microsoft.comy proporcione los dos archivos de registro más recientes. Recorrer manualmente la ubicación para acceder a los registros y compartir lo mismo con el equipo: C:\Windows\System32\config\systemprofile\AppData\Local\Microsoft\GraphConnectorAgent\AgentUpdateApp\logs

Error de conexión

Si se produce un error en la acción "Probar conexión" al crear una conexión y se muestra el error "Compruebe el nombre de usuario o la contraseña y la ruta de acceso del origen de datos", incluso cuando el nombre de usuario y la contraseña proporcionados sean correctos, asegúrese de que la cuenta de usuario tenga derechos de inicio de sesión interactivos en la máquina donde está instalado el agente del conector. Puede revisar la documentación sobre la administración de directivas de inicio de sesión para comprobar los derechos de inicio de sesión. Además, asegúrese de que el origen de datos y la máquina del agente están en la misma red.