Data connectors and OAuth

Overview

Enterprise h2oGPTe supports data ingestion from multiple external sources through built-in connectors. Some connectors, such as SharePoint Online, Confluence Cloud, and Snowflake, require OAuth credentials to authenticate with the external service.

Slack also authenticates through OAuth, but for a different purpose. Instead of importing documents, the Slack connector lets each user link a personal Slack account on the Data Connectors page so agents can act on their behalf.

This page covers:

• Connector access control: How role-based permissions govern which users can use which connectors
• OAuth configuration: How to set up OAuth credentials for SharePoint, Confluence, and Snowflake
• Security: How OAuth secrets are stored and protected

note

OAuth connector configuration requires administrator privileges. Users interact with connectors through the collection creation workflow. To learn about using connectors to import data, see Connectors.

Connector access control

Role-based permissions control access to each data connector. Administrators can turn on or turn off specific connectors for each role by assigning or removing the corresponding permission.

Connector	Permission identifier
File system	h2ogpte/connectors/file_system
Web crawl	h2ogpte/connectors/web_crawl
Amazon S3	h2ogpte/connectors/s3
Azure Blob Storage	h2ogpte/connectors/azure_blob_store
Google Cloud Storage	h2ogpte/connectors/google_cloud_storage
SharePoint Online	h2ogpte/connectors/sharepoint_online
SharePoint On-Premise	h2ogpte/connectors/sharepoint_on_premise
Confluence	h2ogpte/connectors/confluence

note

Snowflake doesn't have a connector permission. All users can access the Snowflake connector when OAuth credentials are configured. To restrict Snowflake access, remove the OAuth credentials from System Settings.

By default, the admin and default roles have access to all connectors. The guest role has access to all connectors except File system. The user and viewer roles don't have connector access by default. To restrict connector access for a role, remove the corresponding permission:

# Remove file system connector access from a role
curl -X DELETE "https://<YOUR_DOMAIN>/api/v1/roles/{role_id}/permissions/h2ogpte/connectors/file_system" \
  -H "Authorization: Bearer <API_KEY>"

To learn more about managing role permissions, see Roles and Permissions.

OAuth connector configuration

SharePoint Online, Confluence Cloud, Snowflake, and Slack connectors require OAuth credentials. Configure these credentials through the OAUTH category in System Settings.

Access OAuth settings

1. In Enterprise h2oGPTe, click account_circle Account Circle.
2. Select System Dashboard.
3. In the Configuration section, click System settings.
4. Scroll down to the OAUTH category.

SharePoint Online

Configure the following settings for SharePoint Online integration:

Setting	Description
runtime_sharepoint_oauth_client_id	OAuth Client ID from your Microsoft Entra ID app registration.
runtime_sharepoint_oauth_client_secret	OAuth Client Secret. Encrypted setting, see OAuth secret security.
runtime_sharepoint_oauth_tenant_id	Microsoft Entra ID tenant ID. Defaults to common for multi-tenant access.
runtime_sharepoint_oauth_redirect_url	OAuth redirect URL. Must match the redirect URI configured in your Microsoft Entra ID app registration.
runtime_sharepoint_oauth_scopes	OAuth scopes for Microsoft Graph API access.

# Set SharePoint OAuth Client ID
curl -X PUT "https://<YOUR_DOMAIN>/api/v1/configurations/runtime_sharepoint_oauth_client_id" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"string_value": "<CLIENT_ID>"}'

# Set SharePoint OAuth Client Secret (stored encrypted)
curl -X PUT "https://<YOUR_DOMAIN>/api/v1/configurations/runtime_sharepoint_oauth_client_secret" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"string_value": "<CLIENT_SECRET>"}'

# Set Microsoft Entra ID Tenant ID
curl -X PUT "https://<your-domain>/api/v1/configurations/runtime_sharepoint_oauth_tenant_id" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"string_value": "<TENANT_ID>"}'

note

Use common (the default) for multi-tenant app registrations, which allows users from any Microsoft Entra ID organization to authenticate. Set this to your organization's specific tenant ID only if the app is registered as single-tenant.

Confluence Cloud

note

For a step-by-step walkthrough of registering the OAuth app in the Atlassian developer console, see Confluence OAuth setup.

Configure the following settings for Confluence Cloud integration:

Setting	Description
runtime_confluence_oauth_client_id	OAuth Client ID from your Atlassian app registration.
runtime_confluence_oauth_client_secret	OAuth Client Secret. Encrypted setting, see OAuth secret security.
runtime_confluence_oauth_redirect_url	OAuth redirect URL. Must match the redirect URI configured in your Atlassian app registration.
runtime_confluence_oauth_scopes	OAuth scopes for Confluence API access.

