# Admin-managed Google Drive knowledge base setup
<a name="google-drive-kb-admin-managed"></a>

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
<a name="google-drive-kb-admin-managed-prerequisites"></a>

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
<a name="google-drive-kb-admin-managed-overview"></a>

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
<a name="google-drive-kb-google-config"></a>

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
<a name="google-drive-kb-create-project"></a>

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
<a name="google-drive-kb-enable-apis"></a>

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
<a name="google-drive-kb-create-service-account"></a>

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
<a name="google-drive-kb-generate-key"></a>

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
<a name="google-drive-kb-record-unique-id"></a>

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
<a name="google-drive-kb-domain-delegation"></a>

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
<a name="google-drive-kb-create-admin-user"></a>

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
<a name="google-drive-kb-google-config-troubleshooting"></a>

### Resolving organization policy restrictions
<a name="google-drive-kb-admin-troubleshooting-org-policy"></a>

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
<a name="google-drive-kb-admin-troubleshooting-org-admin-role"></a>

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
<a name="google-drive-kb-connection"></a>

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
<a name="google-drive-kb-connection-setup"></a>

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
<a name="google-drive-kb-connection-content"></a>

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
<a name="google-drive-kb-connection-advanced"></a>

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
<a name="google-drive-kb-admin-managed-manage"></a>

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
<a name="google-drive-kb-admin-troubleshooting"></a>
+ **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
<a name="google-drive-kb-acl"></a>

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
<a name="google-drive-kb-acl-how-it-works"></a>

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
<a name="google-drive-kb-acl-enable"></a>

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
<a name="google-drive-kb-admin-managed-limitations"></a>
+ 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).