Connectors

Self-Hosting Documentation Access

This section requires a password to access. Interested in self-hosting? Contact sales to learn more.

Password:

Access Documentation

Self-Hosting Documentation Access Granted Logout

Connectors sync files from Google Drive, SharePoint, S3, and Confluence into project folders. See Connectors for how they work. On a self-hosted deployment you provide three things:

1. Encryption keys. LlamaCloud encrypts every credential it stores. Without a key, it refuses to store a credential and creating the connection fails.
2. The connection types to offer. For example, S3 only, or S3 plus Google Drive and SharePoint sign-in.
3. OAuth client apps, only if you offer the sign-in (“Sign in with Google” or “Sign in with Microsoft”) connections. You register these apps with Google or Microsoft yourself, then give LlamaCloud their client IDs and secrets through the API.

Connections that use keys (S3 access keys, a Google service account key, a SharePoint app registration, a Confluence API token) need only steps 1 and 2.

Connector settings in values.yaml

Chart version 0.9.3 and later configures connectors under config.connectors. The chart passes these settings to every workload that stores or reads credentials: the API and the Temporal workers.

config:
  connectors:
    # Which connection types to offer (see below). This is the default.
    enabledAuthTypes: "google_drive:oauth,google_drive:service_account,sharepoint:oauth,sharepoint:service_account,s3:service_account"
    # Where Google or Microsoft sends users back after sign-in.
    # Defaults to https://<ingress.host>/credential-brokers/return.
    oauthReturnUrl: ""
    # Encrypt with AWS KMS...
    credentialsKmsKeyArn: ""
    tokenVaultKmsKeyArn: ""
    # ...or with master keys, and the sign-in seal key, from a Secret you create.
    secret: llamacloud-connector-secrets

Create the Secret before installing or upgrading. The chart never generates these keys:

kubectl create secret generic llamacloud-connector-secrets \
  --from-literal=CONNECTOR_AUTH_SEAL_KEY="$(openssl rand -base64 32)" \
  --from-literal=CONNECTOR_MASTER_KEY="$(openssl rand -base64 32)" \
  --from-literal=TOKEN_VAULT_MASTER_KEY="$(openssl rand -base64 32)"

Leave out CONNECTOR_MASTER_KEY or TOKEN_VAULT_MASTER_KEY when you set the matching KMS key ARN instead. The sections below explain each setting.

Connector encryption keys

LlamaCloud keeps two kinds of connector secrets, and each kind is encrypted with its own key:

Secret	Examples	KMS key	Or master key in the Secret
Credentials a connection holds itself	S3 access keys, Google service account keys, SharePoint client secrets, Confluence API tokens	credentialsKmsKeyArn	CONNECTOR_MASTER_KEY
OAuth client apps and the tokens from sign-in connections	Your Google and Entra client secrets, users’ refresh tokens	tokenVaultKmsKeyArn	TOKEN_VAULT_MASTER_KEY

For each kind, set one of the two:

• A KMS key: the key ARN or alias ARN, including the region, for example arn:aws:kms:us-east-1:123456789012:alias/llamacloud-connector-credentials. The API and Temporal worker pods’ IAM role needs kms:GenerateDataKey, kms:Decrypt, and kms:DescribeKey on it. If both a KMS key and a master key are set, the KMS key is used.
• A master key: a random key in the Secret, for deployments without AWS KMS. Generate it with openssl rand -base64 32.

Rules for the keys:

• Use a different key for each kind. Don’t reuse CONNECTOR_MASTER_KEY as TOKEN_VAULT_MASTER_KEY, or one KMS key for both.
• Never change or lose a key once connections exist. Stored credentials can only be opened with the key that encrypted them. If a key changes, every connection that used it has to be deleted and made again.

Without a key, creating a key-based connection returns 503 Credentials could not be stored securely, and registering an OAuth client app returns 500 Token vault encryption is not available.