# Set Confluence OAuth Client ID
curl -X PUT "https://<YOUR_DOMAIN>/api/v1/configurations/runtime_confluence_oauth_client_id" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"string_value": "<CLIENT_ID>"}'

# Set Confluence OAuth Client Secret (stored encrypted)
curl -X PUT "https://<YOUR_DOMAIN>/api/v1/configurations/runtime_confluence_oauth_client_secret" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"string_value": "<CLIENT_SECRET>"}'

Snowflake

Configure the following settings for Snowflake integration:

Setting	Description
runtime_snowflake_oauth_client_id	OAuth Client ID for Snowflake.
runtime_snowflake_oauth_client_secret	OAuth Client Secret for Snowflake. Encrypted setting, see OAuth secret security.
runtime_snowflake_account_identifier	Snowflake Account Identifier (for example, xy12345.us-east-1).
runtime_snowflake_oauth_scopes	OAuth scopes for Snowflake access.
runtime_snowflake_oauth_redirect_url	OAuth redirect URL for Snowflake.

# Set Snowflake OAuth Client ID
curl -X PUT "https://<YOUR_DOMAIN>/api/v1/configurations/runtime_snowflake_oauth_client_id" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"string_value": "<CLIENT_ID>"}'

# Set Snowflake OAuth Client Secret (encrypted at rest on this path)
curl -X PUT "https://<YOUR_DOMAIN>/api/v1/configurations/runtime_snowflake_oauth_client_secret" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"string_value": "<CLIENT_SECRET>"}'

# Set Snowflake Account Identifier
curl -X PUT "https://<YOUR_DOMAIN>/api/v1/configurations/runtime_snowflake_account_identifier" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"string_value": "<ACCOUNT_IDENTIFIER>"}'

Slack

Configure the following settings for the Slack connector, which lets users link their personal Slack account from the Data Connectors page:

Setting	Description
runtime_slack_oauth_client_id	OAuth Client ID from your Slack app. An empty value hides the Slack card on the Data Connectors page.
runtime_slack_oauth_client_secret	OAuth Client Secret. Encrypted at rest when seeded by environment variable on first start or set through the configurations API. See OAuth secret security.
runtime_slack_oauth_redirect_url	OAuth redirect URL. When unset, falls back to <base URL>/api/v1/connectors/slack/callback. Must match the redirect URL configured in your Slack app.
runtime_slack_oauth_scopes_bot	Comma-separated bot token scopes. Set this and/or the user scopes; users need at least one to connect Slack.
runtime_slack_oauth_scopes_user	Comma-separated user token scopes. Set this and/or the bot scopes; users need at least one to connect Slack.

The Slack card appears on the Data Connectors page only when each of these conditions holds:

• Connector linking is turned on at deployment time: H2OGPTE_MUX_ENABLE_CONNECTOR_LINKING=true (Helm: mux.config.oauth.enabled). Off by default. This also requires H2OGPTE_MUX_CONNECTOR_ENCRYPTION_KEY (at least 32 characters). Without the key, mux doesn't start.
• runtime_slack_oauth_client_id has a value.
• The user's role has the Link connectors permission (h2ogpte/display/link_connectors). Without it, the user never sees the Connectors menu item, so no card can appear.

# Set Slack OAuth Client ID
curl -X PUT "https://<YOUR_DOMAIN>/api/v1/configurations/runtime_slack_oauth_client_id" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"string_value": "<CLIENT_ID>"}'

# Set Slack OAuth Client Secret (stored encrypted)
curl -X PUT "https://<YOUR_DOMAIN>/api/v1/configurations/runtime_slack_oauth_client_secret" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"string_value": "<CLIENT_SECRET>"}'

# Set Slack user token scopes
curl -X PUT "https://<YOUR_DOMAIN>/api/v1/configurations/runtime_slack_oauth_scopes_user" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"string_value": "<COMMA_SEPARATED_SCOPES>"}'

caution

The Slack card appears as soon as runtime_slack_oauth_client_id has a value, but connecting fails until at least one scope setting also has a value. Until then, users who click Connect see this error: Slack OAuth scopes are not configured — set runtime_slack_oauth_scopes_user and/or runtime_slack_oauth_scopes_bot in Global Settings.

note

Neither runtime_slack_oauth_scopes_user nor runtime_slack_oauth_scopes_bot has a default value. The Slack consent screen shows exactly the scopes you configure, and nothing more.

A starting point for runtime_slack_oauth_scopes_user:

