diff --git a/docs.json b/docs.json index 84cb846..8e87329 100644 --- a/docs.json +++ b/docs.json @@ -85,6 +85,7 @@ { "group": "External Connectors", "pages": [ + "en/user-manual/connectors/google-drive", "en/user-manual/connectors/sharepoint", "en/user-manual/connectors/confluence", "en/user-manual/connectors/confluence-server", @@ -352,6 +353,7 @@ "group": "Knowledge Base Connectors", "pages": [ "en/operator-manual/knowledge-base/index", + "en/operator-manual/knowledge-base/google-drive", "en/operator-manual/knowledge-base/sharepoint", "en/operator-manual/knowledge-base/confluence", "en/operator-manual/knowledge-base/confluence-server", @@ -490,6 +492,7 @@ { "group": "Conectores Externos", "pages": [ + "es/user-manual/connectors/google-drive", "es/user-manual/connectors/sharepoint", "es/user-manual/connectors/confluence", "es/user-manual/connectors/confluence-server", @@ -750,6 +753,7 @@ "group": "Conectores de Bases de Conocimiento", "pages": [ "es/operator-manual/knowledge-base/index", + "es/operator-manual/knowledge-base/google-drive", "es/operator-manual/knowledge-base/sharepoint", "es/operator-manual/knowledge-base/confluence", "es/operator-manual/knowledge-base/confluence-server", diff --git a/en/operator-manual/knowledge-base/google-drive.mdx b/en/operator-manual/knowledge-base/google-drive.mdx new file mode 100644 index 0000000..dce1b6e --- /dev/null +++ b/en/operator-manual/knowledge-base/google-drive.mdx @@ -0,0 +1,134 @@ +--- +title: Google Drive +--- + +To integrate with Google Drive, create a Google Cloud OAuth application and configure Zylon with its credentials. This enables users to sign in with Google, select files or folders through the Google Picker, and import them into a knowledge base. + +## Before you begin + +- Use a Google account that can manage the Google Cloud project. It does not need access to the Drive content that users will import. +- Know the public URL of your Zylon instance, for example `https://zylon.company.com`. +- Keep the OAuth client secret in a secure secret store. Do not commit it to source control. The Picker API key is used by the browser, so restrict it to the required APIs and, where applicable, your Zylon origin. + +## Create or select a Google Cloud project + +1. Open the [Google Cloud console](https://console.cloud.google.com/). +2. Select an existing project or create a new project for the integration. +3. Record the **Project number** from the project dashboard. Zylon uses this as the Picker **App ID**. + +[Placeholder: Add a screenshot showing the Google Cloud project number.] + +## Enable the Google APIs + +1. In the Google Cloud console, go to **APIs & Services** → **Library**. +2. Search for and enable **Google Drive API**. +3. Search for and enable **Google Picker API**. + +![Google Cloud API Library search results](/images/operator-manual/knowledge-base/google-drive-images/api-list.png) + +## Create and restrict an API key + +The Google Picker requires an API key in addition to the OAuth client credentials. + +1. Go to **APIs & Services** → **Credentials**. +2. Select **Create credentials** → **API key**. +3. Copy the key; it is the value for Zylon's `apiKey` setting. +4. Open the new key and, under **API restrictions**, select **Restrict key**. +5. Select **Google Drive API** and **Google Picker API**, then save the key. + +If your Google Cloud policy requires application restrictions, restrict the key to the public origin of your Zylon Workspace, for example `https://zylon.company.com`. + +![API key restricted to Google Drive API and Google Picker API](/images/operator-manual/knowledge-base/google-drive-images/credentials-permissions.png) + +## Configure the OAuth consent screen and data access + +1. In the Google Cloud console, open **Google Auth platform**. Complete the required **Branding** and **Audience** settings for your organization. +2. Open **Data Access** and select **Add or remove scopes**. +3. Add the following scopes, then save the changes. + +| Scope | User-facing description | +| --- | --- | +| `https://www.googleapis.com/auth/drive.metadata.readonly` | View metadata for files in your Google Drive. | +| `https://www.googleapis.com/auth/drive.readonly` | View and download files from your Google Drive. | +| `https://www.googleapis.com/auth/userinfo.email` | See your primary Google Account email address. | +| `https://www.googleapis.com/auth/userinfo.profile` | See your personal info, including any personal info you have made publicly available. | +| `openid` | Associate you with your personal info on Google. | +| `https://www.googleapis.com/auth/drive.file` | See, edit, create, and delete only the specific Google Drive files you use with this app. | + +Zylon requests all of these scopes during sign-in. The Drive metadata scope is required by the connector implementation as well as the Drive read-only scope. + +![Google Auth platform Data Access scopes](/images/operator-manual/knowledge-base/google-drive-images/data-access.png) + +## Create an OAuth client + +1. In **Google Auth platform**, open **Clients**. +2. Select **Create client** and choose **Web application** as the application type. +3. Give the client a meaningful name, such as `Zylon Google Drive`. +4. Under **Authorized redirect URIs**, add the following URL, replacing the domain with your Zylon instance URL: + +```text +https://{your-zylon-domain}/api/app/integration/googledrive/callback +``` + +5. Create the client. +6. Copy the **Client ID** and **Client secret**. You will use them as `clientId` and `clientSecret` in the Zylon configuration. + + +The redirect URI in Google Cloud and Zylon must match exactly, including `https`, domain, path, and trailing slash behavior. + + +![Google OAuth client configuration](/images/operator-manual/knowledge-base/google-drive-images/client-config.png) + +## Configure Zylon + +Add the following values to your Zylon configuration. The same `apiKey` and `appId` values are made available to the Workspace frontend for the Google Picker. + +```yaml +integration: + googleDrive: + enabled: true + clientId: "{Google OAuth client ID}" + clientSecret: "{Google OAuth client secret}" + redirectUri: "https://{your-zylon-domain}/api/app/integration/googledrive/callback" + apiKey: "{Google API key}" + appId: "{Google Cloud project number}" +``` + +For Helm installations, set the equivalent values in your values file under `integration.googleDrive`: + +```yaml +integration: + googleDrive: + enabled: true + clientId: "{Google OAuth client ID}" + clientSecret: "{Google OAuth client secret}" + redirectUri: "https://{your-zylon-domain}/api/app/integration/googledrive/callback" + apiKey: "{Google API key}" + appId: "{Google Cloud project number}" +``` + +Apply the configuration using your normal Zylon deployment process. For installations managed with the Zylon CLI, run: + +```bash +sudo zylon-cli sync +``` + +You are ready to connect Google Drive from a project knowledge base. + +## Troubleshooting + +### The Google Drive option is unavailable or the picker closes immediately + +- Confirm that `integration.googleDrive.enabled` is `true`. +- Confirm that `apiKey` and `appId` are configured. The Picker requires both values. +- Confirm that the Google Drive API and Google Picker API are enabled in the same Google Cloud project. + +### Google sign-in reports a redirect URI error + +- Verify that the **Authorized redirect URI** is exactly the same as `redirectUri` in the Zylon configuration. +- Confirm that the domain is the public HTTPS domain used to access Zylon. + +### A user cannot see or import a Drive item + +- Confirm that the user signs in with the Google account that can access the item. +- Confirm that the consent screen includes all scopes listed in [Configure the OAuth consent screen and data access](#configure-the-oauth-consent-screen-and-data-access). diff --git a/en/operator-manual/knowledge-base/index.mdx b/en/operator-manual/knowledge-base/index.mdx index 0a94cb1..b11328b 100644 --- a/en/operator-manual/knowledge-base/index.mdx +++ b/en/operator-manual/knowledge-base/index.mdx @@ -3,6 +3,9 @@ title: "Knowledge Connectors" --- + + Configure Google Drive access so users can select and index files and folders from their Google accounts + Connect to Atlassian Confluence spaces to index wiki pages, documentation, and collaborative content @@ -15,4 +18,4 @@ title: "Knowledge Connectors" Set up file share integration to index network drives and shared file system content. E.g. Samba - \ No newline at end of file + diff --git a/en/user-manual/connectors/google-drive.mdx b/en/user-manual/connectors/google-drive.mdx new file mode 100644 index 0000000..3bf67b7 --- /dev/null +++ b/en/user-manual/connectors/google-drive.mdx @@ -0,0 +1,18 @@ +--- +title: Google Drive connector +description: Import Google Drive files and folders into a project knowledge base. +--- + +You can import **files or folders** from **My Drive** and **Shared with me** that your Google account can access. After importing, use **Update** from the three-dot menu to sync the source: + +- Detects content changes in files. +- Adds new files and removes deleted files. +- Reflects moves and renames so the project structure mirrors Google Drive. + +> Everyone with access to the project can access the Google Drive files and folders you connect, independently of the original Google Drive permissions. + +[Placeholder: Add a screenshot of the Google Drive sign-in and Picker flow.] + + +Ask your administrator to configure the connector, or follow the [Google Drive integration setup](/en/operator-manual/knowledge-base/google-drive). + diff --git a/es/operator-manual/knowledge-base/google-drive.mdx b/es/operator-manual/knowledge-base/google-drive.mdx new file mode 100644 index 0000000..e7fa0a4 --- /dev/null +++ b/es/operator-manual/knowledge-base/google-drive.mdx @@ -0,0 +1,123 @@ +--- +title: Google Drive +--- + +Para integrar Google Drive, crea una aplicación OAuth en Google Cloud y configura Zylon con sus credenciales. Esto permite que los usuarios inicien sesión con Google, seleccionen archivos o carpetas con Google Picker y los importen a una base de conocimiento. + +## Antes de empezar + +- Usa una cuenta de Google que pueda administrar el proyecto de Google Cloud. No necesita acceso al contenido de Drive que importarán los usuarios. +- Conoce la URL pública de tu instancia de Zylon, por ejemplo `https://zylon.company.com`. +- Guarda el secreto del cliente OAuth en un gestor de secretos seguro. No lo incluyas en el control de versiones. La clave de API de Picker se usa en el navegador, así que restríngela a las APIs requeridas y, cuando corresponda, al origen de Zylon. + +## Crear o seleccionar un proyecto de Google Cloud + +1. Abre la [consola de Google Cloud](https://console.cloud.google.com/). +2. Selecciona un proyecto existente o crea uno nuevo para la integración. +3. Anota el **número de proyecto** en el panel del proyecto. Zylon lo usa como **App ID** de Picker. + +[Placeholder: Añadir una captura que muestre el número de proyecto de Google Cloud.] + +## Habilitar las APIs de Google + +1. En la consola de Google Cloud, ve a **APIs y servicios** → **Biblioteca**. +2. Busca y habilita **Google Drive API**. +3. Busca y habilita **Google Picker API**. + +![Resultados de búsqueda de la biblioteca de APIs de Google Cloud](/images/operator-manual/knowledge-base/google-drive-images/api-list.png) + +## Crear y restringir una clave de API + +Google Picker requiere una clave de API además de las credenciales del cliente OAuth. + +1. Ve a **APIs y servicios** → **Credenciales**. +2. Selecciona **Crear credenciales** → **Clave de API**. +3. Copia la clave; será el valor de `apiKey` en Zylon. +4. Abre la nueva clave y, en **Restricciones de API**, selecciona **Restringir clave**. +5. Selecciona **Google Drive API** y **Google Picker API** y guarda la clave. + +Si la política de Google Cloud exige restricciones de aplicación, restringe la clave al origen público de Zylon Workspace, por ejemplo `https://zylon.company.com`. + +![Clave de API restringida a Google Drive API y Google Picker API](/images/operator-manual/knowledge-base/google-drive-images/credentials-permissions.png) + +## Configurar la pantalla de consentimiento OAuth y el acceso a datos + +1. En la consola de Google Cloud, abre **Google Auth platform**. Completa la configuración obligatoria de **Branding** y **Audience** de tu organización. +2. Abre **Data Access** y selecciona **Add or remove scopes**. +3. Añade los siguientes scopes y guarda los cambios. + +| Scope | Descripción para el usuario | +| --- | --- | +| `https://www.googleapis.com/auth/drive.metadata.readonly` | Ver metadatos de archivos en Google Drive. | +| `https://www.googleapis.com/auth/drive.readonly` | Ver y descargar archivos de Google Drive. | +| `https://www.googleapis.com/auth/userinfo.email` | Ver tu dirección de correo principal de Google Account. | +| `https://www.googleapis.com/auth/userinfo.profile` | Ver tu información personal, incluida la información que has hecho pública. | +| `openid` | Asociarte con tu información personal en Google. | +| `https://www.googleapis.com/auth/drive.file` | Ver, editar, crear y eliminar solo los archivos específicos de Google Drive que usas con esta aplicación. | + +Zylon solicita todos estos scopes al iniciar sesión. El scope de metadatos de Drive también es necesario para la implementación del conector. + +![Scopes de Data Access en Google Auth platform](/images/operator-manual/knowledge-base/google-drive-images/data-access.png) + +## Crear un cliente OAuth + +1. En **Google Auth platform**, abre **Clients**. +2. Selecciona **Create client** y elige **Web application** como tipo de aplicación. +3. Asigna un nombre significativo al cliente, por ejemplo `Zylon Google Drive`. +4. En **Authorized redirect URIs**, añade la siguiente URL; sustituye el dominio por la URL de tu instancia de Zylon: + +```text +https://{your-zylon-domain}/api/app/integration/googledrive/callback +``` + +5. Crea el cliente. +6. Copia el **Client ID** y el **Client secret**. Los usarás como `clientId` y `clientSecret` en la configuración de Zylon. + + +La URI de redirección de Google Cloud y Zylon debe coincidir exactamente, incluidos `https`, el dominio, la ruta y las barras finales. + + +![Configuración del cliente OAuth de Google](/images/operator-manual/knowledge-base/google-drive-images/client-config.png) + +## Configurar Zylon + +Añade los siguientes valores a la configuración de Zylon. Los valores `apiKey` y `appId` también se proporcionan al frontend de Workspace para Google Picker. + +```yaml +integration: + googleDrive: + enabled: true + clientId: "{Google OAuth client ID}" + clientSecret: "{Google OAuth client secret}" + redirectUri: "https://{your-zylon-domain}/api/app/integration/googledrive/callback" + apiKey: "{Google API key}" + appId: "{Google Cloud project number}" +``` + +Para instalaciones con Helm, configura los valores equivalentes en tu archivo de valores bajo `integration.googleDrive`. + +Aplica la configuración mediante tu proceso habitual de despliegue de Zylon. En instalaciones gestionadas con Zylon CLI, ejecuta: + +```bash +sudo zylon-cli sync +``` + +Ya puedes conectar Google Drive desde una base de conocimiento de un proyecto. + +## Solución de problemas + +### La opción de Google Drive no está disponible o el selector se cierra inmediatamente + +- Confirma que `integration.googleDrive.enabled` es `true`. +- Confirma que `apiKey` y `appId` están configurados. Google Picker necesita ambos valores. +- Confirma que Google Drive API y Google Picker API están habilitadas en el mismo proyecto de Google Cloud. + +### Google muestra un error de URI de redirección + +- Comprueba que la **Authorized redirect URI** sea exactamente igual a `redirectUri` en la configuración de Zylon. +- Confirma que el dominio sea el dominio HTTPS público con el que se accede a Zylon. + +### Un usuario no puede ver o importar un elemento de Drive + +- Confirma que el usuario inicia sesión con la cuenta de Google que puede acceder al elemento. +- Confirma que la pantalla de consentimiento incluya todos los scopes de [Configurar la pantalla de consentimiento OAuth y el acceso a datos](#configurar-la-pantalla-de-consentimiento-oauth-y-el-acceso-a-datos). diff --git a/es/operator-manual/knowledge-base/index.mdx b/es/operator-manual/knowledge-base/index.mdx index 0567733..7ddf840 100644 --- a/es/operator-manual/knowledge-base/index.mdx +++ b/es/operator-manual/knowledge-base/index.mdx @@ -3,6 +3,9 @@ title: "Conectores de Conocimiento" --- + + Configura el acceso a Google Drive para que los usuarios puedan seleccionar e indexar archivos y carpetas de sus cuentas de Google + Conecta con espacios de Atlassian Confluence para indexar páginas wiki, documentación y contenido colaborativo diff --git a/es/user-manual/connectors/google-drive.mdx b/es/user-manual/connectors/google-drive.mdx new file mode 100644 index 0000000..7277a8c --- /dev/null +++ b/es/user-manual/connectors/google-drive.mdx @@ -0,0 +1,18 @@ +--- +title: Conector de Google Drive +description: Importa archivos y carpetas de Google Drive a una base de conocimiento de proyecto. +--- + +Puedes importar **archivos o carpetas** de **Mi unidad** y **Compartido conmigo** a los que tu cuenta de Google tenga acceso. Después de importar, usa **Actualizar** en el menú de tres puntos para sincronizar la fuente: + +- Detecta cambios de contenido en los archivos. +- Añade archivos nuevos y elimina los archivos eliminados. +- Refleja movimientos y cambios de nombre para que la estructura del proyecto refleje Google Drive. + +> Todas las personas con acceso al proyecto pueden acceder a los archivos y carpetas de Google Drive que conectes, independientemente de los permisos originales de Google Drive. + +[Placeholder: Añadir una captura del flujo de inicio de sesión y Google Picker.] + + +Pide a tu administrador que configure el conector o consulta la [configuración de la integración de Google Drive](/es/operator-manual/knowledge-base/google-drive). + diff --git a/images/operator-manual/knowledge-base/google-drive-images/api-list.png b/images/operator-manual/knowledge-base/google-drive-images/api-list.png new file mode 100644 index 0000000..142927b Binary files /dev/null and b/images/operator-manual/knowledge-base/google-drive-images/api-list.png differ diff --git a/images/operator-manual/knowledge-base/google-drive-images/client-config.png b/images/operator-manual/knowledge-base/google-drive-images/client-config.png new file mode 100644 index 0000000..073cb8b Binary files /dev/null and b/images/operator-manual/knowledge-base/google-drive-images/client-config.png differ diff --git a/images/operator-manual/knowledge-base/google-drive-images/credentials-permissions.png b/images/operator-manual/knowledge-base/google-drive-images/credentials-permissions.png new file mode 100644 index 0000000..94b4992 Binary files /dev/null and b/images/operator-manual/knowledge-base/google-drive-images/credentials-permissions.png differ diff --git a/images/operator-manual/knowledge-base/google-drive-images/data-access.png b/images/operator-manual/knowledge-base/google-drive-images/data-access.png new file mode 100644 index 0000000..4bb290d Binary files /dev/null and b/images/operator-manual/knowledge-base/google-drive-images/data-access.png differ