add support for workbench custom oauth integrations

[statik]

These configurations are described at https://docs.posit.co/ide/server-pro/2026.01.0/admin/integration/custom_oauth.html#configuration-file-format

[statik]

Implementation Plan: Custom OAuth Integrations for Workbench

Overview

Add support for Workbench custom OAuth integrations by implementing the oauth-clients.conf configuration file format as documented at https://docs.posit.co/ide/server-pro/2026.01.0/admin/integration/custom_oauth.html#configuration-file-format.

This feature allows users to configure multiple OAuth integrations (Box, Dropbox, Google Drive, etc.) for their Workbench instances, enabling data access from external APIs.

Design Summary

This implementation follows the exact same pattern as the existing Databricks integration (api/core/v1beta1/workbench_config.go:34):

• Add a map-based field OAuthClients to WorkbenchSecretIniConfig
• Map keys become INI section headers (e.g., box-integration → [box-integration])
• Existing reflection-based GenerateConfigMap() handles INI generation automatically
• Secrets fetched using same pattern as FetchAndSetClientSecretForAzureDatabricks()
• File mounted via existing secret-config volume at /mnt/secure-config/rstudio/oauth-clients.conf

Why this works: The codebase already has all the infrastructure for map-based INI configs with secrets. We're just adding a new config type using the proven pattern.

Critical Files

1. api/core/v1beta1/workbench_config.go - Add OAuth client data structures

   • Add WorkbenchOAuthClientConfig struct (after line 854)
   • Add OAuthClients field to WorkbenchSecretIniConfig (line 34)

2. internal/controller/core/workbench.go - Add secret fetching logic

   • Add FetchAndSetOAuthClientSecrets() method (after line 71)
   • Call it in ReconcileWorkbench() (after line 135)
   • Update ensureDeployedService() to add OAuth secrets to SecretProviderClass (around line 269)

Implementation Steps

Step 1: Add OAuth Client Configuration Struct

In api/core/v1beta1/workbench_config.go, add after line 854:

type WorkbenchOAuthClientConfig struct {
    Name                     string   `json:"name,omitempty"`
    ClientId                 string   `json:"client-id,omitempty"`
    ClientSecret             string   `json:"client-secret,omitempty"`
    AuthorizationUrl         string   `json:"authorization-url,omitempty"`
    TokenUrl                 string   `json:"token-url,omitempty"`
    TokenEndpointAuthMethod  string   `json:"token-endpoint-auth-method,omitempty"`
    Scopes                   []string `json:"scopes,omitempty"`
}

Step 2: Add Field to WorkbenchSecretIniConfig

In api/core/v1beta1/workbench_config.go, update WorkbenchSecretIniConfig at line 34:

type WorkbenchSecretIniConfig struct {
    Database           *WorkbenchDatabaseConfig              `json:"database.conf,omitempty"`
    OpenidClientSecret *WorkbenchOpenidClientSecret          `json:"openid-client-secret,omitempty"`
    Databricks         map[string]*WorkbenchDatabricksConfig `json:"databricks.conf,omitempty"`
    OAuthClients       map[string]*WorkbenchOAuthClientConfig `json:"oauth-clients.conf,omitempty"` // NEW
}

Note: The JSON tag "oauth-clients.conf" becomes the filename automatically via the GenerateConfigMap() method (lines 48-50).

Step 3: Add Secret Fetching Function

In internal/controller/core/workbench.go, add after line 71 (after FetchAndSetClientSecretForAzureDatabricks):

func (r *WorkbenchReconciler) FetchAndSetOAuthClientSecrets(ctx context.Context, req ctrl.Request, w *positcov1beta1.Workbench) error {
    l := r.GetLogger(ctx)

    if w.Spec.SecretConfig.WorkbenchSecretIniConfig.OAuthClients == nil {
        return nil
    }

    for integrationName, config := range w.Spec.SecretConfig.WorkbenchSecretIniConfig.OAuthClients {
        if config.ClientId == "" {
            l.Info("skipping OAuth integration with no client ID", "integration", integrationName)
            continue
        }

        clientSecretName := fmt.Sprintf("dev-oauth-client-secret-%s", integrationName)

        if cs, err := product.FetchSecret(ctx, r, req, w.Spec.Secret.Type, w.Spec.Secret.VaultName, clientSecretName); err != nil {
            l.Error(err, "error fetching client secret for OAuth integration", "integration", integrationName)
            return err
        } else {
            config.ClientSecret = cs
            l.Info("successfully fetched OAuth client secret", "integration", integrationName)
        }
    }

    return nil
}

Pattern: Identical to FetchAndSetClientSecretForAzureDatabricks() at lines 49-71, adapted for OAuth clients.