chat:write,channels:read,channels:history,groups:read,groups:history,im:read,im:history,mpim:read,mpim:history,search:read,users:read

For each conversation type, include both the <type>:read scope, to list conversations of that type, and the <type>:history scope, to read messages in them. Omitting the :read half causes a scope error. Always include users:read. Add chat:write so a connected user's agent can post as them, and search:read to enable message search.

For how users connect their Slack account and what the resulting tokens can do, see Data Connectors.

OAuth secret security

The system marks the OAuth client secrets for SharePoint, Confluence, Snowflake, and Slack as encrypted settings. Administrators enter plaintext values, and the system decrypts the stored value when it starts an OAuth authentication flow.

Which write path encrypts the value at rest depends on how you set it:

How you set the secret	Stored in the database as
Environment variable, first start only (no stored value yet)	AES-GCM ciphertext
PUT /api/v1/configurations/{key_name}	AES-GCM ciphertext
System Settings page in the System Dashboard	Plaintext

An environment variable seeds the setting only when the database has no value for it yet. After that, changing the environment variable doesn't change the stored secret. To change a stored secret, use PUT /api/v1/configurations/{key_name}.

warning

The System Settings page stores a secret in plaintext, even though it masks the value. If your deployment requires encryption at rest, set the secret through the configurations API or use an external secret manager.

The System Dashboard masks encrypted settings and offers a reveal option. Reveal shows the stored value, so a secret set by environment variable or the API appears as base64 ciphertext.

The encryption key is the internal_encryption_secret value in the Redis connection Secret (H2OGPTE_MUX_INTERNAL_ENCRYPTION_SECRET). Keep it stable. If the key changes, the stored secrets no longer decrypt and the provider rejects the sign-in. To recover, set each secret again through the configurations API. The Helm chart keeps the existing key on upgrade only when it can read the cluster. If you render the chart without cluster access (for example, helm template or Argo CD), each render makes a new key, and every stored secret stops decrypting at the next sync. For these tools, supply a stable key with global.redis.existingSecret.

Upgrade from an earlier version

Marking a setting as encrypted doesn't encrypt the value already in the database. On the first start after the upgrade, Enterprise h2oGPTe marks each existing OAuth client secret as encrypted and keeps its stored value, which for the Snowflake secret is plaintext. The connector keeps working with that value, but the value isn't encrypted at rest until you set it again.

To complete the upgrade for each configured connector secret:

1. Get the value to store:
   • Snowflake: rotate the client secret at Snowflake to get a new value. Before this release, mux wrote the Snowflake client secret to the h2ogpte-mux log in cleartext on every start, so treat the current value as exposed in your log retention.
   • SharePoint, Confluence, and Slack: you can use the current value, unless you set a SharePoint or Confluence secret on the System Settings page in version 1.7.4 or earlier. Those versions wrote that secret to the log in plain text on every start, so rotate it with the provider and use the new value.
2. Set the value with PUT /api/v1/configurations/{key_name}. An environment variable doesn't replace a stored value.
3. On the Connectors page, connect the account again to confirm that sign-in still works.

Collection sharing and access

For collection sharing permissions (h2ogpte/collection/share, h2ogpte/collection/public, h2ogpte/collection/import) and document-level access controls, see Roles and Permissions.

Configure OAuth with the Python SDK

The following example configures SharePoint OAuth credentials using the Python SDK:

from h2ogpte import H2OGPTE

admin = H2OGPTE(address="https://<YOUR_DOMAIN>", api_key="<API_KEY>")

# Configure SharePoint OAuth
admin.set_global_configuration(
    "runtime_sharepoint_oauth_client_id", "<CLIENT_ID>",
    can_overwrite=False, is_public=False
)
admin.set_global_configuration(
    "runtime_sharepoint_oauth_client_secret", "<CLIENT_SECRET>",
    can_overwrite=False, is_public=False
)
admin.set_global_configuration(
    "runtime_sharepoint_oauth_tenant_id", "<TENANT_ID>",
    can_overwrite=False, is_public=False
)

Related topics

• Data Connectors - Connect a personal Slack account and manage other connected accounts
• Connectors - Overview of available data connectors and how to use them
• Auto-Sync Connectors - Configure automatic scheduled synchronization for cloud connectors
• Roles and Permissions - Manage connector access permissions per role
• System Settings - Complete OAuth settings reference
• Secret Manager - Manage secrets used by connectors and integrations

---

Feedback

• Submit and view feedback for this page
• Send feedback about Enterprise h2oGPTe to cloud-feedback@h2o.ai