# Google Drive knowledge base integration
With the Google Drive knowledge base integration, you can index your Google Drive content. Your Amazon Quick agents can then search this content and answer questions about it.
Amazon Quick supports two authentication methods for connecting to Google Drive:
+ **User-managed setup** – You sign in to Google Drive directly to authorize the connection. This is the simplest way to get started. For more information, see [User-managed setup](google-drive-kb-user-managed.md).
+ **Admin-managed setup (service credentials)** – A Google Workspace administrator creates a service account with domain-wide delegation to authorize the connection. A key benefit of admin-managed setup is built-in document-level access control (ACL). Amazon Quick automatically syncs access control lists from Google Drive. It verifies each user's permissions at query time, so users see answers only from documents that they are authorized to access. For more information, see [Admin-managed Google Drive knowledge base setup](google-drive-kb-admin-managed.md).
After you connect, Amazon Quick indexes your Google Drive files and folders into a knowledge base. Your Amazon Quick agents can then search this content and generate answers that are grounded in your Google Drive data.
## Prerequisites
Before you set up the Google Drive integration, make sure that you have the following:
+ A Google account with Google Drive access.
+ For subscription requirements, see [Set up integrations in the console](integration-console-setup-process.md).
For admin-managed setup, additional prerequisites apply. For more information, see [Admin-managed Google Drive knowledge base setup](google-drive-kb-admin-managed.md).
## Supported content types
The Google Drive connector supports all of the common file types that Amazon Quick knowledge bases support. These include PDF, Word, Excel, PowerPoint, and text files. The connector also supports the following Google Workspace-specific formats:
+ Google Docs
+ Google Sheets
+ Google Slides
For more information about supported file types, size limits, and content processing options, see [Common configuration settings](knowledge-base-integrations.md#common-configuration-settings).
# User-managed setup
With user-managed setup, you sign in to Google Drive directly to authorize the connection. Amazon Quick handles authentication through a managed OAuth flow. No Google Cloud project, service account, or domain-wide delegation is required.
## Prerequisites
Before you set up a user-managed Google Drive knowledge base, verify the following:
+ You have a Google account with access to Google Drive.
+ Your Google Workspace administrator allows third-party app access, or can allow the Amazon Quick app on your behalf.
+ Your browser allows popups from the Amazon Quick console domain.
**Note**
If your organization restricts third-party app access in Google Workspace, your Google Workspace administrator might need to allow the Amazon Quick app before users can sign in. Contact your Google Workspace administrator if you encounter an error during sign-in.
**Note**
User-managed setup does not support document-level access control (ACL). ACL is a mechanism that controls which users can access specific documents. If you need document-level access control, use [Admin-managed Google Drive knowledge base setup](google-drive-kb-admin-managed.md) instead.
## Permissions granted during consent
When you authorize the connection, Amazon Quick requests the following permissions from your Google account:
See and download all your Google Drive files
+ Allows Amazon Quick to see your Google Drive files
+ Allows Amazon Quick to download your files
+ Allows Amazon Quick to see the names and email addresses of people you share files with
See information about your Google Drive files
+ Allows Amazon Quick to see the titles and descriptions of your files
+ Allows Amazon Quick to see the names and email addresses of people you share files with
+ Allows Amazon Quick to see your folders and how files are organized
**Note**
You can review and remove this access at any time from your Google Account permissions settings.
## Set up a Google Drive knowledge base
To create a user-managed Google Drive knowledge base, complete the following steps in the Amazon Quick console.
1. In the Amazon Quick console, choose **Integrations**.
1. Find **Google Drive** and choose the **Add** (\$1) icon.
1. In the **Create Google Drive knowledge base** dialog, under **Authentication method**, choose **Sign in to Google Drive** and complete the Google sign-in and consent flow.
1. Under **Create knowledge base**, enter a name and an optional description for your knowledge base.
1. In the **Content** section, choose **Add content** and select the Google Drive files and folders that you want to index. You can browse content from your personal drive, files shared with you, and shared drives in your organization.
1. Choose **Create**.
After you choose **Create**, the data sync starts automatically.
## Access controls
**Important**
When Amazon Quick indexes Google Drive content through user-managed setup, it does not sync access control lists (ACLs) from Google Drive. All indexed content is accessible to any user who has access to the knowledge base in Amazon Quick, regardless of their permissions in Google Drive. Carefully review which content you include when you create a knowledge base.
If you require document-level access control, use the [Admin-managed Google Drive knowledge base setup](google-drive-kb-admin-managed.md) instead.
## Manage and troubleshoot your integration
For instructions on editing, sharing, or deleting your integration, see [Managing existing integrations](integration-workflows.md#managing-existing-integrations).
For more information about knowledge base troubleshooting, including sync issues and missing documents, see [Troubleshooting knowledge bases](troubleshooting-knowledge-bases.md).
### Google Drive-specific issues
+ **App blocked by administrator** – If your Google Workspace administrator restricts third-party app access, you might see an error when you attempt to sign in. Contact your Google Workspace administrator to allow the Amazon Quick app.
+ **Authentication popup fails** – Verify that your browser allows popups from the Amazon Quick console domain. Try using a different browser or clearing your browser cache.
+ **Permissions revoked** – If you previously revoked Amazon Quick access from your Google Account permissions settings, you need to re-authenticate by editing the integration and signing in again.
+ **Missing content** – Verify that the Google account that you used for authentication has access to the files and folders that you selected. Content that was shared with you after the initial sync requires a resync to be indexed.
+ **Google API rate limiting** – Google Drive might limit requests during high usage periods. If syncs fail or are incomplete, retry during off-peak hours.
## Known limitations
+ Document-level access control (ACL) is not supported with user-managed setup. If you require document-level access control, use [Admin-managed Google Drive knowledge base setup](google-drive-kb-admin-managed.md).
+ Synchronization of file comments is not supported.
# Admin-managed Google Drive knowledge base setup
With admin-managed setup, a Google Workspace administrator creates a service account and delegates domain-wide access. Individual users don't need to authorize through sign-in.
Admin-managed setup includes built-in document-level access control list (ACL) support. Amazon Quick automatically syncs ACLs from Google Drive and verifies each user's permissions at query time.
For more information about ACL best practices, see [Best practices for managing ACLs in knowledge bases](acl-best-practices-kb.md).
## Prerequisites
Make sure that you have the following before you set up the integration.
+ Administrator access to your organization's Google Workspace.
+ An Amazon Quick enterprise user account. Administrator access is not required.
+ A Google Workspace account with an email domain that matches the email domain that is used for your Amazon Quick identity.
+ For subscription requirements, see [Set up integrations in the console](integration-console-setup-process.md).
## Setup overview
The setup involves the following phases:
1. **Configure Google Workspace** – Create a Google Cloud service account with read-only API access and domain-wide delegation. Then create a dedicated admin user for the service account to impersonate. For more information, see [Configure Google Workspace](google-drive-kb-google-config.md).
1. **Create the knowledge base in Amazon Quick** – Create a Google Drive knowledge base by using the service account credentials from Phase 1. For more information, see [Creating a knowledge base in Amazon Quick](google-drive-kb-connection.md).
Document-level access control is automatically enabled for all admin-managed knowledge bases. For more information about how access controls work, see [Document-level access controls](google-drive-kb-acl.md).
# Configure Google Workspace
To connect Amazon Quick to Google Drive, complete the following tasks in the Google Cloud console and Google Workspace Admin Console. You create a Google Cloud project, turn on the required APIs, generate service account credentials, and configure domain-wide delegation. You also create a dedicated admin user for the service account to impersonate.
**Prerequisites**
Before you begin, make sure that you have the following:
A Google Workspace account with administrator access
Permission to create projects in the Google Cloud console
## Creating a Google Cloud project
1. Open the Google Cloud console.
1. From the project selector at the top of the page, choose **New Project**.
1. Enter a project name, then choose **Create**.
1. After the project is created, choose **Select Project** to switch to it. This might take a few moments.
## Turning on the required APIs
Amazon Quick requires three Google APIs. Turn on each one from the API Library.
1. In the navigation menu, choose **APIs & Services**, then choose **Library**.
1. Search for each of the following APIs and choose **Enable**:
+ Google Drive API
+ Google Drive Activity API
+ Admin SDK API
## Creating the service account
1. In the navigation menu, choose **APIs & Services**, then choose **Credentials**.
1. Choose **Create Credentials**, then choose **Service account**.
1. Enter a name and optional description for the service account, then choose **Done**.
## Generating a private key
1. On the **Credentials** page, choose the service account you created.
1. Choose the **Keys** tab, then choose **Add Key**, **Create new key**.
1. Confirm that **JSON** is selected, then choose **Create**.
The browser downloads a JSON file containing the private key. Store this file securely. You upload it to Amazon Quick in a later step.
**Note**
If you receive an error stating that service account key creation is disabled by an organization policy, see [Resolving organization policy restrictions](#google-drive-kb-admin-troubleshooting-org-policy).
## Recording the service account unique ID
1. On the service account detail page, choose the **Details** tab.
1. Copy the value in the **Unique ID** field. You need this value when you configure domain-wide delegation.
## Configuring domain-wide delegation
Domain-wide delegation allows the service account to access Google Workspace data on behalf of users in your organization.
1. On the service account detail page, expand **Advanced settings**.
1. Choose **View Google Workspace Admin Console**. The admin console opens in a new tab.
1. In the admin console navigation pane, choose **Security**, **Access and data control**, **API controls**.
1. Choose **Manage Domain Wide Delegation**, then choose **Add new**.
1. For **Client ID**, enter the unique ID you copied earlier.
1. For **OAuth scopes**, enter the following comma-separated values:
```
https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/drive.metadata.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/forms.body.readonly
```
1. Choose **Authorize**.
## Creating a delegated admin user
The service account acts on behalf of a Google Workspace admin user. Create a dedicated user for this purpose and assign the minimum required roles.
1. In the Google Workspace Admin Console, choose **Directory**, then choose **Users**.
1. Choose **Add new user**.
1. Enter a first name, last name, and primary email address for the new user, then choose **Add new user**.
1. Choose **Done**.
1. From the user list, choose the user you created. If the user does not appear, refresh the page.
1. On the user detail page, expand the **Admin roles and privileges** section.
1. Under **Roles**, assign the following roles:
+ Groups Reader
+ User Management Admin
+ Storage Admin
1. Choose **Save**.
Record the email address of this user. You need it when you create the knowledge base in Amazon Quick.
## Troubleshooting the Google Workspace configuration
### Resolving organization policy restrictions
If you receive the following error when creating a service account key:
```
The organization policy constraint iam.disableServiceAccountKeyCreation
is enforced on your organization.
```
**Note**
For Google Cloud organizations created on or after May 3, 2024, this constraint is enforced by default.
You must override the policy for your project.
1. Open the Google Cloud console and confirm that the correct project is selected.
1. In the navigation menu, choose **IAM & Admin**, then choose **Organization Policies**.
1. In the **Filter** field, enter `iam.disableServiceAccountKeyCreation`. Then, in the policy list, choose **Disable service account key creation**.
1. Choose **Manage policy**.
**Note**
If **Manage policy** is unavailable, you need the Organization Policy Administrator role (`roles/orgpolicy.policyAdmin`) at the organization level. See [Granting the Organization Policy Administrator role](#google-drive-kb-admin-troubleshooting-org-admin-role).
1. In the **Policy source** section, ensure that **Override parent's policy** is selected.
1. Under **Enforcement**, turn off enforcement for this organization policy constraint.
1. Choose **Set policy**.
The change can take several minutes to propagate.
### Granting the Organization Policy Administrator role
The Organization Policy Administrator role (`roles/orgpolicy.policyAdmin`) must be granted at the organization level, not the project level. It does not appear in the role list when assigning roles to a project.
To grant this role, select your organization (not a project) from the project selector in the Google Cloud console. Then, choose **IAM & Admin**, **IAM**, and assign the role to your account. For detailed instructions, see [Manage access to projects, folders, and organizations](https://cloud.google.com/iam/docs/granting-changing-revoking-access) in the Google Cloud documentation.
The role assignment can take several minutes to propagate.
# Creating a knowledge base in Amazon Quick
In this phase, you create a knowledge base in Amazon Quick and provide the service account credentials from the Google Workspace configuration. Any enterprise user can complete this phase. Amazon Quick administrator access is not required.
If a Google Workspace administrator completed the Google Workspace configuration on your behalf, you need the JSON key file and the delegated admin email address before you proceed.
## Setting up the knowledge base
1. In the Amazon Quick console, choose **Integrations**.
1. Under **Knowledge bases**, find **Google Drive**, and then choose the **Add** (\$1) icon.
1. In the **Create Google Drive knowledge base** dialog, choose **Have admin credentials? Configure document-level access control.**
1. In the **Connected account** dropdown, choose **Add account**.
1. For **Name**, enter a name for the connection. Use a descriptive name such as your Google Workspace domain.
**Important**
You cannot change the connection name after you save it.
1. Choose **Upload .JSON key**, and then choose the JSON file that you downloaded during the Google Workspace configuration.
1. For **Google workspace admin email**, enter the email address of the delegated admin user that you created during the Google Workspace configuration.
1. Choose **Next**.
## Choosing content to sync
1. Enter a **Name** and optional **Description** for your knowledge base.
1. Choose which Google Drive content to include:
+ **My Drive (all users)** – Includes files from all users' My Drive in your organization.
+ **Shared with me (all users)** – Includes files that are shared with your users.
+ **Shared drives** – All shared drives sync by default. To include or exclude specific drives, use the **Filter type** dropdown and **Add shared drive IDs** field. You can enter 1 to 100 shared drive IDs.
1. Choose **Next** to configure advanced settings.
## Configuring advanced settings
In the **Advanced settings** step, you can configure optional settings for the knowledge base.
Filter content by date
Limit which documents are crawled based on their last modified date. The start date defaults to one year before today. You can change or clear the start date, and optionally set an end date.
Multi-media content, file size, and file patterns
Choose which content types to include in the knowledge base.
+ **Visual content in documents** – Extracts and indexes visual elements from supported document formats. This option is enabled by default.
+ **Audio files** – Transcribes and indexes audio files.
+ **Video files** – Transcribes and indexes video files.
Choose **Create** to create the knowledge base. After you choose **Create**, the data sync starts automatically.
## Managing and troubleshooting
To edit, share, or delete your integration, see [Managing existing integrations](integration-workflows.md#managing-existing-integrations).
For information about knowledge base troubleshooting, including sync issues and missing documents, see [Troubleshooting knowledge bases](troubleshooting-knowledge-bases.md).
### Admin-managed setup issues
+ **Google API rate limiting** – Google Drive might throttle requests during high usage periods. If syncs fail or are incomplete, retry during off-peak hours.
+ **SSL certificate errors** – If you receive an error about SSL certificate errors when you create your knowledge base, verify the OAuth scopes that you configured during domain-wide delegation.
# Document-level access controls
Admin-managed Google Drive knowledge bases include built-in document-level access control. Amazon Quick syncs access control lists (ACLs) from Google Drive during each crawl and verifies each user's permissions at query time, so users only see answers from documents that they are authorized to access.
## How it works
When a user submits a query to an Amazon Quick agent that uses an admin-managed Google Drive knowledge base, the system enforces access controls in two stages:
1. **Pre-retrieval filtering** – Amazon Quick performs a semantic search against the vector index to find the most relevant document passages. The system applies access control lists that are already stored in the index. This produces a preliminary set of candidate documents. This stage is necessary because real-time API calls for every document in the index would be too costly at scale.
1. **Real-time verification** – The system verifies the candidate documents in real time by calling the Google Drive APIs. It uses the service account credential that the administrator provided to generate user-specific access tokens through impersonation. Google Drive maintains the source of truth for access control lists that are associated with each document. The system removes any documents that the user is not authorized to access from the result set.
The system passes only the verified and authorized document passages to the model as context. The model uses this knowledge to generate a response. This two-stage approach provides document-level access control guarantees and maintains performance at scale.
## Enable ACL management
Document-level access control is automatically enabled for all admin-managed knowledge bases. No additional configuration is required.
For more information about ACL best practices, see [Best practices for managing ACLs in knowledge bases](acl-best-practices-kb.md).
## Known limitations
+ File comments synchronization is not supported.
For more information about general ACL limitations and best practices, see [Best practices for managing ACLs in knowledge bases](acl-best-practices-kb.md).