How to integrate enterprise knowledge permissions and identity - PolarDB

When an enterprise knowledge base must grant access to employees and AI agents across departments and roles, retrieval results must be filtered by caller identity and unauthorized content must never enter the large model context. Enterprise knowledge space supports permission-aware capabilities: through PolarDB Agentic Server integrated with your enterprise identity directory, AI agents perform retrieval under the current caller identity, and documents the caller is not authorized to access are excluded from recall. This topic describes the end-to-end path from creating a permission-aware knowledge space to employees completing permission-aware access.

Business scenarios

After an enterprise consolidates documents scattered across Lark, SharePoint, and on-premises file systems into a knowledge space, it faces tiered authorization requirements: sensitive content such as finance, HR, and R&D must be retrievable only by authorized personnel, while public policies and organization-wide knowledge must be shared within the domain. Permission-aware capabilities establish access control at three levels: knowledge space, knowledge base, and document. The knowledge space determines the ACL mode at creation, the knowledge base defines the admission scope as public or private, and document-level ACL is enforced during retrieval recall. After completing this tutorial:

Administrators create a permission-aware knowledge space and knowledge base, ingest enterprise documents with source-side ACL, and deploy PolarDB Agentic Server to integrate with the enterprise identity directory.
Employees issue personal tokens under their enterprise identity and use MCP-compatible AI agent clients such as Qoder and Claude Code to perform permission-aware retrieval. Retrieval results include source file and page number for knowledge tracing, and all operations are auditable.

Solution architecture

The permission-aware pipeline consists of two operational planes:

PolarDB console: responsible for creating and managing knowledge spaces and knowledge bases. After you enable Document ACL when creating a knowledge space, the space becomes an ACL-enforced space, and all retrieval requests undergo document-level permission checks. Documents carry source-side ACL when ingested, or the system derives permissions based on the knowledge base type.
PolarDB Agentic Server administration panel: PolarDB Agentic Server (PolarRAG MCP Server) is a trusted access gateway between enterprise identities and AI agents. It handles enterprise identity source integration, agent binding, personal token issuance, and completes SSO/OIDC identity authentication, organizational relationship resolution, and permission context construction. The retrieval request call chain is as follows:
- An employee authenticates through their enterprise identity and obtains a token bound to their personal identity.
- The AI agent uses the token to call the MCP retrieval tool.
- PolarDB Agentic Server resolves the user identity and their user groups and departments, constructs a trusted permission context on the server side, and calls the PolarDB retrieval service. Clients cannot specify permission principals or override identity information.
- PolarDB performs knowledge base admission and document-level ACL filtering during the recall phase, and returns only content the current identity is authorized to access.
AI agents hold no independent data access permissions and always perform retrieval under the current caller identity. The knowledge space service and vector storage are deployed in the VPC bound by the customer. Original documents remain in the customer's OSS bucket, and index building and retrieval all take place within the customer's data domain.

Preparations

This tutorial is completed collaboratively by administrators and employees: Steps 1 and 2 are performed by an administrator in the PolarDB console, Steps 3 through 5 are performed by an administrator in the PolarDB Agentic Server administration panel, and Steps 6 and 7 are performed by employees. Before you begin, make sure the following resources and information are ready:

Network and compute resources:
- When creating a knowledge space, you must select a VPC, availability zone, vSwitch, and security group.
- To deploy PolarDB Agentic Server in Step 3, you also need to purchase an ECS instance in the same VPC as the source PolarDB cluster search node.
OSS bucket and AK/SK:
- When creating a knowledge space, you must bind an OSS bucket and provide the bucket name and AK/SK.
- In Step 3, enabling the MCP Tool document upload capability also requires an OSS AK/SK.
Enterprise identity directory and authorization information: supported identity sources include the Lark directory, SharePoint (Entra ID), and self-managed user systems. You must provide the authorization information for the corresponding platform when creating a document synchronization link.
Employee enterprise identity accounts: employees must use an enterprise identity such as Lark, SharePoint, or a self-managed account to sign in to the administration panel and issue personal tokens.

Procedure

The end-to-end path consists of seven steps.

