Google file access setup

This page covers everything you need to supply values into the File Access Control — creating and finding Drive Labels, folder IDs, and shared-drive IDs, and granting the OAuth scopes the control's resolvers need. It doesn't repeat the control's mechanics; see that guide for the predicate, pooled OR-combine, and enforcement points.

Creating and managing Drive Labels

Drive Labels are managed in the Google Workspace Admin console, not in PolicyArc:

1. Go to Admin console → Apps → Google Workspace → Drive and Docs → Manage Labels (the Drive Labels manager).
2. Create a label — for a simple approve/deny scheme, a single-select field with one or more values (e.g. a field Classification with values approved-for-ai, confidential) is the common shape.
3. Publish the label. An unpublished label isn't assignable to files.
4. Grant whoever needs to apply the label (a human classifying their own files, or a service account) the right to do so — applying a label is a distinct Workspace permission from ordinary file write access, which is the point: an agent with file-write access can't silently relabel a file to escape the filter unless it has also been separately granted label-apply rights.

Getting the bare label ID

The file access control's label source required/blocked lists take the bare label ID — no labels/ prefix. The Drive Labels manager UI and the Drive Labels API both surface the ID as labels/<id>; strip the labels/ prefix before putting it in the operator config. For example, if the API returns labels/sKFCys64ExampleApprovedId, the value to use in required/blocked is sKFCys64ExampleApprovedId.

You can list your organization's labels via the API:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://drivelabels.googleapis.com/v2/labels?view=LABEL_VIEW_FULL"

Each entry's name field is labels/<id> — take everything after labels/.

Required OAuth scopes

The file access control's resolvers call the Google Drive/Drive Labels APIs directly (not through whichever file connector is installed), using the caller's own passthrough token. That token must carry:

Scope	Needed for
https://www.googleapis.com/auth/drive.labels.readonly	Resolving a file's label IDs
https://www.googleapis.com/auth/drive.metadata.readonly	Resolving a file's parent folder ID(s) and shared-drive ID for a location source

Missing either scope on a governed request fails closed (denied), not silently ungoverned — see Fail-closed rules.

Granting the scopes

• If Google Drive is one of your installed connectors, its idp_passthrough upstream scopes already include drive.readonly (a superset covering metadata) plus drive.labels.readonly — installing it merges these into the Google IdP's scope list automatically, and users re-consent on next login.
• If only Docs, Sheets, and/or Slides are installed (no Drive connector), each of those connectors' idp_passthrough upstream scopes already declares both drive.metadata.readonly and drive.labels.readonly for exactly this reason — installing any one of them is enough to grant the file access control what it needs, even though the connector itself never calls those APIs directly for its own tools.
• Users who authenticated before the connector was installed will see "stored IdP token missing required scopes" until they re-log in at Google — the same behavior as any other upstream-scope change.

Getting folder IDs and shared-drive IDs

A location source's required/blocked lists take Drive container IDs: folder IDs and shared-drive IDs, used interchangeably as opaque container IDs.

• Folder ID — open the folder in the Drive web UI; the ID is the last path segment of the URL: https://drive.google.com/drive/folders/<folderId>. Or list it via the API: GET https://www.googleapis.com/drive/v3/files?q='<parentId>'+in+parents, or fetch a known file's parents field.
• Shared-drive ID — open the shared drive in the Drive web UI; the ID is the last path segment of https://drive.google.com/drive/folders/<sharedDriveId> (shared drives use the same URL shape as folders), or list it via GET https://www.googleapis.com/drive/v3/drives.

Folders and shared drives are matched by ID, not by path — Drive has no path metadata. An operator UI is expected to resolve a picked/named folder or drive to its ID and persist the ID; you shouldn't need to type a path by hand.

Google Drive does not allow labels on folders

You cannot apply a Drive Label to a folder — Drive Labels attach to files only. So there is no "label a folder to govern its contents" path, and no label inheritance. Govern folders with a location source instead: put the folder's ID in the location source's required to return the folder itself and its direct contents, or in blocked to hide them. A location source matches an item by its own ID as well as its parents, which is what lets the approved folder itself appear (and a blocked folder itself disappear). Two consequences:

• Approving a folder covers the folder itself and the files sitting directly inside it — a file in a sub-folder is not covered by the parent folder's ID; add the sub-folder's ID too, or govern the whole tree with a shared drive.
• If you need a whole department or project tree to share one boundary, put the whole tree inside a dedicated shared drive and govern it with a location source matching the shared-drive ID (which every descendant file reports as its driveId, at any depth). Governing shared-drive content requires the Google connectors at the version that is shared-drive-aware (Drive connector ≥ 1.2.0); older installs return "File not found" for shared-drive IDs — reinstall the connector and update the resource's routes.

End-to-end worked example

Wiring the identos.google-docs connector so that get_document returns a document that carries an approved label or lives directly in an approved folder, and denies anything carrying a restricted label or living in an excluded folder.

1. Install the connector (identos.google-docs, idp_passthrough mode) — this merges drive.metadata.readonly and drive.labels.readonly into the Google IdP's scope list.
2. Create and publish a Drive Label in the Admin console: field Classification, single-select value approved-for-ai. Note the bare ID from the Drive Labels API, e.g. sKFCys64ExampleApprovedId.
3. Get the approved folder's ID — the folder holding documents you want agents to read regardless of their own labels. Drive won't let you label the folder, so you govern it by ID: open it in Drive and copy the ID from the URL, e.g. 1AbcApprovedFolderId.
4. Get the excluded folder's ID the same way, e.g. 1XyzHRFolderId.
5. Configure the file access control:

curl -X PUT "http://localhost:8080/admin/api/policy-data/by-key?dataKey=pbac.operator.controls.file_access" \
  -H "X-Admin-API-Key: $PBAC_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dataKey": "pbac.operator.controls.file_access",
    "payload": {
      "sources": {
        "drive-labels": {
          "type": "label",
          "required": ["sKFCys64ExampleApprovedId"],
          "blocked": []
        },
        "drive-location": {
          "type": "location",
          "required": ["1AbcApprovedFolderId"],
          "blocked": ["1XyzHRFolderId"]
        }
      },
      "governed": {
        "urn:connector:identos:google-docs": ["drive-labels", "drive-location"]
      }
    }
  }'

With this in place: a document sitting directly inside the Approved folder is readable via get_document even if the document itself carries no label (its parent folder ID is an approved container); a document carrying the approved label is readable wherever it lives; and either would be denied if it instead carried a restricted label or lived directly inside the HR folder, because a blocked match wins over any approval (deny-wins).

Related docs

• File Access Control — the control this page supplies IDs and scopes for: the pooled predicate, OR-combine and deny-wins, and the two enforcement points.
• Google Drive connector — the Drive connector itself. It declares no operator settings of its own; all of its governance comes from this control and the general controls under pbac.controls.*.
• Google Workspace: multi-connector setup — how one Google IdP backs Drive, Docs, Sheets, Slides, Gmail, and Calendar together.