Sign-In and Permission-Aware Search¶

Flexible GraphRAG can answer only from the documents the person asking may read. You sign in to each repository whose documents are in the stores. Search, AI query and AI chat then check each candidate result against that repository, as you, when the question is asked. Results you may not open are left out.

This page covers how it works for users, which sources support it, the setup each one needs, and what to do when something goes wrong.

Which sources support it¶

Opt-in means: until the setting is present, that source's documents are not permission-checked and stay visible to everyone, as in earlier versions. Alfresco, Nuxeo and CMIS need no extra app, so they are always checked; see Settings to relax that.

The incremental registry is required for everything except Alfresco and Nuxeo (ENABLE_INCREMENTAL_UPDATES=true with POSTGRES_INCREMENTAL_URL). It records which source, server and repository item each document came from.

Using it (React, Vue, Angular)¶

The sign-in pill¶

The header has one pill for every repository sign-in.

• It reads Sign-ins 2/5 with several servers, or e.g. Nuxeo: Administrator with one.
• A dashed outline means a server whose documents are in the stores has no sign-in yet.
• Its menu lists each server:
• Signed in: a coloured dot, the account and Sign out.
• Offline: a grey dot and Sign in.
• Each row shows how many documents the stores hold from it (e.g. "SharePoint 2 docs · OneDrive 1 doc"). Hover a row for its server address.
• Sign out only forgets the sign-in in that browser tab. It does not end your session at Alfresco, Microsoft, Box or Google, so ACA and other tabs keep working.

Signing in¶

• Username / password sources (Alfresco, Nuxeo, CMIS) open a dialog. The password is sent once to the backend, which exchanges it for the repository's ticket or token. Only that ticket or token is kept, in the tab's session storage.
• Amazon S3 opens the same dialog with Access key ID and Secret access key. The key is sent once and exchanged for a temporary AWS session (12 hours by default); only that session is kept.
• Popup sources (Microsoft 365, Box, Google, Azure Storage) open the vendor's own login in a new window, so multi-factor authentication works. The window closes itself when you are signed in.

Allow pop-ups for the Flexible GraphRAG site. If the browser blocks the window, the dialog says so: allow pop-ups for the UI's address (the blocked-pop-up icon in the address bar), then click the sign-in button again.

• Before your first question, the UI asks for each server that still needs a sign-in. Continue without answers from the other sources instead (for that browser tab).
• Microsoft, Google and Azure Storage remember the account you used (only its name, never a token) and pass it as a hint next time, so they skip the account picker.
• Tokens expire: Microsoft, Box, Google and Azure Storage after about an hour; Alfresco tickets on the server's schedule. The pill then shows offline; sign in again.

Picking sources¶

Search (Hybrid Search and AI Query) and AI Chat have a Sources row: All sources, plus one chip per source in the stores.

• Pick several chips to answer only from those sources.
• A greyed chip needs a sign-in first: hover it to see which one, and click it to sign in.
• Picking only some sources also limits the sign-in prompts to those sources.

Results¶

Each result line names the file, the data source and the store, e.g. Source: cmispress.pdf | SharePoint | Qdrant vector | Score: 0.250.

The file name opens the document in its repository: ACA or Share for Alfresco, the Nuxeo Web UI, the SharePoint or OneDrive page, Box's viewer, Drive's viewer, or the GCS object. S3 and Azure Blob links, while you are signed in to them, open the file itself through a short-lived URL signed with your own sign-in (an hour); without a sign-in an S3 link opens the AWS console and Azure has none. Each of those applies your own permissions again.

Ingesting with your sign-in¶

The Alfresco, Nuxeo and CMIS data-source forms show Signed in to X as Y (used for this ingest) when you are signed in to that server. The ingest then uses your ticket or token, and no credentials are typed.

Use other credentials brings the fields back. Use it for a service account, e.g. for Auto Sync: an Alfresco ticket expires, while a Nuxeo token does not.

Setup by source¶

Alfresco¶

Nothing to register. The sign-in uses Alfresco's own ticket API (as ACA does) against the server the documents came from. ALFRESCO_URL is the default server.

• KG Spaces in ACA passes ACA's own ticket, so no sign-in is asked there for ACA's own server (since v0.9.0 the title bar shows it as Alfresco · \<user>). Every other source signs in from the sign-in pill at the right end of the KG Spaces title bar (with a signed-in count); questions then carry ACA's ticket plus those sign-ins. plugins.kgSpaces.searchSignIn: false in ACA's app.config.json sends only ACA's ticket.
• Several Alfresco servers each get their own row in the pill.

Nuxeo and CMIS¶

Nothing to register. Nuxeo issues a token for the user. A CMIS server on Alfresco or Nuxeo gets that vendor's ticket or token. Details: Nuxeo, CMIS, including how to add another CMIS vendor.

• KG Spaces for Nuxeo (v0.9.0+) passes the Web UI user's Nuxeo token, so no sign-in is asked there for that Nuxeo server; its title bar shows Nuxeo · \<user> (sign out in Web UI), and every other source signs in from the sign-in pill next to it. See Nuxeo — KG Spaces for Nuxeo.

Microsoft 365, Box, Google, Azure Storage: what they have in common¶

Each needs an OAuth app registered at the vendor, separate from, or in addition to, the credentials the data source ingests with:

Notes for all four:

• <backend> is the backend's address as the browser reaches it, e.g. http://localhost:8000. A deployed backend needs https://. Set <PROVIDER>_AUTH_REDIRECT_URI when a proxy changes the address.
• Use localhost, not 127.0.0.1, in redirect URIs: vendors treat them as different addresses.

Settings¶

Troubleshooting¶

REST and MCP¶

• GET /api/auth/requirements: which servers need a sign-in.
• GET /api/sources/available: the sources a question can be limited to.
• Search and query take:
• source_auth: one credential, or a list with one per server, under alfresco, nuxeo, cmis, microsoft, box, google, azure or s3;
• sources: the source picker's choice.
• Username / password sign-in: POST /api/auth/{alfresco|nuxeo|cmis}/login; S3: POST /api/auth/s3/login with the access key as username / password.
• Popup sign-in: GET /api/auth/{microsoft|box|google|azure}/popup → /callback → /result.
• MCP tools:
• sign_in (username / password sources and S3), get_auth_requirements and list_sources;
• Three levels, set on the MCP side (details in the MCP server README): 1 no credentials, no filtering (the backend must trust the MCP server: TRUSTED_CLIENT_KEY on the backend = FLEXIBLE_GRAPHRAG_TRUSTED_KEY on the MCP server); 2 credentials in source_auth filter those sources; 3 MCP_BROWSER_SIGN_IN=true adds the browser sign-in tools below.
• start_sign_in and finish_sign_in for the browser sign-ins (Microsoft 365, Box, Google, Azure Storage): start_sign_in gives a link, the user opens it in any browser and signs in at the vendor, and finish_sign_in (once they say they have; it returns at once, or waits with wait_seconds) collects the credential to pass as source_auth. The secret that collects it stays in the MCP server, never in the model's context; a link works once and lasts 10 minutes. REST: POST /api/auth/{provider}/handoff, then POST /api/auth/{provider}/handoff/result with the poll key.
• AUTH_HANDOFF_CONFIRM_CODE=true makes the link first show a code to compare with the client's before going on to the vendor. Use it on a shared backend: it stops a sign-in link sent by someone else from handing them your token.
• search_documents and query_documents take source_auth and sources.