Skip to content

Permission-Aware Answers

Gaia can enforce file-level permissions when processing queries — ensuring users only see answers derived from documents they're authorized to access. This is critical for regulated industries and multi-tenant enterprise deployments.

How It Works

When permission-aware answers are enabled for a dataset, Gaia:

  1. Receives a query from a user
  2. Identifies relevant documents via semantic search
  3. Checks each document against the user's permissions in the original source system
  4. Excludes any documents the user lacks access to
  5. Generates an answer using only authorized documents

Transparent to Your App

Permission filtering happens inside Gaia. Your application doesn't need to implement document-level access control — Gaia handles it automatically. However, you must ensure user identity is properly propagated.

Answer Generation Policies

When creating a dataset, you choose one of two policies:

Policy Behavior
Role-based Answer only Responses based on the user's Helios role (RBAC). No file-level filtering.
Role-Based and Permission-Aware Answers RBAC + source-level file permissions are both enforced.

SaaS Configuration

Identity Provider: Microsoft Entra ID (Azure AD)

Supported Object Types: Microsoft 365 OneDrive, Microsoft 365 SharePoint Site

Prerequisites

  1. Set up Microsoft Entra ID
  2. Create an application in your Entra ID tenant with these permissions:
    • Directory.Read.All
    • User.Read
    • User.Read.All
    • User.ReadBasic.All
  3. Create a secret key (save the app ID and secret)
  4. Register Entra ID as an authorization directory in Gaia (Settings > Access Management > Authorization Directory)
  5. Link data sources to the authorization directory
  6. Select "Role-Based and Permission-Aware Answers" when creating the dataset

Self-Managed Configuration

Identity Provider: Microsoft Active Directory

Supported Object Types: Isilon NAS, NetApp ONTAP, Generic NAS, Views (must use SMB protocol)

Prerequisites

  1. Cohesity cluster version 7.3.1_p1+
  2. Helios Self-Managed version 1.3.0_p1+
  3. Register Active Directory in Gaia (Settings > Access Management)
  4. Link data sources to the Active Directory domain
  5. Select "Role-Based and Permission-Aware Answers" when creating the dataset

Group Nesting Limit

Gaia resolves file permissions up to a maximum group nesting depth of 3. If a user's access depends on deeper nesting (Group A → B → C → D), permissions beyond the third level are not evaluated.

Developer Considerations

Your App Doesn't Need to Filter

Since Gaia handles permission filtering server-side, your application code stays simple:

Python
# Same API call — Gaia filters results based on the authenticated user
response = await gaia.ask(
    dataset_names=["hr-documents"],
    query="What is the vacation policy?"
)
# The response only contains information from documents
# the current user is authorized to access

User Identity Propagation

For permission-aware answers to work, Gaia must know which user is making the query. In practice:

  • UI users (Gaia native): Identity is established at login
  • API users (your app): The API key determines the identity context. If your app serves multiple users, you may need to use the X-GAIA-SECURITY-CTX header to pass user-specific context
Python
async with GaiaClient(
    api_key="service-account-key",
    security_context="user-specific-context-token",
) as gaia:
    # Results are filtered for this specific user
    response = await gaia.ask(["hr-docs"], "What is my benefits package?")

Handling "No Results"

When all relevant documents are filtered out by permissions, Gaia may return responses like "I could not find enough information to answer the question." Your app should handle this gracefully — it might mean the user doesn't have access to the relevant data, not that the data doesn't exist.

Next Steps