Step	Operator	Operational plane	Outcome
Step 1: Create a permission-aware knowledge space and knowledge base	Administrator	PolarDB console	Knowledge space, knowledge base, PolarDB search node address
Step 2: Ingest document data	Administrator	PolarDB console	Documents and permissions ingested, indexes ready
Step 3: Deploy PolarDB Agentic Server and register the search node	Administrator	ECS + administration panel	MCP endpoint available for agent connections
Step 4: Connect an enterprise identity source	Administrator	Administration panel	Users and departments available for agent binding
Step 5: Create an agent and bind identity and knowledge space	Administrator	Administration panel	Agent bound to identity, instance, and permissions
Step 6: Employee sign-in and personal token issuance	Employee	Administration panel	Personal token and MCP client configuration
Step 7: Permission-aware access and verification	Employee	AI agent client	Permission-filtered, traceable, and auditable retrieval results

Step 1: Create a permission-aware knowledge space and knowledge base

This step creates the knowledge space and knowledge base that host permission-aware capabilities, and obtains the PolarDB cluster search node address required for registering the search node in the next steps.

Log on to the PolarDB console. In the left-side navigation pane, choose PolarDB AI > PolarDB Enterprise Knowledge Space.
Click Create Knowledge Space, and configure Knowledge Space Name, Database Type, Large Language Model, Sorting Model, Vector Model, Vector Dimensions, Sharding Strategy, OSS Bucket, OSS AccessKey, OSS Secret Key, and select VPC Network, Zone and vSwitch, and other settings.
Enable Document ACL, and then click Create.

Important
The ACL mode of the knowledge space is determined at creation and cannot be changed afterward. Fully evaluate your future permission management requirements before you create the space. If you are certain that document-level access control is not required, you can leave Document ACL turned off and create an open space (ACL Disabled) to remain compatible with existing data that does not carry permission metadata.
After creation, go to the knowledge space details page. In the Basic Information section, confirm that ACL Mode is set to ACL Enforced.

In the knowledge base section, click Create Knowledge Base, enter a knowledge base name, select a search mode, and configure Knowledge Base Type:

Knowledge base type	Access scope
Public	Open to authorized users within the domain. The uploader gains management permissions, and other users in the domain gain read-only access.
Private	Accessible only to the knowledge base owner. Used for personal materials, work notes, drafts, and other private content. Private knowledge bases can only be created under a permission-aware space.

In the Basic Information section, click the PolarDB Instance link to go to the Basic Information page of the PolarDB cluster, and record the search node address. You need this address in Step 3 to register the search node.

Step 2: Ingest document data

This step ingests enterprise documents into the knowledge base. Documents become retrievable after they are ingested and indexed.

Ingestion methods

Different ingestion paths have different ACL sources:

Ingestion path	ACL source
Console upload, OSS synchronization	The system automatically derives permissions based on the knowledge base type: public knowledge bases are open to authorized users within the domain, and private knowledge bases authorize only the owner. No manual ACL configuration is required.
Synchronization link (Lark, SharePoint)	The connector reads the source-side ACL, maps users, user groups, and departments into normalized permission principals, and synchronizes them to the retrieval index along with the documents. Source-side permission changes are propagated incrementally by synchronization tasks.
MCP Tool upload	The server generates the permission context based on the authenticated identity and knowledge base policy. Clients cannot specify permission principals.

Procedure

Console: on the knowledge base details page, under File Overview > Upload File, manually upload documents or use automatic OSS synchronization.
Connect enterprise content sources such as Lark and SharePoint: on the knowledge base details page, click the Synchronization Link tab, click Add Synchronization Link, select IM Platform, and provide the authorization information to create a synchronization link. The synchronization link form does not include ACL settings because source-side ACL is automatically synchronized with the documents and requires no additional configuration.

Note
For detailed instructions on each synchronization link, see Data synchronization.
MCP Tool upload: PolarDB Agentic Server is an open-source project. You must purchase an ECS instance in the same VPC as the PolarDB search node and complete the deployment. The data pipeline stays within the security domain.
1. Deploy the MCP server: refer to the open-source repository PolarDB Agentic Server for deployment instructions.
  
  Note
  The repository provides an agent-assisted deployment Skill (deploy-polardb-agentic-server) that can be invoked directly from AI agents such as Qoder, Claude Code, and Codex to complete a Docker Compose deployment. For details, see One-click deployment Skill documentation.
