Skip to main content
Version: v1.6.43-dev4 🚧

Tutorial 11: Secure connectors and secret manager

Overview​

This tutorial demonstrates how to use the Secret Manager and Secure Connectors features in Enterprise h2oGPTe to securely access cloud storage systems without storing credentials directly in the application database.

The Secret Manager provides secure credential management with:

  • SecureStore: Production-grade secret management with audit logging, access control, and multi-tenant support.

You will learn two approaches for managing secrets:

  1. Option 1: Using the Secret Manager from the Enterprise h2oGPTe UI
  • for administrators and users
  • uses SecureStore in the background
  1. Option 2: Using SecureStore
  • for production environments
  • the officially supported secret storage

By the end of this tutorial, you will understand how to:

  • Configure secrets for cloud storage connectors
  • Use secure connectors to access cloud storage
  • Manage credentials securely without exposing them in the application

Prerequisites​

  • Secret Manager must be enabled by your administrator. See Secret Manager guide for more details.
  • Access to a cloud storage account (AWS S3, Azure Blob, GCS, or SharePoint)

Option 1: Using Enterprise h2oGPTe UI secret manager​

Step 1: Access the secret manager​

  1. In Enterprise h2oGPTe, click Account Circle.
  2. Select System Dashboard.
  3. Click Secret Manager in the Configuration section.
note

If you don't see the Secret Manager option, it needs to be enabled at the deployment level. For detailed instructions on enabling Secret Manager, see the enabling options in the Secret Manager guide.

Access Secret Manager

Step 2: Configure connector-specific credentials​

  1. Click + New Secret.
  2. Select the Connector type from the dropdown.
  3. Configure the connector-specific credentials:
  • Access Key ID: Your AWS access key identifier
  • Secret Access Key: Your AWS secret access key
  • Region: AWS region where your S3 bucket is located (e.g., us-east-1)

AWS S3 Credentials

  1. Click Submit.

Step 3: Use secure connectors to add documents​

  1. Navigate to Collections → + New Collection.
  2. Create a collection for your documents.
  3. Click + Add Documents.
  4. Select your cloud storage connector type.
  5. In the Credential ID dropdown, select your configured secret.
  6. Configure the storage path and other connector-specific settings.
  7. Enable auto-sync if you want automatic document synchronization.
  8. Click Add to start the document ingestion.
note

The credentials are retrieved securely from the Secret Manager and never stored in the Enterprise h2oGPTe database.

Option 2: Using SecureStore​

This option is for developers who need to work with SecureStore in a development environment.

Step 1: Set up development environment​

  1. SSO to your environment (for example, cloud-dev).
  2. Set the Kubernetes context: 
    kubectl config use-context cloud-dev
  3. Forward the SecureStore port: 
    kubectl port-forward svc/securestore-server -n dev-securestore 3001:8081

Step 2: Configure environment variables​

Set the required environment variables:

export H2OGPTE_SECRET_MANAGER_ENABLED=true
export H2OGPTE_SECRET_MANAGER=securestore
export H2OGPTE_SECURE_CONNECTORS_ENABLED=true
export H2OGPTE_SECURE_CONNECTORS_SECURE_STORE_SERVER_ENDPOINT=localhost:3001
export H2OGPTE_SECURE_CONNECTORS_WORKSPACE_ID=your-workspace-id
note

The Secret Manager feature must be enabled before using secure connectors.

Step 3: Create secrets in SecureStore​

Create secrets with the appropriate structure for your connector type:

For S3: Use a json with the following format:

Schema:
  access_key_id: string        # AWS Access Key ID
  secret_access_key: string    # AWS Secret Access Key
  session_token: string        # (Optional) AWS Session Token

For GCS: Use a service account json with the following format:

Schema:
  type: string                 # Must be "service_account"
  project_id: string           # GCP Project ID
  private_key_id: string       # Private key identifier
  private_key: string          # Private key in PEM format
  client_email: string         # Service account email
  client_id: string            # Client ID
  auth_uri: string             # OAuth2 authorization endpoint
  token_uri: string            # OAuth2 token endpoint
  auth_provider_x509_cert_url: string  # Provider certificate URL
  client_x509_cert_url: string         # Client certificate URL
  universe_domain: string      # API universe domain

For Azure Blob Storage: Use a json with the following format:

Schema:
  account_name: string         # Azure Storage Account Name
  sas_token: string           # SAS Token for authentication

Step 4: Start Enterprise h2oGPTe services​

make run-mux run-core-cpu run-crawl-cpu

Step 5: Use secure connectors to add documents​

  1. Navigate to Collections → + New Collection.
  2. Create a collection for your documents.
  3. Click + Add Documents.
  4. Select your cloud storage connector type.
  5. The Credential ID dropdown will now show secrets from SecureStore.
  6. Select the appropriate credential and configure the storage path.
  7. Enable auto-sync if you want automatic document synchronization.
  8. Click Add to start the document ingestion.

API usage (example)​

You can also use the Python API to programmatically work with secure connectors:

from h2ogpte_crawl.secure_connectors import get_available_secret_ids, create_secure_cloud_storage_connector

# List available credentials for S3
secret_ids = get_available_secret_ids("s3")
print(f"Available S3 credentials: {secret_ids}")

# Create a secure connector
connector = create_secure_cloud_storage_connector("s3", "my-creds", {"credential_id": "my-creds"})

Quick verification​

Verify your setup is working correctly:

# Check logs for secure connector activity
docker logs h2ogpte-core | grep -i "secure.*connector"

# Test API access to secrets
python -c "from h2ogpte_crawl.secure_connectors import get_available_secret_ids; print(get_available_secret_ids('s3'))"

Local development options​

For developers who need to set up local development environments, you have two options:

OptionRequirementsSetup Steps
File-Based (Recommended)Noneexport H2OGPTE_SECRET_MANAGER_ENABLED=true
export H2OGPTE_SECRET_MANAGER=filebased
export H2OGPTE_SECURE_CONNECTORS_ENABLED=true
make run-mux run-core-cpu run-crawl-cpu
SecureStoreCloud-dev access1. kubectl config use-context cloud-dev
2. make forward-secure-store-port
3. Set environment variables
4. make run-mux run-core-cpu run-crawl-cpu

Security features​

The Secure Connectors feature provides several security benefits to protect your cloud storage credentials:

  • Credentials never in Enterprise h2oGPTe database: Your cloud storage credentials are stored securely in the Secret Manager and never exposed in the Enterprise h2oGPTe database
  • SecureStore audit logging: All access to secrets is logged for security monitoring and compliance
  • Kubernetes RBAC policies: Role-based access control ensures only authorized services can access secrets
  • Encrypted communication: All communication between Enterprise h2oGPTe and SecureStore is encrypted

Troubleshooting​

If you encounter issues with Secure Connectors, refer to the following common problems and solutions:

IssueSolution
SecretManager is not configuredEnable Secret Manager first
No secret IDs foundAdd credentials in Secret Manager admin panel
Permission denied accessing SecureStoreCheck RBAC policies and service account whitelist
Failed to create secure connectorVerify credential ID exists and format is correct
Feedback