Licensed to be used in conjunction with basebox, only.
// integration
Permissions
Applies to
Product: Cloud · Server · Audience: Developer / Integrator · Security reviewer
Ensuring that a user reaches through basebox only what they may reach in the source system – and how basebox's access-control gate enforces that. The answer is deliberately simple: basebox does not manage foreign permissions. It ensures that every request arrives at the source system as the right user, and the source system decides.
The principle
basebox is transparent. It never replicates or caches the connected system's access rights. On every request it passes on the user's own credentials, so their permission model always applies:
- A user with read-only access to project A gets only project A through basebox. The ticket system enforces that, not basebox.
- A user without access to a wiki area gets the same "not found" or "access denied" response as in the browser.
- basebox adds no permissions and removes none – with one exception: write tools are disabled by default.
The gate in basebox
Before the model even sees a tool, AISRV checks three things and forms the intersection:
| Check | Source | Effect |
|---|---|---|
| Organisation has enabled the connector | Administration setting | Otherwise the connector does not exist |
| App enables the tool | The app's tool settings | Otherwise it is not offered to the model; write tools must be enabled individually |
| User has activated the connector and – where necessary – stored credentials | User settings | Otherwise it is not offered to the model |
Only then does AISRV insert this user's credentials into the connection configuration and call your server. If the credentials are invalid or revoked, the target system refuses – and that is the desired behaviour.
What your connector has to do
Pass through, do not decide. The Authorization header goes to the target system unchanged. Every response of the target system – including a refusal – goes back as a result.
Never a shared admin token for user-specific data. The classic to avoid: fetch everything with a service account and then "filter for the user". That is not access control but an imitation of it – and it is always incomplete. A service account is acceptable only for content everyone may see.
No copy of permissions. Your server keeps no list of who may do what. It does not know and does not need to know.
No cache across users. A result that user A was allowed to see must not go to user B from a cache.
Make refusals visible. 401 and 403 of the target system become clear tool results ("No access to …"). No silent fallback, no second attempt with other credentials.
What basebox guarantees – summarised
| Property | Implementation |
|---|---|
| Per-user isolation | Credentials stored separately per user and loaded per request by user_id |
| No shared admin token | basebox holds no privileged token for all users |
| No credential caching | Fresh from the database per request; not in process memory across requests |
| Target system enforces permissions | No filter layer, no removed checks |
| Write access off by default | Per app; administrator enables individually |
| Confidentiality of credentials | Never in production logs; stored write-only; administrators do not see them |
| Immediate revocation | Revoked token or deactivated account → next call fails; no session, no cache |
The sequence diagram: MCP permission and authorization flow.
Limits you should know
- Knowledge bases are different. Documents in an app's knowledge base are visible to everyone allowed to use the app – there is no per-user permission check there. Sensitive content therefore belongs behind a connector with personal credentials, not in a knowledge base. See Managing knowledge bases.
- Web search + internal tools in the same app is the path security teams take most seriously: a manipulated web page could try to smuggle internal data out via a follow-up search. The architectural answer is separation per app – see Introduction to web search security.
- What the user sees, the model sees. A connector makes available to the model what the user may read anyway – no more, but no less. Group-wise tool visibility is announced for upcoming releases.
Checklist for the security review of a connector
- User-specific data only with personal credentials
- Header passed through unchanged; no token exchange
- No permission list, no cache across users
- 401/403 as result, no fallback
- Write tools separate, off by default
- Only one target system on the network (egress allowlist)
- No credentials in logs
- Service account – if present – read-only, only for generally accessible content, from Kubernetes secret