Merge remote-tracking branch 'origin/main' into alona/secret-restart-checksum

ak684 · ak684 · commit c8d847319a44 · 2026-05-21T16:42:00.000-04:00
# Conflicts:
#	charts/openhands/Chart.yaml
diff --git a/charts/openhands-secrets/Chart.yaml b/charts/openhands-secrets/Chart.yaml
@@ -2,5 +2,5 @@ apiVersion: v2
 name: openhands-secrets
 description: A Helm chart for OpenHands secrets
 type: application
-version: 0.1.16
+version: 0.1.18
 appVersion: "1.0"
diff --git a/charts/openhands-secrets/templates/bitbucket-data-center-app.yaml b/charts/openhands-secrets/templates/bitbucket-data-center-app.yaml
@@ -1,4 +1,4 @@
-{{- if or .Values.config.bitbucket_data_center_domain .Values.config.bitbucket_data_center_client_id .Values.config.bitbucket_data_center_client_secret }}
+{{- if or .Values.config.bitbucket_data_center_domain .Values.config.bitbucket_data_center_client_id .Values.config.bitbucket_data_center_client_secret .Values.config.bitbucket_data_center_bot_token }}
 apiVersion: v1
 kind: Secret
 metadata:
@@ -15,4 +15,7 @@ data:
   {{- if .Values.config.bitbucket_data_center_client_secret }}
   client-secret: {{ .Values.config.bitbucket_data_center_client_secret | b64enc | quote }}
   {{- end }}
+  {{- if .Values.config.bitbucket_data_center_bot_token }}
+  bot-token: {{ .Values.config.bitbucket_data_center_bot_token | b64enc | quote }}
+  {{- end }}
 {{- end }}
diff --git a/charts/openhands-secrets/templates/sandbox-image-pull-secret.yaml b/charts/openhands-secrets/templates/sandbox-image-pull-secret.yaml
@@ -0,0 +1,16 @@
+{{- $server := .Values.config.custom_sandbox_image_registry_server | default "" | trim }}
+{{- $user   := .Values.config.custom_sandbox_image_registry_username | default "" | trim }}
+{{- $pass   := .Values.config.custom_sandbox_image_registry_password | default "" | trim }}
+{{- if and $server $user $pass }}
+{{- $auth   := printf "%s:%s" $user $pass | b64enc }}
+{{- $entry  := dict "username" $user "password" $pass "auth" $auth }}
+{{- $cfg    := dict "auths" (dict $server $entry) }}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: sandbox-image-pull-secret
+  namespace: {{ .Release.Namespace }}
+type: kubernetes.io/dockerconfigjson
+data:
+  .dockerconfigjson: {{ $cfg | toJson | b64enc | quote }}
+{{- end }}
diff --git a/charts/openhands-secrets/values.yaml b/charts/openhands-secrets/values.yaml
@@ -73,6 +73,11 @@ config:
   slack_client_secret: ""
   slack_signing_secret: ""
 
+  # Custom sandbox image registry credentials
+  custom_sandbox_image_registry_server: ""
+  custom_sandbox_image_registry_username: ""
+  custom_sandbox_image_registry_password: ""
+
   # Plugin Directory secrets
   plugin_directory_identity_shared_secret: ""
   plugin_directory_session_secret: ""
diff --git a/charts/openhands/templates/_env.yaml b/charts/openhands/templates/_env.yaml
@@ -206,6 +206,12 @@
     secretKeyRef:
       name: bitbucket-data-center-app
       key: client-secret
+- name: BITBUCKET_DATA_CENTER_BOT_TOKEN
+  valueFrom:
+    secretKeyRef:
+      name: bitbucket-data-center-app
+      key: bot-token
+      optional: true
 {{- end }}
 {{- if and (index .Values "litellm-helm") (index .Values "litellm-helm" "enabled") }}
 - name: LITE_LLM_API_URL