2. Register an instance and connect: after deployment, in the PolarDB Agentic Server administration panel, go to the Instances page and click Register Instance. Enter a name, select PolarRAG as the engine, and provide the PolarDB search node address and credentials obtained in Step 1. For details, see PolarRAG onboarding guide.
  
  Note
  Private knowledge bases must be assigned to an owner and activated on the Instances page before they can be used.
3. Configure upload capability: in the newly created instance, go to Spaces settings, enter the OSS AK/SK, and enable the MCP Tool document upload capability. After this is enabled, employees can upload documents to the knowledge base directly from AI agents.
After this step, the PolarDB Agentic Server instance is ready and the MCP endpoint is available for agent connections.

Step 4: (MCP Tool integration) Connect an enterprise identity source

In the PolarDB Agentic Server administration panel, go to the Users page and configure an enterprise identity source (Lark directory / SharePoint Entra ID / self-managed user system). The directory is automatically synchronized every 5 minutes. After the identity source synchronization completes, you can bind users and departments in one click when creating an agent. Lark and SharePoint directory changes are automatically synchronized within 5 minutes, so no manual maintenance of user lists is required. For detailed configuration, see Enterprise identity source configuration.

Step 5: (MCP Tool integration) Create an agent and bind identity and knowledge space

In the PolarDB Agentic Server administration panel, go to the Agent page and click Create Agent.
On the agent details page, click the PolarRAG tab, and then click Configure Enterprise Access. Select the enterprise identity source, users or user groups, and the target knowledge space to bind the agent to the enterprise identity and the knowledge space in one step.
Click Configure PUBLIC Scope to set, as needed, the public knowledge bases that different users can access.

After this step, the agent is bound to the identity, instance, and permissions. For detailed management instructions, see Agent and token management.

Step 6: (MCP Tool integration) Employee sign-in and personal token issuance

This step is performed by an employee under their personal identity to obtain access credentials for the AI agent client.

As an employee, sign in with your enterprise identity (Lark, SharePoint, or self-managed account) to the PolarDB Agentic Server administration panel.
Go to the My Instances page, find the target agent, and click Issue Token to obtain a personal token.
Copy the generated MCP JSON configuration and add it to your MCP-compatible AI agent client (Qoder, Qwen Code, Claude Code, or Codex).
(Optional) Click the Knowledge Base button to view the knowledge bases and document details that your current identity is authorized to access or manage.

The token is bound to your personal identity. Retrieval results are automatically filtered to the permission scope of that identity, and unauthorized content is never recalled.

Step 7: (MCP Tool integration) Permission-aware access and verification

Operate the enterprise knowledge base through natural language with AI agents: upload documents, check document status, and perform retrieval through questions. Retrieval is filtered by the caller identity. Answers include knowledge tracing information such as source file name, chunk, page number, and relevance score. The system records the caller identity, request time, and returned documents for each retrieval to meet audit requirements.
Verify whether permission isolation is effective: use two identities with different permission scopes to ask the same question against the same knowledge base, and compare the results. If each identity sees only the documents within its own permission scope, permission isolation is working correctly.

Permission changes are asynchronously synchronized to the retrieval pipeline in the background. During propagation, the system follows a deny-first strategy and temporarily excludes documents whose permission updates have not completed, preventing potentially unauthorized content from being returned. The retrieval service requires no downtime.

Learn more

What is an enterprise knowledge space: understand the access control model, permission storage, and retrieval mechanism of permission-aware capabilities.
Use enterprise knowledge spaces: day-to-day management operations for knowledge spaces and knowledge bases.
Sync Feishu documents to a knowledge base: complete steps for creating a Lark application, granting API permissions, and configuring synchronization links.
Synchronize SharePoint documents to a knowledge base: complete steps for registering a Microsoft Entra application, authorizing Microsoft Graph permissions, and configuring synchronization links.
PolarDB Agentic Server: the PolarDB Agentic Server open-source repository, including deployment, identity source, and agent management documentation.