Step 4: Call Secret Fetching in Reconciliation

In internal/controller/core/workbench.go, add after line 135 (after the Databricks secret fetching):

// fetch OAuth client secrets
if err := r.FetchAndSetOAuthClientSecrets(ctx, req, w); err != nil {
    l.Error(err, "error fetching OAuth client secrets")
    return ctrl.Result{}, err
}

Step 5: Add OAuth Secrets to SecretProviderClass (AWS)

In internal/controller/core/workbench.go, in the ensureDeployedService() method around line 269 (where other secrets are added to allSecrets map for AWS Secrets Manager):

// OAuth client secrets
if w.Spec.SecretConfig.WorkbenchSecretIniConfig.OAuthClients != nil {
    for integrationName, config := range w.Spec.SecretConfig.WorkbenchSecretIniConfig.OAuthClients {
        if config.ClientId != "" {
            secretKey := fmt.Sprintf("dev-oauth-client-secret-%s", integrationName)
            allSecrets[secretKey] = secretKey
        }
    }
}

Step 6: Run Code Generation

just mgenerate

This regenerates CRD manifests and API documentation after modifying the API types.

Example Usage

Kubernetes Secrets Approach

Workbench CRD:

apiVersion: core.posit.team/v1beta1
kind: Workbench
metadata:
  name: my-workbench
spec:
  secret:
    type: kubernetes
    vaultName: my-workbench-secrets

  secretConfig:
    workbench-secret-ini-config:
      oauth-clients.conf:
        box-integration:
          name: "Box API Access"
          client-id: "your-box-client-id"
          authorization-url: "https://account.box.com/api/oauth2/authorize"
          token-url: "https://api.box.com/oauth2/token"
          scopes: ["read", "write"]

        google-drive:
          name: "Google Drive"
          client-id: "your-google-client-id"
          authorization-url: "https://accounts.google.com/o/oauth2/v2/auth"
          token-url: "https://oauth2.googleapis.com/token"
          scopes: ["https://www.googleapis.com/auth/drive.readonly"]

Kubernetes Secret:

apiVersion: v1
kind: Secret
metadata:
  name: my-workbench-secrets
  namespace: posit-team
type: Opaque
stringData:
  dev-oauth-client-secret-box-integration: "actual-box-secret-xyz"
  dev-oauth-client-secret-google-drive: "actual-google-secret-abc"

AWS Secrets Manager Approach

Workbench CRD:

apiVersion: core.posit.team/v1beta1
kind: Workbench
metadata:
  name: my-workbench
spec:
  awsAccountId: "123456789012"
  secret:
    type: aws
    vaultName: "20240101-default-my-workbench"

  secretConfig:
    workbench-secret-ini-config:
      oauth-clients.conf:
        dropbox-integration:
          name: "Dropbox Access"
          client-id: "your-dropbox-client-id"
          authorization-url: "https://www.dropbox.com/oauth2/authorize"
          token-url: "https://api.dropbox.com/oauth2/token"

AWS Secrets Manager:

• Vault: 20240101-default-my-workbench
• Secret name: dev-oauth-client-secret-dropbox-integration
• Secret value: "actual-dropbox-secret-xyz"

Generated Configuration

The above examples generate /mnt/secure-config/rstudio/oauth-clients.conf:

[box-integration]
name=Box API Access
client-id=your-box-client-id
client-secret=actual-box-secret-xyz
authorization-url=https://account.box.com/api/oauth2/authorize
token-url=https://api.box.com/oauth2/token
scopes=read,write

[google-drive]
name=Google Drive
client-id=your-google-client-id
client-secret=actual-google-secret-abc
authorization-url=https://accounts.google.com/o/oauth2/v2/auth
token-url=https://oauth2.googleapis.com/token
scopes=https://www.googleapis.com/auth/drive.readonly

How it works:

1. Map key (e.g., box-integration) becomes section header [box-integration]
2. Struct fields auto-convert to kebab-case INI keys via toKebabCase()
3. Array fields (e.g., scopes) auto-join with commas via sliceToString()
4. File mounted at /mnt/secure-config/rstudio/oauth-clients.conf via existing secret-config volume
5. Workbench reads it via XDG_CONFIG_DIRS environment variable

How It Integrates

Configuration Flow

1. User creates Workbench CR with OAuth clients defined in secretConfig.workbench-secret-ini-config.oauth-clients.conf
2. User creates secrets (K8s Secret or AWS Secrets Manager) with naming pattern dev-oauth-client-secret-{integration-name}
3. Controller reconciles:
   • Calls FetchAndSetOAuthClientSecrets() to fetch secrets from vault
   • Populates ClientSecret fields in memory
   • Calls secretConfig.GenerateSecretData() → WorkbenchSecretIniConfig.GenerateConfigMap()
   • Reflection-based generator creates INI-formatted oauth-clients.conf content