diff --git a/docs/assets/github-oauth-flow.mmd b/docs/assets/github-oauth-flow.mmd
@@ -0,0 +1,95 @@
+%% Validated against OpenHands-Cloud @ 136f63fdc
+
+sequenceDiagram
+    autonumber
+    participant Browser
+    participant OpenHands as OpenHands<br/>(Enterprise Server)
+    participant DB as SecretsStore
+    participant Keycloak as Keycloak<br/>(Identity Provider / OAuth Broker)
+    participant GitHub as GitHub<br/>(GitHub App, OAuth 2.0)
+
+    Note over Browser,GitHub: This deployment uses a GitHub APP (not a classic OAuth App).<br/>Evidence: GitHub App client_id has the Iv__ prefix and<br/>the returned user token is prefixed ghu_ (App user-to-server).<br/>GitHub Apps grant capabilities via App-level permissions,<br/>so OAuth scope strings are largely ignored.<br/>User tokens expire (8 h) and the App returns a refresh token<br/>that OpenHands rotates via grant_type=refresh_token.
+
+    Note over Browser,Keycloak: OIDC. SPA initiates login client-side.
+    Note over Browser: SPA at /login builds URL via<br/>generate-auth-url.ts and assigns<br/>window.location.href
+
+    Browser->>Keycloak: GET /realms/allhands/protocol/openid-connect/auth<br/>?client_id=allhands<br/>&response_type=code<br/>&kc_idp_hint=github<br/>&redirect_uri=.../oauth/keycloak/callback<br/>&scope=openid+email+profile<br/>&state=base64(redirect_url)
+
+    Note over Keycloak: kc_idp_hint=github skips Keycloak login screen.<br/>Keycloak does NOT forward the SPA OIDC scopes.<br/>It sends its own configured defaultScope to GitHub.
+
+    Keycloak-->>Browser: 303 See Other<br/>/realms/allhands/broker/github/login?session_code=...
+
+    Browser->>Keycloak: GET /realms/allhands/broker/github/login
+    Keycloak-->>Browser: 303 See Other to github.com
+
+    Note over Browser,GitHub: OAuth 2.0 (NOT OIDC). Keycloak<br/>built-in providerId=github broker.
+    Browser->>GitHub: GET /login/oauth/authorize<br/>?client_id=GITHUB_APP_CLIENT_ID  -- Iv__ prefix marks GitHub App<br/>&redirect_uri=.../realms/allhands/broker/github/endpoint<br/>&response_type=code<br/>&scope=openid+email+profile  -- OIDC strings, not GitHub OAuth scopes<br/>&state=keycloak-state
+
+    Note over GitHub: Scope strings openid/email/profile are<br/>NOT GitHub native scopes (user, user:email, ...).<br/>GitHub Apps ignore them. App permissions are<br/>configured on github.com and apply uniformly.<br/>User authorizes the App (first time) or is auto-redirected.
+
+    GitHub-->>Browser: 302 to Keycloak broker endpoint
+    Browser->>Keycloak: GET /realms/allhands/broker/github/endpoint<br/>?code=github-auth-code<br/>&state=keycloak-state
+
+    Note over Keycloak,GitHub: Server-to-server (no browser).
+    Keycloak->>GitHub: POST /login/oauth/access_token<br/>client_id, client_secret, code, redirect_uri
+    GitHub-->>Keycloak: access_token=ghu_...<br/>refresh_token=ghr_...<br/>expires_in, refresh_token_expires_in
+
+    Keycloak->>GitHub: GET https://api.github.com/user<br/>Authorization: Bearer ghu_...
+    GitHub-->>Keycloak: id, login, email, ...
+
+    Note over Keycloak: Maps github id to user attribute github_id<br/>via github-user-attribute-mapper.<br/>Hardcodes identity_provider=github.<br/>Persists tokens because storeToken=true.
+
+    Keycloak-->>Browser: 302 to OpenHands
+    Browser->>OpenHands: GET /oauth/keycloak/callback<br/>?code=kc-code.session.client<br/>&session_state=...&iss=...
+
+    Note over OpenHands,Keycloak: Server-to-server OIDC.
+    OpenHands->>Keycloak: POST /realms/allhands/protocol/openid-connect/token<br/>grant_type=authorization_code, code,<br/>client_id=allhands, client_secret
+    Keycloak-->>OpenHands: access_token (JWT), id_token (JWT), refresh_token<br/>NO offline_access on this leg
+
+    OpenHands->>Keycloak: GET /realms/allhands/protocol/openid-connect/userinfo<br/>Authorization: Bearer kc_access_token
+    Keycloak-->>OpenHands: sub, email, preferred_username, github_id, identity_provider
+
+    Note over OpenHands: Logs (verbatim):<br/>Logging in user UUID in org UUID<br/>user_logged_in idp=github idp_type=oidc
+
+    Note over OpenHands,Keycloak: Fetch broker-stored GitHub token.
+    OpenHands->>Keycloak: GET /realms/allhands/broker/github/token<br/>Authorization: Bearer kc_access_token
+    Keycloak-->>OpenHands: access_token=ghu_...<br/>refresh_token=ghr_...<br/>expires_at, refresh_expires_at
+    OpenHands->>DB: Encrypt and persist tokens (AuthTokenStore)
+
+    Note over OpenHands: server/routes/auth.py branches on two<br/>independent flags - valid_offline_token and<br/>has_accepted_tos. First login fails both.<br/>Returning users typically pass both.
+
+    alt has_accepted_tos == false (first login)
+        OpenHands-->>Browser: 302 to /accept-tos<br/>?redirect_url=(offline_auth_url_or_app)
+        Note over Browser: SPA renders TOS. User clicks accept.
+        Browser->>OpenHands: POST /api/accept_tos
+        OpenHands-->>Browser: 200 OK, body has redirect_url<br/>(NOT a 302)
+        Note over Browser: SPA reads redirect_url and assigns<br/>window.location.href = redirect_url
+    end
+
+    alt valid_offline_token == false (first login, or offline session expired)
+        Note over Browser,Keycloak: Second OIDC flow. Captures offline (refresh) token.<br/>Keycloak SSO session is live, so no GitHub round-trip.
+        Browser->>Keycloak: GET /realms/allhands/protocol/openid-connect/auth<br/>scope=openid+email+profile+offline_access<br/>redirect_uri=.../oauth/keycloak/offline/callback
+        Keycloak-->>Browser: 302 with new authorization code
+        Browser->>OpenHands: GET /oauth/keycloak/offline/callback?code=...
+        OpenHands->>Keycloak: POST /protocol/openid-connect/token
+        Keycloak-->>OpenHands: access_token + LONG-LIVED refresh_token (offline)
+    end
+
+    OpenHands-->>Browser: Set session cookies, redirect to app<br/>(returning users land here directly with no TOS/offline detour)
+
+    Note over Browser,GitHub: Subsequent calls. GitHub token from local store.
+    Browser->>OpenHands: GET /api/v1/git/installations/search?provider=github
+    OpenHands->>DB: load_tokens(github)
+
+    alt access_token near expiry (less than 15 min left) and refresh_token still valid
+        Note over OpenHands,GitHub: token_manager._refresh_github_token<br/>(gated by AuthTokenStore._is_token_expired<br/>with ACCESS_TOKEN_EXPIRY_BUFFER = 900s)
+        OpenHands->>GitHub: POST https://github.com/login/oauth/access_token<br/>client_id, client_secret, refresh_token,<br/>grant_type=refresh_token
+        GitHub-->>OpenHands: new access_token + new refresh_token<br/>expires_in, refresh_token_expires_in
+        OpenHands->>DB: re-encrypt and persist
+    else access_token still valid
+        Note over OpenHands: Use stored ghu_... as-is
+    end
+
+    OpenHands->>GitHub: GET https://api.github.com/...<br/>Authorization: Bearer ghu_...
+    GitHub-->>OpenHands: Repos / installations / etc.
+    OpenHands-->>Browser: JSON response
diff --git a/docs/assets/github-oauth-flow.png b/docs/assets/github-oauth-flow.png
diff --git a/docs/build-diagrams.sh b/docs/build-diagrams.sh
@@ -9,3 +9,7 @@ which d2 || (echo "d2 command not found, see: https://github.com/terrastruct/d2"
 export D2_LAYOUT=elk
 
 d2 assets/fig1.d2 assets/fig1.svg
+
+which mmdc || (echo "mmdc command not found, install via: npm install -g @mermaid-js/mermaid-cli" ; exit 1)
+
+mmdc -i assets/github-oauth-flow.mmd -o assets/github-oauth-flow.png
diff --git a/replicated/config.yaml b/replicated/config.yaml
@@ -417,27 +417,39 @@ spec:
       items:
         - name: bitbucket_data_center_auth_enabled
           title: Enable Bitbucket Data Center Authentication
-          help_text: Enable Bitbucket Data Center OAuth for user authentication
+          help_text: Let users sign in with their Bitbucket Data Center account.
           type: bool
           default: "0"
         - name: bitbucket_data_center_domain
           title: Bitbucket Data Center Domain
-          help_text: Domain of your Bitbucket Data Center instance
+          help_text: >-
+            Hostname of your Bitbucket Data Center instance (e.g. bbdc.example.com)
           type: text
           when: 'repl{{ ConfigOptionEquals "bitbucket_data_center_auth_enabled" "1" }}'
           required: true
         - name: bitbucket_data_center_client_id
           title: Bitbucket Data Center Client ID
-          help_text: Client ID from your Bitbucket Data Center OAuth App
+          help_text: >-
+            Client ID of the OAuth 2.0 Application Link created in Bitbucket
+            Data Center (Administration → Application Links).
           type: text
           when: 'repl{{ ConfigOptionEquals "bitbucket_data_center_auth_enabled" "1" }}'
           required: true
         - name: bitbucket_data_center_client_secret
           title: Bitbucket Data Center Client Secret
-          help_text: Client Secret from your Bitbucket Data Center OAuth App
+          help_text: Client Secret for that Application Link.
           type: password
           when: 'repl{{ ConfigOptionEquals "bitbucket_data_center_auth_enabled" "1" }}'
           required: true
+        - name: bitbucket_data_center_bot_token
+          title: Bitbucket Data Center Bot Token (optional)
+          help_text: >-
+            HTTP access token for a dedicated bot user (e.g. openhands-bot)
+            with repo access. When set, OpenHands posts comments and reactions
+            as the bot instead of the mentioning user or installer; jobs still
+            run on the invoking user's workspace.
+          type: password
+          when: 'repl{{ ConfigOptionEquals "bitbucket_data_center_auth_enabled" "1" }}'
 
     - name: github_authentication
       title: GitHub Authentication
@@ -705,6 +717,53 @@ spec:
             regex:
               pattern: ^(0|[1-9][0-9]*)$
               message: Must be a non-negative integer
+        - name: custom_sandbox_image_enabled
+          title: Use a Custom Sandbox Image
+          help_text: Use this if you bundle a custom agent-server image.
+          type: bool
+          default: "0"
+        - name: custom_sandbox_image_repository
+          title: Sandbox Image Repository
+          help_text: 'Full repository path with no tag, e.g. my-registry.example.com/openhands/agent-server'
+          type: text
+          when: 'repl{{ ConfigOptionEquals "custom_sandbox_image_enabled" "1" }}'
+          required: true
+        - name: custom_sandbox_image_tag
+          title: Sandbox Image Tag
+          help_text: Image tag, e.g. 1.21.1-python
+          type: text
+          default: "1.21.1-python"
+          when: 'repl{{ ConfigOptionEquals "custom_sandbox_image_enabled" "1" }}'
+          required: true
+        - name: custom_sandbox_image_registry_server
+          title: Registry Server
+          help_text: |
+            Host (and optional port) of the registry, e.g. my-registry.example.com.
+            Leave blank if the registry is public, or if your cluster authenticates
+            via a credential provider (EKS IRSA, GKE Workload Identity, AKS managed
+            identity).
+          type: text
+          when: 'repl{{ ConfigOptionEquals "custom_sandbox_image_enabled" "1" }}'
+          required: false
+        - name: custom_sandbox_image_registry_username
+          title: Registry Username
+          help_text: |
+            Registry username. Some registries use sentinel values: _json_key
+            for GCP Artifact Registry, AWS for ECR static creds, $oauthtoken
+            for Quay robot accounts.
+          type: text
+          when: 'repl{{ ConfigOptionEquals "custom_sandbox_image_enabled" "1" }}'
+          required: false
+        - name: custom_sandbox_image_registry_password
+          title: Registry Password or Credentials
+          help_text: |
+            Password, PAT, or credentials string. This field is single-line.
+            For GCP Artifact Registry, minify the service-account JSON first
+            (e.g. `jq -c . key.json`) and paste the one-line result, with
+            username set to _json_key.
+          type: password
+          when: 'repl{{ ConfigOptionEquals "custom_sandbox_image_enabled" "1" }}'
+          required: false
 
     - name: proxy_configuration
       title: Proxy Configuration
diff --git a/replicated/openhands.yaml b/replicated/openhands.yaml
diff --git a/replicated/secrets.yaml b/replicated/secrets.yaml
