Licensed to be used in conjunction with basebox, only.
// admin
Connector authentication
This page describes how basebox and your users authenticate to connected systems: personal sign-in per user (OAuth, token or user name and password) and shared service accounts. Which variant a connector uses determines who sees what – which is why this is the most important security question around connectors.
The assistant must identify itself to the target system
When the assistant accesses a wiki, a ticket system or a mailbox through a connector, it has to identify itself there. As an administrator you decide which model is used, and you need to be able to explain to users why they should store a token.
The three models
| Model | How it works | Who sees what | Typical connectors |
|---|---|---|---|
| Personal credentials | Each person signs in with their own account: via OAuth or with their own token or user name and password; basebox uses this sign-in for every request to the system | Exactly what the person may see in the system themselves | E-mail (IMAP), DokuWiki, YouTrack, Nextcloud, Atlassian, roXtra, Zammad, CentralStationCRM |
| Shared service account | The administrator stores one account used for all requests | All users see what the service account sees | Read-only access to generally accessible content, where the connector supports it, for example Zammad (shared token) or roXtra |
| No sign-in | No account needed | – | Calculator; web search (the query goes to the provider without user identity) |
basebox never uses a shared admin token to fetch data and then filter it per user. With personal credentials, the connected system enforces its own permissions – ACLs, roles, project memberships – exactly as with a direct sign-in by that person.
OAuth is a sign-in method, not a connector
If a system offers OAuth, the person signs in there with their own account and confirms an authorisation for basebox; basebox receives this authorisation, not a password. If the system does not offer OAuth, the person stores their own token or user name and password; basebox never displays them again.
Which sign-in a connector supports depends on the target system:
| Connector | Sign-in |
|---|---|
| Zammad | Per person with a token or user name and password, or one shared token |
| CentralStationCRM | Only per person with user name and password |
| roXtra (planned) | Per person with user name and password; shared access is also possible |
Network drives are not a connector: with the server, basebox connects them during setup with one account for the whole organisation, see Managing knowledge bases.
Credentials are entered in two places
- Administration → Connectors: per connector the base URL, where applicable a shared service account or an organisation-level API key (e.g. for web search), Test connection, switch.
- Users: in the chat, click the connector via the "+" icon next to the input bar and enter the personal token there. Alternatively under Settings → Connectors.
Introducing connectors
Introducing a connector with personal credentials
- Enable the connector under Administration → Connectors and enter the system's base URL (on basebox Server, the Platform Operator sets some external endpoints via Helm – see Configuring connectors).
- Click Test connection.
- Enable the connector in the app settings of the apps in which it should be usable.
- Tell your users how to generate a token – for YouTrack the guide is under Create a YouTrack token. Where the system offers tokens, emphasise: a dedicated token, not the login password. Some systems, for example CentralStationCRM, only support user name and password.
- Users enter their token or user name and password (with OAuth they confirm the authorisation in the target system) and click Test connection. Only then are the connector's tools available in their chat.
Using a shared service account (where supported)
Only for content that all users may see anyway – a public wiki, a general manual. Create a dedicated account with minimal, read-only rights; do not use a real person's account.
How credentials are stored
- Write-only. Stored credentials are never returned to the browser, are hidden in logs and are never filled in automatically. A badge merely shows that some are set. Even you as administrator can neither see nor use other users' credentials.
- Separate per user. Credentials are loaded fresh for every request based on the user identifier; they are not shared or cached between users or sessions.
- Immediately revocable. If the token is withdrawn in the connected system or the account is deactivated, basebox loses access with the next request.
The complete technical flow with sequence diagram: MCP permission and authorization flow.
Write tools are off by default
Enable write access deliberately
Tools that change things in the connected system (create, update, delete) are disabled by default per app. Enable them only where that is intended, and only for connectors with personal credentials – so that every change is attributable to the acting person.
Note
- Web search needs no user sign-in. Optionally you store an API key of your organisation with the search provider; if it is left empty, searches run on the shared basebox quota. A rejected key produces an error, not a silent fallback. Details: Web search.
- E-mail: IMAP host, port and connection type are set by the Platform Operator; mailbox credentials are entered by users themselves and do not belong in any configuration file.
- Credentials never appear in production logs; only at log level
DEBUGduring targeted diagnostic runs.
Frequently asked questions
Why can't I as administrator view a user's credentials? Because they are stored write-only. That protects the users – and you.
Can I store one token for all users so nobody has to enter anything? Only as a shared service account, and only where the connector provides for it and everyone may see the same content. For systems with individual permissions that is the wrong approach.
What happens when a user changes their token? They enter the new token; it is used from the next request on. They can revoke the old one in the source system.
Does the connected system see that the request comes from basebox? It sees a normal API request with the person's credentials – indistinguishable from a direct sign-in by that person.
Need help? Contact support