CONNECTOR_AUTH_SEAL_KEY is a third, separate key that protects the short-lived state passed back and forth during a sign-in. It must be 32 random bytes, base64-encoded (openssl rand -base64 32). Sign-in connections can’t be created without it. Key-based connections don’t need it.

Choose which connection types to offer

config.connectors.enabledAuthTypes is a comma-separated list of integration:auth_type pairs. The API refuses any pair that isn’t listed with a 422. Set it to "" to turn connectors off.

Pair	Connection	In the default
s3:service_account	S3 with an access key pair	Yes
google_drive:service_account	Google Drive with a service account key file	Yes
google_drive:oauth	Google Drive, sign in with Google	Yes
sharepoint:service_account	SharePoint with an Entra app registration and client secret	Yes
sharepoint:oauth	SharePoint, sign in with Microsoft	Yes
confluence:api_key	Confluence with an API token or personal access token	No
confluence:oauth	Confluence Cloud, sign in with Atlassian	No

The cards in the Add connection dialog are fixed when the frontend image is built, and they match the default list. If you narrow the list, for example to s3:service_account only, the other cards still show but fail with a 422 when used. A connection type that isn’t in the default can’t be added from the dialog at all, though the API accepts it once you list it.

For an S3-only deployment, s3:service_account plus CONNECTOR_MASTER_KEY (or credentialsKmsKeyArn) is all you need. Skip the rest of this page.

Enable sign-in connections

Sign-in connections run through your deployment’s own token vault, using the OAuth client apps you register below. Beyond the token vault key and CONNECTOR_AUTH_SEAL_KEY, they need a redirect URI:

https://<your-llamacloud-host>/credential-brokers/return

<your-llamacloud-host> is your ingress.host, the hostname you open the UI on. The chart builds this URL from ingress.host for you. Set config.connectors.oauthReturnUrl only if users reach LlamaCloud at a different URL, for example behind your own ingress.

The URI must match, character for character, what you register with Google and Microsoft below: same scheme, same host, no trailing slash. LlamaCloud sends it when the sign-in starts and again when it exchanges the code, and the provider rejects any mismatch.

Create a Google OAuth client for Google Drive

Do this in a Google Cloud project your organization controls.

1. In the Google Cloud console, open APIs & Services → Library and enable the Google Drive API and the Google Picker API.
2. Open Google Auth Platform → Branding (the OAuth consent screen) and fill it in. Under Audience, pick:
   • Internal if only accounts in your Google Workspace will connect. This is the simplest choice, and Google doesn’t review Internal apps.
   • External if accounts from other domains must connect. drive.readonly is a restricted scope, so an External app needs Google’s verification before users outside your test users can use it.
3. Under Data Access, add these scopes:
   • openid
   • .../auth/userinfo.email
   • .../auth/userinfo.profile
   • https://www.googleapis.com/auth/drive.readonly
4. Under Clients, click Create client, choose Web application, and add one Authorized redirect URI: https://<your-llamacloud-host>/credential-brokers/return.
5. Copy the Client ID and Client secret.

LlamaCloud always asks for offline access, so each connection gets a refresh token and keeps syncing without the user signing in again.

Create a Microsoft Entra app for SharePoint sign-in

This app is for the SharePoint (sign in with Microsoft) connection. It isn’t the same as the app registration a SharePoint Keys connection uses, which needs application permissions instead; see SharePoint Connector.

1. In the Microsoft Entra admin center, go to App registrations → New registration.
2. Under Supported account types, choose Accounts in any organizational directory (multitenant). LlamaCloud signs users in through Microsoft’s organizations endpoint, and a single-tenant app is rejected there.
3. Under Redirect URI, choose the Web platform and enter https://<your-llamacloud-host>/credential-brokers/return.
4. Under API permissions → Add a permission → Microsoft Graph → Delegated permissions, add:
   • openid, profile, email, offline_access
   • User.Read
   • Sites.Read.All