4. Secret creation:
   • Creates/updates Kubernetes Secret {workbench-name}-config with oauth-clients.conf key
   • Computes SHA256 hash of secret data
   • Adds hash to Deployment annotation (workbench.posit.team/secret-sha)
5. Pod deployment:
   • Mounts secret via existing secret-config volume (workbench_types.go:734-746)
   • File appears at /mnt/secure-config/rstudio/oauth-clients.conf
   • Workbench reads it automatically (Workbench checks XDG_CONFIG_DIRS=/mnt/config/rstudio:/mnt/config:/mnt/secure:/mnt/secure-config:/mnt/session)

Auto-Restart on Changes

When user updates OAuth configuration:

1. New SHA calculated from updated secret content
2. Deployment annotation changes
3. Kubernetes triggers rolling update
4. New pods start with updated OAuth config

This uses the existing SHA-based restart mechanism (no additional work needed).

Verification & Testing

Unit Tests

Add tests in api/core/v1beta1/workbench_config_test.go:

• Test WorkbenchSecretIniConfig.GenerateConfigMap() with OAuth clients
• Verify INI format generation
• Verify map keys become section headers
• Verify field names convert to kebab-case
• Verify arrays convert to comma-separated strings

Integration Tests

Test scenarios:

1. Single OAuth integration - verify config file generated correctly
2. Multiple OAuth integrations - verify multiple sections in INI file
3. K8s Secrets - verify secret fetching from Kubernetes Secret
4. AWS Secrets Manager - verify secret fetching from AWS
5. Missing secret - verify error handling
6. Empty client ID - verify integration skipped gracefully
7. Config updates - verify pod restart on SHA change

Manual Verification

Deploy test Workbench:

kubectl apply -f test-workbench-oauth.yaml
kubectl apply -f test-workbench-secrets.yaml

Check generated secret:

kubectl get secret my-workbench-config -n posit-team -o yaml
kubectl get secret my-workbench-config -n posit-team -o jsonpath='{.data.oauth-clients\.conf}' | base64 -d

Verify file in pod:

kubectl exec -it deployment/my-workbench -n posit-team -- cat /mnt/secure-config/rstudio/oauth-clients.conf

Test OAuth flow in Workbench:

1. Log into Workbench UI
2. Go to Tools → Global Options → OAuth
3. Verify custom integrations appear
4. Test authorization flow with external service

End-to-End Verification

1. Create Workbench with OAuth integrations configured
2. Verify pod starts successfully
3. Verify oauth-clients.conf file exists in pod with correct content
4. Log into Workbench and verify OAuth integrations available in UI
5. Update OAuth configuration in CR
6. Verify pod automatically restarts
7. Verify updated configuration reflected in pod

Notes & Considerations

Security

• Client secrets stored in Kubernetes Secrets or AWS Secrets Manager (encrypted at rest)
• Secrets mounted as read-only volumes
• File permissions: DefaultMode is nil (defaults to 0644), acceptable for containerized environment
• Secrets never logged or exposed in CRD status

Secret Naming Convention

Secret keys follow pattern: dev-oauth-client-secret-{integration-name}

Examples:

• dev-oauth-client-secret-box-integration
• dev-oauth-client-secret-google-drive
• dev-oauth-client-secret-dropbox-integration

Optional Fields

All fields except client-id, authorization-url, and token-url are optional:

• name: Defaults to section header if not provided
• client-secret: Fetched from vault (required in practice)
• token-endpoint-auth-method: Workbench defaults to client-secret-post
• scopes: Optional, depends on OAuth provider requirements

Workbench Redirect URI

Users must configure redirect URI in OAuth provider settings:

https://<your-workbench-url>/oauth_redirect_callback

This is not configurable in the operator - it's fixed in Workbench.

Why This Design Works

1. Zero changes to generation logic - Existing GenerateConfigMap() handles everything via reflection
2. Proven pattern - Exact same structure as Databricks integration (in production)
3. Minimal code - ~40 lines total across 2 files
4. No new dependencies - Uses existing product.FetchSecret() infrastructure
5. Auto-restart - Existing SHA mechanism handles pod updates
6. Type-safe - Go structs provide validation and autocomplete
7. Dual secret support - Works with both K8s Secrets and AWS Secrets Manager out of the box

Estimated Scope

• Files modified: 2
• Lines added: ~40
• New dependencies: 0
• Breaking changes: 0
• Risk level: Low (follows proven patterns)