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:
- Option 1: Using the Secret Manager from the Enterprise h2oGPTe UI
- for administrators and users
- uses SecureStore in the background
- 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β
- In Enterprise h2oGPTe, click Account Circle.
- Select System Dashboard.
- Click Secret Manager in the Configuration section.
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.
Step 2: Configure connector-specific credentialsβ
- Click + New Secret.
- Select the Connector type from the dropdown.
- Configure the connector-specific credentials:
- AWS S3
- Azure Key
- Azure SAS
- Google Cloud Storage (GCS)
- SharePoint Online
- SharePoint On-Premises
- 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)
- Account Name: Your Azure storage account name
- Account Key: Your Azure storage account access key
- Account Name: Your Azure storage account name
- Account Key: Your Azure storage account shared access signature (SAS) token
- Project ID: Your Google Cloud project identifier
- Service Account JSON: JSON file containing your service account credentials
- Site URL: The URL of your SharePoint Online site
- Tenant ID: Your Microsoft 365 tenant identifier
- Client ID: Azure AD application client ID
- Client Secret: Azure AD application client secret
- Site URL: The URL of your on-premises SharePoint site
- Username: Your SharePoint username or email
- Password: Your SharePoint account password
- Click Submit.
Step 3: Use secure connectors to add documentsβ
- Navigate to Collections β + New Collection.
- Create a collection for your documents.
- Click + Add Documents.
- Select your cloud storage connector type.
- In the Credential ID dropdown, select your configured secret.
- Configure the storage path and other connector-specific settings.
- Enable auto-sync if you want automatic document synchronization.
- Click Add to start the document ingestion.
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β
- SSO to your environment (for example, cloud-dev).
- Set the Kubernetes context:
kubectl config use-context cloud-dev
- 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
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β
- Navigate to Collections β + New Collection.
- Create a collection for your documents.
- Click + Add Documents.
- Select your cloud storage connector type.
- The Credential ID dropdown will now show secrets from SecureStore.
- Select the appropriate credential and configure the storage path.
- Enable auto-sync if you want automatic document synchronization.
- 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:
Option | Requirements | Setup Steps |
---|---|---|
File-Based (Recommended) | None | export 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 |
SecureStore | Cloud-dev access | 1. 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:
Issue | Solution |
---|---|
SecretManager is not configured | Enable Secret Manager first |
No secret IDs found | Add credentials in Secret Manager admin panel |
Permission denied accessing SecureStore | Check RBAC policies and service account whitelist |
Failed to create secure connector | Verify credential ID exists and format is correct |
- Submit and view feedback for this page
- Send feedback about Enterprise h2oGPTe to cloud-feedback@h2o.ai