5. So users can browse for a folder with Microsoft’s file picker, also add SharePoint → Delegated permissions → AllSites.Read. Without it the picker can’t open. Users can still create folders, but only by entering IDs.
6. Click Grant admin consent for your tenant. Sites.Read.All needs admin consent in most tenants, and this spares each user from asking for it.
7. Under Certificates & secrets, create a client secret. Copy its Value, not its Secret ID, and note its expiry date.
8. Copy the Application (client) ID from Overview.

These are all delegated permissions. The connection can read only what the signed-in user can open.

Register OAuth client apps with the API

Give LlamaCloud each app’s client ID and secret with POST /api/v2/internal/token-vault/apps. The secret is encrypted with the token vault key and never returned. Each app applies at one level:

tenant_type	tenant_id	Who can register it	Used for
global	omit	A global admin	Every project in the deployment
organization	The organization ID	An organization admin	Projects in that organization
project	The project ID	A project admin	That project only

On most deployments, one global app per provider is all you need. Call the API with the API key of an account that has the admin role for the level you register at:

LLAMACLOUD="https://llamacloud.example.com"

# Google Drive
curl -sS -X POST "$LLAMACLOUD/api/v2/internal/token-vault/apps" \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration": "google_drive",
    "tenant_type": "global",
    "client_id": "'"$GOOGLE_CLIENT_ID"'",
    "client_secret": "'"$GOOGLE_CLIENT_SECRET"'"
  }'

# SharePoint (set expires_at to the client secret's expiry)
curl -sS -X POST "$LLAMACLOUD/api/v2/internal/token-vault/apps" \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration": "sharepoint",
    "tenant_type": "global",
    "client_id": "'"$ENTRA_CLIENT_ID"'",
    "client_secret": "'"$ENTRA_CLIENT_SECRET"'",
    "expires_at": "2027-09-30T00:00:00Z"
  }'

The response echoes the client_id and the app’s id, never the secret. The OAuth scopes are fixed for each integration, so you don’t send them.

integration accepts google_drive, sharepoint, and confluence. For Confluence, register an Atlassian OAuth 2.0 (3LO) app the same way, with the same redirect URI as its callback URL.

Manage registered OAuth apps

Request	What it does
GET /api/v2/internal/token-vault/apps?tenant_type=global	List apps at a level (add &tenant_id=… for organization or project). Filter with integration, is_enabled, or is_expired.
PATCH /api/v2/internal/token-vault/apps/{app_id} with {"enabled": false}	Stop offering the app for new connections. Existing connections keep working.
DELETE /api/v2/internal/token-vault/apps/{app_id}	Delete the app. Returns 409 while any connection still uses it.

Apps can’t be edited. To rotate a client secret, register the new secret as a second app, disable the old one, and delete it once no connections use it. After its expires_at, an app is no longer offered for new connections.

Troubleshooting self-hosted connectors

Symptom	What to check
503 Credentials could not be stored securely when adding a key-based connection	Neither credentialsKmsKeyArn nor CONNECTOR_MASTER_KEY in config.connectors.secret is set.
500 Token vault encryption is not available when registering an app	Neither tokenVaultKmsKeyArn nor TOKEN_VAULT_MASTER_KEY in config.connectors.secret is set.
”No enabled google_drive app is configured for this tenant” at sign-in	No app is registered for that integration at a level covering the project, or it’s disabled or past expires_at.
Google: redirect_uri_mismatch; Microsoft: AADSTS50011	The redirect URI registered on the app doesn’t exactly match https://<ingress.host>/credential-brokers/return (or config.connectors.oauthReturnUrl).
Microsoft: AADSTS50194	The Entra app is single-tenant. Change Supported account types to multitenant.
422 naming an integration and auth type	That pair isn’t in config.connectors.enabledAuthTypes.
Syncs fail with decryption errors after a redeploy	A key in the Secret or a KMS key ARN changed. Restore the original.