Skip to content

πŸ™Œ OpenHands: AI-Driven Development

feat(jira-dc): persist and inject per-user OAuth tokens in resolver conversations (#14650)

Alona5982cf16c56d
diff --git a/enterprise/integrations/jira_dc/jira_dc_manager.py b/enterprise/integrations/jira_dc/jira_dc_manager.py
index 6fee31ce14..1252f3c0d2 100644
--- a/enterprise/integrations/jira_dc/jira_dc_manager.py
+++ b/enterprise/integrations/jira_dc/jira_dc_manager.py
@@ -11,6 +11,7 @@ from integrations.jira_dc.jira_dc_service_account import (
from integrations.jira_dc.jira_dc_types import (
JiraDcViewInterface,
)
+from integrations.jira_dc.jira_dc_user_token import JiraDcUserTokenError
from integrations.jira_dc.jira_dc_view import (
JiraDcExistingConversationView,
JiraDcFactory,
@@ -22,6 +23,7 @@ from integrations.utils import (
OPENHANDS_RESOLVER_TEMPLATES_DIR,
filter_potential_repos_by_user_msg,
get_account_not_linked_message,
+ get_jira_dc_relink_message,
get_session_expired_message,
get_user_not_found_message,
infer_repo_from_message,
@@ -509,6 +511,10 @@ class JiraDcManager(Manager[JiraDcViewInterface]):
logger.warning(f'[Jira DC] Session expired: {str(e)}')
msg_info = get_session_expired_message()
+ except JiraDcUserTokenError as e:
+ logger.warning(f'[Jira DC] User token unavailable: {str(e)}')
+ msg_info = get_jira_dc_relink_message(jira_dc_view.job_context.display_name)
+
except ConcurrencyLimitError as e:
detail = e.detail if isinstance(e.detail, dict) else {}
limit = detail.get('limit', '?')
diff --git a/enterprise/integrations/jira_dc/jira_dc_user_token.py b/enterprise/integrations/jira_dc/jira_dc_user_token.py
new file mode 100644
index 0000000000..50079e56e7
--- /dev/null
+++ b/enterprise/integrations/jira_dc/jira_dc_user_token.py
@@ -0,0 +1,133 @@
+"""Per-user Jira DC OAuth token resolution and refresh."""
+
+import time
+from dataclasses import dataclass
+from typing import Final
+
+import httpx
+from pydantic import SecretStr
+from server.auth.constants import (
+ JIRA_DC_BASE_URL,
+ JIRA_DC_CLIENT_ID,
+ JIRA_DC_CLIENT_SECRET,
+)
+from server.auth.token_manager import TokenManager
+from storage.jira_dc_integration_store import JiraDcIntegrationStore
+
+from openhands.app_server.utils.http_session import httpx_verify_option
+from openhands.app_server.utils.logger import openhands_logger as logger
+
+# Refresh access tokens this many seconds before wire expiry.
+_ACCESS_REFRESH_BUFFER_SECONDS: Final = 300
+
+JIRA_DC_TOKEN_URL = f'{JIRA_DC_BASE_URL}/rest/oauth2/latest/token'
+
+
+class JiraDcUserTokenError(Exception):
+ """Per-user Jira DC OAuth token is missing or unrefreshable."""
+
+
+@dataclass(frozen=True)
+class JiraDcUserToken:
+ access_token: SecretStr
+ expires_at: int # 0 if unknown
+
+
+async def get_user_jira_dc_token(
+ *,
+ keycloak_user_id: str,
+ workspace_id: int,
+ token_manager: TokenManager,
+ store: JiraDcIntegrationStore,
+) -> JiraDcUserToken:
+ """Resolve a valid per-user Jira DC access token, refreshing if necessary.
+
+ Raises JiraDcUserTokenError when no usable token is available.
+ """
+ # TODO(jira-dc-refresh-race): single-flight refreshes with SELECT FOR UPDATE
+ # or an advisory lock before exposing this token through shared account-level
+ # integrations. Some IdPs rotate refresh tokens on use, so concurrent
+ # refreshes can otherwise write a stale refresh token back to the row.
+ row = await store.get_user_oauth_tokens(
+ keycloak_user_id=keycloak_user_id,
+ workspace_id=workspace_id,
+ )
+ if row is None:
+ raise JiraDcUserTokenError(
+ 'No stored Jira DC OAuth token for this user/workspace. '
+ 'Please re-link via OpenHands Settings β†’ Integrations.'
+ )
+
+ enc_access, enc_refresh, access_exp, refresh_exp = row
+ now = int(time.time())
+
+ fresh = access_exp == 0 or access_exp > now + _ACCESS_REFRESH_BUFFER_SECONDS
+ if fresh:
+ return JiraDcUserToken(
+ SecretStr(token_manager.decrypt_text(enc_access)), access_exp
+ )
+
+ if not enc_refresh:
+ raise JiraDcUserTokenError(
+ 'Jira DC access token expired and no refresh token is stored. '
+ 'Please re-link via OpenHands Settings β†’ Integrations.'
+ )
+ if refresh_exp and refresh_exp <= now:
+ raise JiraDcUserTokenError(
+ 'Jira DC refresh token has expired. '
+ 'Please re-link via OpenHands Settings β†’ Integrations.'
+ )
+
+ refresh_token = token_manager.decrypt_text(enc_refresh)
+ async with httpx.AsyncClient(verify=httpx_verify_option(), timeout=30.0) as client:
+ response = await client.post(
+ JIRA_DC_TOKEN_URL,
+ data={
+ 'grant_type': 'refresh_token',
+ 'client_id': JIRA_DC_CLIENT_ID,
+ 'client_secret': JIRA_DC_CLIENT_SECRET,
+ 'refresh_token': refresh_token,
+ },
+ )
+ if response.status_code != 200:
+ logger.warning(
+ '[Jira DC] Token refresh failed: %s %s',
+ response.status_code,
+ response.text[:200],
+ )
+ raise JiraDcUserTokenError(
+ 'Jira DC token refresh failed. '
+ 'Please re-link via OpenHands Settings β†’ Integrations.'
+ )
+ data = response.json()
+
+ new_access = data.get('access_token')
+ if not new_access:
+ raise JiraDcUserTokenError(
+ 'Jira DC token refresh returned no access_token. '
+ 'Please re-link via OpenHands Settings β†’ Integrations.'
+ )
+ # Some IdPs rotate the refresh token on each use; fall back to the existing one.
+ new_refresh = data.get('refresh_token') or refresh_token
+ new_expires_in = int(data.get('expires_in') or 0)
+ new_refresh_expires_in = int(
+ data.get('refresh_token_expires_in') or data.get('refresh_expires_in') or 0
+ )
+ ts = int(time.time())
+ new_access_exp = (ts + new_expires_in) if new_expires_in else 0
+ new_refresh_exp = (ts + new_refresh_expires_in) if new_refresh_expires_in else 0
+
+ updated_count = await store.update_user_oauth_tokens(
+ keycloak_user_id=keycloak_user_id,
+ workspace_id=workspace_id,
+ encrypted_access_token=token_manager.encrypt_text(new_access),
+ encrypted_refresh_token=token_manager.encrypt_text(new_refresh),
+ access_token_expires_at=new_access_exp,
+ refresh_token_expires_at=new_refresh_exp,
+ )
+ if updated_count == 0:
+ raise JiraDcUserTokenError(
+ 'Stored Jira DC OAuth link was not found while refreshing tokens. '
+ 'Please re-link via OpenHands Settings β†’ Integrations.'
+ )
+ return JiraDcUserToken(SecretStr(new_access), new_access_exp)
diff --git a/enterprise/integrations/jira_dc/jira_dc_view.py b/enterprise/integrations/jira_dc/jira_dc_view.py
index 4796feacb4..2944458f59 100644
--- a/enterprise/integrations/jira_dc/jira_dc_view.py
+++ b/enterprise/integrations/jira_dc/jira_dc_view.py
@@ -12,12 +12,18 @@ from integrations.jira_dc.jira_dc_types import (
JiraDcViewInterface,
StartingConvoException,
)
+from integrations.jira_dc.jira_dc_user_token import (
+ get_user_jira_dc_token,
+)
from integrations.jira_dc.jira_dc_v1_callback_processor import JiraDcV1CallbackProcessor
from integrations.models import JobContext
from integrations.resolver_context import ResolverUserContext
from integrations.resolver_org_router import resolve_org_for_repo
from integrations.utils import CONVERSATION_URL
from jinja2 import Environment
+from pydantic import SecretStr
+from server.auth.constants import JIRA_DC_ENABLE_OAUTH
+from server.auth.token_manager import TokenManager
from storage.jira_dc_conversation import JiraDcConversation
from storage.jira_dc_integration_store import JiraDcIntegrationStore
from storage.jira_dc_user import JiraDcUser
@@ -57,7 +63,9 @@ class JiraDcNewConversationView(JiraDcViewInterface):
async def _get_instructions(self, jinja_env: Environment) -> tuple[str, str]:
"""Instructions passed when conversation is first initialized."""
instructions_template = jinja_env.get_template('jira_dc_instructions.j2')
- instructions = instructions_template.render()
+ instructions = instructions_template.render(
+ jira_dc_oauth_enabled=JIRA_DC_ENABLE_OAUTH
+ )
user_msg_template = jinja_env.get_template('jira_dc_new_conversation.j2')
@@ -121,6 +129,29 @@ class JiraDcNewConversationView(JiraDcViewInterface):
injector_state = InjectorState()
+ sandbox_secrets: dict[str, SecretStr] = {}
+ if JIRA_DC_ENABLE_OAUTH:
+ # Resolve per-user OAuth token and inject into sandbox environment.
+ # JiraDcUserTokenError is intentionally not caught here β€” it propagates
+ # to start_job which posts a re-link comment on the Jira issue.
+ # TODO(jira-dc-account-token): move Jira credentials to the shared
+ # account-level integration capability path and use LookupSecret so
+ # non-Jira triggers can resolve the freshest token without copying
+ # this resolver-scoped StaticSecret pattern.
+ token_manager = TokenManager()
+ user_token = await get_user_jira_dc_token(
+ keycloak_user_id=self.jira_dc_user.keycloak_user_id,
+ workspace_id=self.jira_dc_workspace.id,
+ token_manager=token_manager,
+ store=integration_store,
+ )
+ sandbox_secrets['JIRA_DC_TOKEN'] = SecretStr(
+ user_token.access_token.get_secret_value()
+ )
+ sandbox_secrets['JIRA_DC_BASE_URL'] = SecretStr(
+ self.job_context.base_api_url
+ )
+
# Create the V1 conversation start request
start_request = AppConversationStartRequest(
conversation_id=UUID(self.conversation_id),
@@ -132,6 +163,7 @@ class JiraDcNewConversationView(JiraDcViewInterface):
title=f'Jira DC Issue {self.job_context.issue_key}: {self.job_context.issue_title or "Unknown"}',
trigger=ConversationTrigger.JIRA,
processors=[jira_dc_callback_processor],
+ secrets=sandbox_secrets,
)
# Set up the Jira DC user context for the V1 system
diff --git a/enterprise/integrations/utils.py b/enterprise/integrations/utils.py
index 1a363fa051..edae4bdc4e 100644
--- a/enterprise/integrations/utils.py
+++ b/enterprise/integrations/utils.py
@@ -83,6 +83,26 @@ def get_account_not_linked_message(username: str | None = None) -> str:
return f"You have an OpenHands account but haven't linked it to this workspace yet. Please link it at [OpenHands Cloud]({HOST_URL}) under Settings > Integrations and try again."
+def get_jira_dc_relink_message(display_name: str | None = None) -> str:
+ """Get a message asking the user to re-link their Jira DC workspace.
+
+ Surfaced when the stored OAuth tokens are missing, expired, or fail to
+ refresh β€” meaning the conversation cannot be started with per-user credentials.
+
+ Args:
+ display_name: Optional Jira display name to personalise the message.
+
+ Returns:
+ A formatted re-link message in Jira Wiki Markup.
+ """
+ greeting = f'Hi {display_name}, ' if display_name else ''
+ return (
+ f'{greeting}your Jira workspace link has expired or is not yet set up. '
+ f'Please re-link in [OpenHands Cloud|{HOST_URL}] under '
+ f'Settings β†’ Integrations to continue using OpenHands from Jira.'
+ )
+
+
OPENHANDS_RESOLVER_TEMPLATES_DIR = (
os.getenv('OPENHANDS_RESOLVER_TEMPLATES_DIR')
or 'openhands/app_server/integrations/templates/resolver/'
diff --git a/enterprise/migrations/versions/122_add_oauth_tokens_to_jira_dc_users.py b/enterprise/migrations/versions/122_add_oauth_tokens_to_jira_dc_users.py
new file mode 100644
index 0000000000..6901e80e9b
--- /dev/null
+++ b/enterprise/migrations/versions/122_add_oauth_tokens_to_jira_dc_users.py
@@ -0,0 +1,48 @@
+"""Add OAuth token columns to jira_dc_users.
+
+Revision ID: 122
+Revises: 121
+Create Date: 2025-05-31
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = '122'
+down_revision: Union[str, None] = '121'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+TABLE_NAME = 'jira_dc_users'
+
+
+def _token_columns() -> tuple[sa.Column, ...]:
+ return (
+ sa.Column('oauth_access_token_encrypted', sa.String(), nullable=True),
+ sa.Column('oauth_refresh_token_encrypted', sa.String(), nullable=True),
+ # Epoch seconds; 0 = unknown / no expiry info supplied by the IdP.
+ sa.Column('oauth_access_token_expires_at', sa.BigInteger(), nullable=True),
+ sa.Column('oauth_refresh_token_expires_at', sa.BigInteger(), nullable=True),
+ )
+
+
+def _existing_columns() -> set[str]:
+ bind = op.get_bind()
+ inspector = sa.inspect(bind)
+ return {column['name'] for column in inspector.get_columns(TABLE_NAME)}
+
+
+def upgrade() -> None:
+ existing = _existing_columns()
+ for column in _token_columns():
+ if column.name not in existing:
+ op.add_column(TABLE_NAME, column)
+
+
+def downgrade() -> None:
+ existing = _existing_columns()
+ for column in reversed(_token_columns()):
+ if column.name in existing:
+ op.drop_column(TABLE_NAME, column.name)
diff --git a/enterprise/server/routes/integration/jira_dc.py b/enterprise/server/routes/integration/jira_dc.py
index 5b2862a100..6bce9f00f4 100644
--- a/enterprise/server/routes/integration/jira_dc.py
+++ b/enterprise/server/routes/integration/jira_dc.py
@@ -2,6 +2,7 @@ import json
import os
import re
import secrets
+import time
import uuid
from typing import cast
from urllib.parse import urlencode, urlparse
@@ -191,11 +192,26 @@ def _jira_dc_events_url(workspace_id: int) -> str:
return f'https://{WEB_HOST}/integration/jira-dc/connections/{workspace_id}/events'
+def _configured_jira_dc_workspace_name() -> str | None:
+ if not JIRA_DC_ENABLE_OAUTH:
+ # Legacy email-match mode is not pinned to the KOTS-configured OAuth host.
+ return None
+ return urlparse(JIRA_DC_BASE_URL).hostname
+
+
+def _workspace_matches_configured_jira_dc_host(workspace_name: str) -> bool:
+ configured_workspace = _configured_jira_dc_workspace_name()
+ if not configured_workspace:
+ return True
+ return workspace_name.lower() == configured_workspace.lower()
+
+
async def _handle_workspace_link_creation(
user_id: str,
jira_dc_user_id: str,
target_workspace: str,
require_active_workspace: bool = True,
+ replace_stale_active_link: bool = False,
):
"""Handle the creation or reactivation of a workspace link for a user."""
# Verify workspace exists and is active
@@ -214,6 +230,11 @@ async def _handle_workspace_link_creation(
detail=f'Workspace "{target_workspace}" is not active',
)
+ if replace_stale_active_link:
+ await jira_dc_manager.integration_store.deactivate_user_links_except_workspace(
+ user_id, workspace.id
+ )
+
# Check if user currently has an active workspace link
existing_user = (
await jira_dc_manager.integration_store.get_user_by_active_workspace(user_id)
@@ -820,6 +841,17 @@ async def jira_dc_callback(request: Request, code: str, state: str):
token_data = response.json()
access_token = token_data['access_token']
+ refresh_token: str | None = token_data.get('refresh_token') or None
+ now = int(time.time())
+ expires_in = int(token_data.get('expires_in') or 0)
+ refresh_expires_in = int(
+ token_data.get('refresh_token_expires_in')
+ or token_data.get('refresh_expires_in')
+ or 0
+ )
+ access_token_expires_at = (now + expires_in) if expires_in else 0
+ refresh_token_expires_at = (now + refresh_expires_in) if refresh_expires_in else 0
+
headers = {'Authorization': f'Bearer {access_token}'}
target_workspace = integration_session.get('target_workspace')
@@ -867,7 +899,10 @@ async def jira_dc_callback(request: Request, code: str, state: str):
# Create a workspace link for the user (admin automatically gets linked)
if integration_session['is_active']:
await _handle_workspace_link_creation(
- user_id, jira_dc_user_id, target_workspace
+ user_id,
+ jira_dc_user_id,
+ target_workspace,
+ replace_stale_active_link=True,
)
else:
await _handle_workspace_link_creation(
@@ -875,6 +910,7 @@ async def jira_dc_callback(request: Request, code: str, state: str):
jira_dc_user_id,
target_workspace,
require_active_workspace=False,
+ replace_stale_active_link=True,
)
else:
# Workspace exists - validate user can update it
@@ -902,7 +938,10 @@ async def jira_dc_callback(request: Request, code: str, state: str):
if integration_session['is_active']:
await _handle_workspace_link_creation(
- user_id, jira_dc_user_id, target_workspace
+ user_id,
+ jira_dc_user_id,
+ target_workspace,
+ replace_stale_active_link=True,
)
else:
await _handle_workspace_link_creation(
@@ -910,6 +949,7 @@ async def jira_dc_callback(request: Request, code: str, state: str):
jira_dc_user_id,
target_workspace,
require_active_workspace=False,
+ replace_stale_active_link=True,
)
webhook_enrolled = await _maybe_register_webhook(
@@ -924,6 +964,17 @@ async def jira_dc_callback(request: Request, code: str, state: str):
status='inactive',
)
+ await jira_dc_manager.integration_store.update_user_oauth_tokens(
+ keycloak_user_id=user_id,
+ workspace_id=workspace.id,
+ encrypted_access_token=token_manager.encrypt_text(access_token),
+ encrypted_refresh_token=(
+ token_manager.encrypt_text(refresh_token) if refresh_token else None
+ ),
+ access_token_expires_at=access_token_expires_at,
+ refresh_token_expires_at=refresh_token_expires_at,
+ )
+
redirect_url = '/settings/integrations'
if integration_session.get('admin_api_key') and not webhook_enrolled:
redirect_url += '?jira_dc_webhook=install_failed'
@@ -936,8 +987,27 @@ async def jira_dc_callback(request: Request, code: str, state: str):
)
elif integration_session.get('operation_type') == 'workspace_link':
await _handle_workspace_link_creation(
- user_id, jira_dc_user_id, target_workspace
+ user_id,
+ jira_dc_user_id,
+ target_workspace,
+ replace_stale_active_link=True,
)
+
+ workspace = await jira_dc_manager.integration_store.get_workspace_by_name(
+ target_workspace
+ )
+ if workspace:
+ await jira_dc_manager.integration_store.update_user_oauth_tokens(
+ keycloak_user_id=user_id,
+ workspace_id=workspace.id,
+ encrypted_access_token=token_manager.encrypt_text(access_token),
+ encrypted_refresh_token=(
+ token_manager.encrypt_text(refresh_token) if refresh_token else None
+ ),
+ access_token_expires_at=access_token_expires_at,
+ refresh_token_expires_at=refresh_token_expires_at,
+ )
+
return RedirectResponse(
url='/settings/integrations', status_code=status.HTTP_302_FOUND
)
@@ -978,6 +1048,11 @@ async def get_current_workspace_link(request: Request):
status_code=status.HTTP_404_NOT_FOUND,
detail='Workspace not found for the user',
)
+ if not _workspace_matches_configured_jira_dc_host(workspace.name):
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail='User is not registered for the configured Jira DC integration',
+ )
return JiraDcUserResponse(
id=user.id,
diff --git a/enterprise/storage/jira_dc_integration_store.py b/enterprise/storage/jira_dc_integration_store.py
index 6a9afbf9a3..9e5ef1495d 100644
--- a/enterprise/storage/jira_dc_integration_store.py
+++ b/enterprise/storage/jira_dc_integration_store.py
@@ -4,7 +4,7 @@ from dataclasses import dataclass
from typing import Optional
from uuid import UUID
-from sqlalchemy import select
+from sqlalchemy import select, update
from storage.database import a_session_maker
from storage.jira_dc_conversation import JiraDcConversation
from storage.jira_dc_user import JiraDcUser
@@ -207,6 +207,31 @@ class JiraDcIntegrationStore:
logger.info(f'[Jira DC] Updated user {keycloak_user_id} status to {status}')
return user
+ async def deactivate_user_links_except_workspace(
+ self, keycloak_user_id: str, jira_dc_workspace_id: int
+ ) -> int:
+ """Deactivate active Jira DC links for this user except the target workspace."""
+ async with a_session_maker() as session:
+ result = await session.execute(
+ update(JiraDcUser)
+ .where(
+ JiraDcUser.keycloak_user_id == keycloak_user_id,
+ JiraDcUser.jira_dc_workspace_id != jira_dc_workspace_id,
+ JiraDcUser.status == 'active',
+ )
+ .values(status='inactive')
+ )
+ await session.commit()
+
+ deactivated_count = result.rowcount or 0
+ if deactivated_count:
+ logger.info(
+ '[Jira DC] Deactivated %s stale active user links for user %s',
+ deactivated_count,
+ keycloak_user_id,
+ )
+ return deactivated_count
+
async def deactivate_workspace(self, workspace_id: int):
"""Deactivate the workspace and all user links for a given workspace."""
async with a_session_maker() as session:
@@ -236,6 +261,60 @@ class JiraDcIntegrationStore:
f'[Jira DC] Deactivated all user links for workspace {workspace_id}'
)
+ async def update_user_oauth_tokens(
+ self,
+ *,
+ keycloak_user_id: str,
+ workspace_id: int,
+ encrypted_access_token: str,
+ encrypted_refresh_token: str | None,
+ access_token_expires_at: int,
+ refresh_token_expires_at: int,
+ ) -> int:
+ """Persist updated OAuth tokens on the user's active workspace link."""
+ async with a_session_maker() as session:
+ async with session.begin():
+ result = await session.execute(
+ update(JiraDcUser)
+ .where(
+ JiraDcUser.keycloak_user_id == keycloak_user_id,
+ JiraDcUser.jira_dc_workspace_id == workspace_id,
+ JiraDcUser.status == 'active',
+ )
+ .values(
+ oauth_access_token_encrypted=encrypted_access_token,
+ oauth_refresh_token_encrypted=encrypted_refresh_token,
+ oauth_access_token_expires_at=access_token_expires_at,
+ oauth_refresh_token_expires_at=refresh_token_expires_at,
+ )
+ )
+ return result.rowcount or 0
+
+ async def get_user_oauth_tokens(
+ self,
+ *,
+ keycloak_user_id: str,
+ workspace_id: int,
+ ) -> tuple[str, str | None, int, int] | None:
+ """Return (enc_access, enc_refresh, access_expires_at, refresh_expires_at) or None."""
+ async with a_session_maker() as session:
+ result = await session.execute(
+ select(JiraDcUser).where(
+ JiraDcUser.keycloak_user_id == keycloak_user_id,
+ JiraDcUser.jira_dc_workspace_id == workspace_id,
+ JiraDcUser.status == 'active',
+ )
+ )
+ row = result.scalar_one_or_none()
+ if not row or not row.oauth_access_token_encrypted:
+ return None
+ return (
+ row.oauth_access_token_encrypted,
+ row.oauth_refresh_token_encrypted,
+ row.oauth_access_token_expires_at or 0,
+ row.oauth_refresh_token_expires_at or 0,
+ )
+
async def create_conversation(
self, jira_dc_conversation: JiraDcConversation
) -> None:
diff --git a/enterprise/storage/jira_dc_user.py b/enterprise/storage/jira_dc_user.py
index df5966a57f..4eb3d1864b 100644
--- a/enterprise/storage/jira_dc_user.py
+++ b/enterprise/storage/jira_dc_user.py
@@ -1,6 +1,6 @@
from datetime import datetime
-from sqlalchemy import DateTime, Index, String, text
+from sqlalchemy import BigInteger, DateTime, Index, String, text
from sqlalchemy.orm import Mapped, mapped_column
from storage.base import Base
@@ -22,6 +22,19 @@ class JiraDcUser(Base):
jira_dc_user_id: Mapped[str] = mapped_column(String, nullable=False, index=True)
jira_dc_workspace_id: Mapped[int] = mapped_column(nullable=False, index=True)
status: Mapped[str] = mapped_column(String, nullable=False)
+ oauth_access_token_encrypted: Mapped[str | None] = mapped_column(
+ String, nullable=True
+ )
+ oauth_refresh_token_encrypted: Mapped[str | None] = mapped_column(
+ String, nullable=True
+ )
+ # Epoch seconds; 0 = unknown / no expiry info supplied by the IdP.
+ oauth_access_token_expires_at: Mapped[int | None] = mapped_column(
+ BigInteger, nullable=True
+ )
+ oauth_refresh_token_expires_at: Mapped[int | None] = mapped_column(
+ BigInteger, nullable=True
+ )
created_at: Mapped[datetime] = mapped_column(
DateTime,
server_default=text('CURRENT_TIMESTAMP'),
diff --git a/enterprise/tests/unit/integrations/jira_dc/test_jira_dc_user_token.py b/enterprise/tests/unit/integrations/jira_dc/test_jira_dc_user_token.py
new file mode 100644
index 0000000000..ec9ead589a
--- /dev/null
+++ b/enterprise/tests/unit/integrations/jira_dc/test_jira_dc_user_token.py
@@ -0,0 +1,318 @@
+"""Unit tests for jira_dc_user_token β€” token resolution and refresh logic."""
+
+import time
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from integrations.jira_dc.jira_dc_user_token import (
+ JiraDcUserToken,
+ JiraDcUserTokenError,
+ get_user_jira_dc_token,
+)
+from pydantic import SecretStr
+
+
+def _make_store(row):
+ store = MagicMock()
+ store.get_user_oauth_tokens = AsyncMock(return_value=row)
+ store.update_user_oauth_tokens = AsyncMock(return_value=1)
+ return store
+
+
+def _make_token_manager(decrypt_side_effect=None, decrypt_return=None):
+ tm = MagicMock()
+ if decrypt_side_effect:
+ tm.decrypt_text.side_effect = decrypt_side_effect
+ else:
+ tm.decrypt_text.return_value = decrypt_return or 'decrypted'
+ tm.encrypt_text.side_effect = lambda v: f'enc({v})'
+ return tm
+
+
+# ---------------------------------------------------------------------------
+# Fast path β€” access token is still fresh
+# ---------------------------------------------------------------------------
+
+
+async def test_fresh_access_token_returned_without_refresh():
+ future_exp = int(time.time()) + 3600
+ store = _make_store(('enc_access', 'enc_refresh', future_exp, 0))
+ tm = _make_token_manager(decrypt_return='raw_access')
+
+ result = await get_user_jira_dc_token(
+ keycloak_user_id='kc1',
+ workspace_id=1,
+ token_manager=tm,
+ store=store,
+ )
+
+ assert isinstance(result, JiraDcUserToken)
+ assert isinstance(result.access_token, SecretStr)
+ assert result.access_token.get_secret_value() == 'raw_access'
+ assert result.expires_at == future_exp
+ store.update_user_oauth_tokens.assert_not_called()
+
+
+async def test_unknown_expiry_treated_as_fresh():
+ """expires_at == 0 means we don't know; treat as fresh."""
+ store = _make_store(('enc_access', None, 0, 0))
+ tm = _make_token_manager(decrypt_return='raw_access')
+
+ result = await get_user_jira_dc_token(
+ keycloak_user_id='kc1',
+ workspace_id=1,
+ token_manager=tm,
+ store=store,
+ )
+
+ assert result.access_token.get_secret_value() == 'raw_access'
+ store.update_user_oauth_tokens.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# No stored tokens β†’ error
+# ---------------------------------------------------------------------------
+
+
+async def test_raises_when_no_stored_tokens():
+ store = _make_store(None)
+ tm = _make_token_manager()
+
+ with pytest.raises(JiraDcUserTokenError, match='No stored'):
+ await get_user_jira_dc_token(
+ keycloak_user_id='kc1',
+ workspace_id=1,
+ token_manager=tm,
+ store=store,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Expired access token, no refresh token β†’ error
+# ---------------------------------------------------------------------------
+
+
+async def test_raises_when_expired_and_no_refresh_token():
+ expired = int(time.time()) - 100
+ store = _make_store(('enc_access', None, expired, 0))
+ tm = _make_token_manager()
+
+ with pytest.raises(JiraDcUserTokenError, match='no refresh token'):
+ await get_user_jira_dc_token(
+ keycloak_user_id='kc1',
+ workspace_id=1,
+ token_manager=tm,
+ store=store,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Expired access token, refresh token also expired β†’ error
+# ---------------------------------------------------------------------------
+
+
+async def test_raises_when_refresh_token_expired():
+ expired = int(time.time()) - 100
+ store = _make_store(('enc_access', 'enc_refresh', expired, expired))
+ tm = _make_token_manager()
+
+ with pytest.raises(JiraDcUserTokenError, match='refresh token has expired'):
+ await get_user_jira_dc_token(
+ keycloak_user_id='kc1',
+ workspace_id=1,
+ token_manager=tm,
+ store=store,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Successful refresh
+# ---------------------------------------------------------------------------
+
+
+async def test_refresh_path_updates_store_and_returns_new_token():
+ expired = int(time.time()) - 100
+ future_refresh = int(time.time()) + 86400
+ store = _make_store(('enc_access', 'enc_refresh', expired, future_refresh))
+
+ decrypt_map = {'enc_access': 'old_access', 'enc_refresh': 'old_refresh'}
+ tm = _make_token_manager(decrypt_side_effect=lambda v: decrypt_map[v])
+
+ new_token_data = {
+ 'access_token': 'new_access',
+ 'refresh_token': 'new_refresh',
+ 'expires_in': 3600,
+ 'refresh_token_expires_in': 86400,
+ }
+
+ mock_response = MagicMock()
+ mock_response.status_code = 200
+ mock_response.json.return_value = new_token_data
+
+ mock_client = AsyncMock()
+ mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+ mock_client.__aexit__ = AsyncMock(return_value=False)
+ mock_client.post = AsyncMock(return_value=mock_response)
+
+ with patch(
+ 'integrations.jira_dc.jira_dc_user_token.httpx.AsyncClient',
+ return_value=mock_client,
+ ):
+ result = await get_user_jira_dc_token(
+ keycloak_user_id='kc1',
+ workspace_id=1,
+ token_manager=tm,
+ store=store,
+ )
+
+ assert result.access_token.get_secret_value() == 'new_access'
+ store.update_user_oauth_tokens.assert_awaited_once()
+ call_kwargs = store.update_user_oauth_tokens.call_args.kwargs
+ assert call_kwargs['encrypted_access_token'] == 'enc(new_access)'
+ assert call_kwargs['encrypted_refresh_token'] == 'enc(new_refresh)'
+ assert call_kwargs['access_token_expires_at'] > 0
+ assert call_kwargs['refresh_token_expires_at'] > 0
+
+
+async def test_refresh_uses_existing_refresh_token_when_idp_does_not_rotate():
+ """When the IdP doesn't return a new refresh_token, keep the old one."""
+ expired = int(time.time()) - 100
+ future_refresh = int(time.time()) + 86400
+ store = _make_store(('enc_access', 'enc_refresh', expired, future_refresh))
+
+ decrypt_map = {'enc_access': 'old_access', 'enc_refresh': 'old_refresh'}
+ tm = _make_token_manager(decrypt_side_effect=lambda v: decrypt_map[v])
+
+ # IdP omits refresh_token in the response
+ new_token_data = {'access_token': 'new_access', 'expires_in': 3600}
+
+ mock_response = MagicMock()
+ mock_response.status_code = 200
+ mock_response.json.return_value = new_token_data
+
+ mock_client = AsyncMock()
+ mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+ mock_client.__aexit__ = AsyncMock(return_value=False)
+ mock_client.post = AsyncMock(return_value=mock_response)
+
+ with patch(
+ 'integrations.jira_dc.jira_dc_user_token.httpx.AsyncClient',
+ return_value=mock_client,
+ ):
+ result = await get_user_jira_dc_token(
+ keycloak_user_id='kc1',
+ workspace_id=1,
+ token_manager=tm,
+ store=store,
+ )
+
+ assert result.access_token.get_secret_value() == 'new_access'
+ call_kwargs = store.update_user_oauth_tokens.call_args.kwargs
+ # Refresh token should be the original one re-encrypted
+ assert call_kwargs['encrypted_refresh_token'] == 'enc(old_refresh)'
+
+
+# ---------------------------------------------------------------------------
+# Refresh HTTP failure β†’ error
+# ---------------------------------------------------------------------------
+
+
+async def test_raises_when_refresh_request_fails():
+ expired = int(time.time()) - 100
+ future_refresh = int(time.time()) + 86400
+ store = _make_store(('enc_access', 'enc_refresh', expired, future_refresh))
+ tm = _make_token_manager(decrypt_return='tok')
+
+ mock_response = MagicMock()
+ mock_response.status_code = 401
+ mock_response.text = 'Unauthorized'
+
+ mock_client = AsyncMock()
+ mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+ mock_client.__aexit__ = AsyncMock(return_value=False)
+ mock_client.post = AsyncMock(return_value=mock_response)
+
+ with patch(
+ 'integrations.jira_dc.jira_dc_user_token.httpx.AsyncClient',
+ return_value=mock_client,
+ ):
+ with pytest.raises(JiraDcUserTokenError, match='refresh failed'):
+ await get_user_jira_dc_token(
+ keycloak_user_id='kc1',
+ workspace_id=1,
+ token_manager=tm,
+ store=store,
+ )
+
+
+async def test_raises_when_refresh_response_has_no_access_token():
+ expired = int(time.time()) - 100
+ future_refresh = int(time.time()) + 86400
+ store = _make_store(('enc_access', 'enc_refresh', expired, future_refresh))
+
+ decrypt_map = {'enc_access': 'old_access', 'enc_refresh': 'old_refresh'}
+ tm = _make_token_manager(decrypt_side_effect=lambda v: decrypt_map[v])
+
+ mock_response = MagicMock()
+ mock_response.status_code = 200
+ mock_response.json.return_value = {'expires_in': 3600}
+
+ mock_client = AsyncMock()
+ mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+ mock_client.__aexit__ = AsyncMock(return_value=False)
+ mock_client.post = AsyncMock(return_value=mock_response)
+
+ with patch(
+ 'integrations.jira_dc.jira_dc_user_token.httpx.AsyncClient',
+ return_value=mock_client,
+ ):
+ with pytest.raises(JiraDcUserTokenError, match='returned no access_token'):
+ await get_user_jira_dc_token(
+ keycloak_user_id='kc1',
+ workspace_id=1,
+ token_manager=tm,
+ store=store,
+ )
+
+ store.update_user_oauth_tokens.assert_not_called()
+
+
+async def test_raises_when_refreshed_token_update_matches_no_rows():
+ expired = int(time.time()) - 100
+ future_refresh = int(time.time()) + 86400
+ store = _make_store(('enc_access', 'enc_refresh', expired, future_refresh))
+ store.update_user_oauth_tokens.return_value = 0
+
+ decrypt_map = {'enc_access': 'old_access', 'enc_refresh': 'old_refresh'}
+ tm = _make_token_manager(decrypt_side_effect=lambda v: decrypt_map[v])
+
+ mock_response = MagicMock()
+ mock_response.status_code = 200
+ mock_response.json.return_value = {'access_token': 'new_access', 'expires_in': 3600}
+
+ mock_client = AsyncMock()
+ mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+ mock_client.__aexit__ = AsyncMock(return_value=False)
+ mock_client.post = AsyncMock(return_value=mock_response)
+
+ with patch(
+ 'integrations.jira_dc.jira_dc_user_token.httpx.AsyncClient',
+ return_value=mock_client,
+ ):
+ with pytest.raises(JiraDcUserTokenError, match='link was not found'):
+ await get_user_jira_dc_token(
+ keycloak_user_id='kc1',
+ workspace_id=1,
+ token_manager=tm,
+ store=store,
+ )
diff --git a/enterprise/tests/unit/integrations/jira_dc/test_jira_dc_view.py b/enterprise/tests/unit/integrations/jira_dc/test_jira_dc_view.py
index c246945a5e..279065e6f4 100644
--- a/enterprise/tests/unit/integrations/jira_dc/test_jira_dc_view.py
+++ b/enterprise/tests/unit/integrations/jira_dc/test_jira_dc_view.py
@@ -4,11 +4,16 @@ from unittest.mock import AsyncMock, MagicMock, patch
from uuid import UUID
import pytest
+from integrations.jira_dc.jira_dc_user_token import (
+ JiraDcUserToken,
+ JiraDcUserTokenError,
+)
from integrations.jira_dc.jira_dc_view import (
JiraDcExistingConversationView,
JiraDcFactory,
JiraDcNewConversationView,
)
+from pydantic import SecretStr
from openhands.app_server.integrations.service_types import ProviderType, Repository
@@ -87,3 +92,145 @@ async def test_new_conversation_resolves_org_from_selected_repo_claim(
full_repo_name='company/repo1',
keycloak_user_id='test_keycloak_id',
)
+
+
+# ---------------------------------------------------------------------------
+# Token injection into AppConversationStartRequest
+# ---------------------------------------------------------------------------
+
+
+def _make_start_conversation_patches(user_token=None, token_error=None):
+ """Return a context-manager stack that stubs everything _create_v1_conversation touches."""
+ import contextlib
+
+ @contextlib.asynccontextmanager
+ async def _patches(view):
+ mock_token = user_token or JiraDcUserToken(
+ access_token=SecretStr('the_access_token'), expires_at=9999999999
+ )
+
+ mock_app_conversation_service = AsyncMock()
+ mock_app_conversation_service.start_app_conversation = AsyncMock(
+ return_value=aiter([])
+ )
+
+ with (
+ patch(
+ 'integrations.jira_dc.jira_dc_view.get_user_jira_dc_token',
+ new=AsyncMock(
+ return_value=mock_token,
+ side_effect=token_error,
+ ),
+ ),
+ patch('integrations.jira_dc.jira_dc_view.TokenManager'),
+ patch('integrations.jira_dc.jira_dc_view.integration_store'),
+ patch(
+ 'integrations.jira_dc.jira_dc_view.resolve_org_for_repo',
+ new=AsyncMock(return_value=None),
+ ),
+ patch('integrations.jira_dc.jira_dc_view.ProviderHandler'),
+ patch(
+ 'integrations.jira_dc.jira_dc_view.get_app_conversation_service',
+ ) as mock_svc_ctx,
+ ):
+ mock_svc_ctx.return_value.__aenter__ = AsyncMock(
+ return_value=mock_app_conversation_service
+ )
+ mock_svc_ctx.return_value.__aexit__ = AsyncMock(return_value=False)
+ yield mock_app_conversation_service
+
+ return _patches
+
+
+async def aiter(iterable):
+ for item in iterable:
+ yield item
+
+
+async def test_create_v1_conversation_injects_jira_dc_token(
+ new_conversation_view, mock_jinja_env
+):
+ """start_request.secrets must contain JIRA_DC_TOKEN and JIRA_DC_BASE_URL."""
+ new_conversation_view.conversation_id = 'a1b2c3d4e5f64a5b8c9d0e1f2a3b4c5d'
+ captured_requests = []
+
+ async def _fake_start(req):
+ captured_requests.append(req)
+ return
+ yield # make it an async generator
+
+ async with _make_start_conversation_patches()(new_conversation_view) as mock_svc:
+ mock_svc.start_app_conversation = _fake_start
+ await new_conversation_view._create_v1_conversation(mock_jinja_env)
+
+ assert len(captured_requests) == 1
+ req = captured_requests[0]
+ assert req.secrets is not None
+ assert 'JIRA_DC_TOKEN' in req.secrets
+ assert req.secrets['JIRA_DC_TOKEN'].get_secret_value() == 'the_access_token'
+ assert 'JIRA_DC_BASE_URL' in req.secrets
+ assert (
+ req.secrets['JIRA_DC_BASE_URL'].get_secret_value()
+ == new_conversation_view.job_context.base_api_url
+ )
+
+
+async def test_create_v1_conversation_skips_jira_dc_token_when_oauth_disabled(
+ new_conversation_view, mock_jinja_env
+):
+ """Legacy email-match mode must not require per-user OAuth tokens."""
+ new_conversation_view.conversation_id = 'a1b2c3d4e5f64a5b8c9d0e1f2a3b4c5d'
+ captured_requests = []
+
+ async def _fake_start(req):
+ captured_requests.append(req)
+ return
+ yield # make it an async generator
+
+ mock_app_conversation_service = AsyncMock()
+ mock_app_conversation_service.start_app_conversation = _fake_start
+ get_token = AsyncMock()
+
+ with (
+ patch('integrations.jira_dc.jira_dc_view.JIRA_DC_ENABLE_OAUTH', False),
+ patch('integrations.jira_dc.jira_dc_view.get_user_jira_dc_token', get_token),
+ patch('integrations.jira_dc.jira_dc_view.TokenManager'),
+ patch('integrations.jira_dc.jira_dc_view.integration_store'),
+ patch(
+ 'integrations.jira_dc.jira_dc_view.resolve_org_for_repo',
+ new=AsyncMock(return_value=None),
+ ),
+ patch('integrations.jira_dc.jira_dc_view.ProviderHandler'),
+ patch(
+ 'integrations.jira_dc.jira_dc_view.get_app_conversation_service',
+ ) as mock_svc_ctx,
+ ):
+ mock_svc_ctx.return_value.__aenter__ = AsyncMock(
+ return_value=mock_app_conversation_service
+ )
+ mock_svc_ctx.return_value.__aexit__ = AsyncMock(return_value=False)
+
+ await new_conversation_view._create_v1_conversation(mock_jinja_env)
+
+ get_token.assert_not_called()
+ assert len(captured_requests) == 1
+ assert captured_requests[0].secrets == {}
+
+
+async def test_create_v1_conversation_propagates_token_error(
+ new_conversation_view, mock_jinja_env
+):
+ """JiraDcUserTokenError must propagate so start_job can post a re-link comment."""
+ with (
+ patch(
+ 'integrations.jira_dc.jira_dc_view.get_user_jira_dc_token',
+ new=AsyncMock(side_effect=JiraDcUserTokenError('no token')),
+ ),
+ patch('integrations.jira_dc.jira_dc_view.TokenManager'),
+ patch('integrations.jira_dc.jira_dc_view.integration_store'),
+ ):
+ with pytest.raises(JiraDcUserTokenError):
+ await new_conversation_view._create_v1_conversation(mock_jinja_env)
diff --git a/enterprise/tests/unit/integrations/test_utils.py b/enterprise/tests/unit/integrations/test_utils.py
index 0ab9c85dc1..ed463a8222 100644
--- a/enterprise/tests/unit/integrations/test_utils.py
+++ b/enterprise/tests/unit/integrations/test_utils.py
@@ -2,6 +2,7 @@
from integrations.utils import (
HOST_URL,
+ get_jira_dc_relink_message,
get_session_expired_message,
get_user_not_found_message,
)
@@ -133,3 +134,23 @@ class TestGetUserNotFoundMessage:
result = get_user_not_found_message(None)
assert not result.startswith('@')
assert 'It looks like' in result
+
+
+class TestGetJiraDcRelinkMessage:
+ """Test cases for get_jira_dc_relink_message function."""
+
+ def test_message_with_display_name_uses_jira_wiki_link(self):
+ result = get_jira_dc_relink_message('Alona')
+
+ assert result.startswith('Hi Alona,')
+ assert f'[OpenHands Cloud|{HOST_URL}]' in result
+ assert 're-link' in result
+ assert 'Settings' in result
+ assert 'Integrations' in result
+
+ def test_message_without_display_name_is_generic(self):
+ result = get_jira_dc_relink_message()
+
+ assert not result.startswith('Hi ')
+ assert f'[OpenHands Cloud|{HOST_URL}]' in result
+ assert 'your Jira workspace link has expired' in result
diff --git a/enterprise/tests/unit/server/routes/test_jira_dc_integration_routes.py b/enterprise/tests/unit/server/routes/test_jira_dc_integration_routes.py
index 851483a54f..1713614f95 100644
--- a/enterprise/tests/unit/server/routes/test_jira_dc_integration_routes.py
+++ b/enterprise/tests/unit/server/routes/test_jira_dc_integration_routes.py
@@ -308,7 +308,10 @@ async def test_jira_dc_callback_workspace_integration_new_workspace(
assert response.status_code == status.HTTP_302_FOUND
mock_manager.integration_store.create_workspace.assert_called_once()
mock_handle_link.assert_called_once_with(
- 'user1', 'jira_user_123', 'test.atlassian.net'
+ 'user1',
+ 'jira_user_123',
+ 'test.atlassian.net',
+ replace_stale_active_link=True,
)
@@ -373,7 +376,10 @@ async def test_jira_dc_callback_redirects_with_webhook_install_failure(
'bad-admin-pat', 'https://test.atlassian.net', 'secret', 1
)
mock_handle_link.assert_called_once_with(
- 'user1', 'jira_user_123', 'test.atlassian.net'
+ 'user1',
+ 'jira_user_123',
+ 'test.atlassian.net',
+ replace_stale_active_link=True,
)
@@ -489,6 +495,46 @@ async def test_get_current_workspace_link_found(
)
+@patch('server.routes.integration.jira_dc.get_user_auth')
+@patch('server.routes.integration.jira_dc.jira_dc_manager', new_callable=AsyncMock)
+@patch('server.routes.integration.jira_dc.JIRA_DC_ENABLE_OAUTH', True)
+@patch(
+ 'server.routes.integration.jira_dc.JIRA_DC_BASE_URL', 'https://current-jira.test'
+)
+async def test_get_current_workspace_link_ignores_stale_configured_host_link(
+ mock_manager, mock_get_auth, mock_request, mock_user_auth
+):
+ mock_get_auth.return_value = mock_user_auth
+ mock_user = MagicMock(
+ id=1,
+ keycloak_user_id='test_user_id',
+ jira_dc_workspace_id=10,
+ status='active',
+ )
+ mock_user.created_at = datetime.now()
+ mock_user.updated_at = datetime.now()
+
+ mock_workspace = MagicMock(
+ id=10,
+ status='active',
+ admin_user_id='test_user_id',
+ svc_acc_email='[email protected]',
+ )
+ mock_workspace.name = 'old-jira.test'
+ mock_workspace.created_at = datetime.now()
+ mock_workspace.updated_at = datetime.now()
+
+ mock_manager.integration_store.get_user_by_active_workspace.return_value = mock_user
+ mock_manager.integration_store.get_workspace_by_id.return_value = mock_workspace
+
+ with pytest.raises(HTTPException) as exc_info:
+ await get_current_workspace_link(mock_request)
+
+ assert exc_info.value.status_code == 404
+ assert 'configured Jira DC integration' in exc_info.value.detail
+
+
@pytest.mark.asyncio
@patch('server.routes.integration.jira_dc.get_user_auth')
@patch('server.routes.integration.jira_dc.jira_dc_manager', new_callable=AsyncMock)
@@ -1402,7 +1448,10 @@ async def test_jira_dc_callback_workspace_integration_existing_workspace(
assert response.status_code == status.HTTP_302_FOUND
mock_manager.integration_store.update_workspace.assert_called_once()
mock_handle_link.assert_called_once_with(
- 'user1', 'jira_user_123', 'existing.atlassian.net'
+ 'user1',
+ 'jira_user_123',
+ 'existing.atlassian.net',
+ replace_stale_active_link=True,
)
@@ -1734,6 +1783,34 @@ async def test_handle_workspace_link_creation_already_linked_different_workspace
assert 'You already have an active workspace link' in exc_info.value.detail
+@patch('server.routes.integration.jira_dc.jira_dc_manager', new_callable=AsyncMock)
+async def test_handle_workspace_link_creation_replaces_stale_active_link(
+ mock_manager,
+):
+ mock_workspace = MagicMock(id=2, status='active')
+
+ mock_manager.integration_store.get_workspace_by_name.return_value = mock_workspace
+ mock_manager.integration_store.get_user_by_active_workspace.return_value = None
+ mock_manager.integration_store.get_user_by_keycloak_id_and_workspace.return_value = None
+
+ await _handle_workspace_link_creation(
+ 'user1',
+ 'jira_user_123',
+ 'current-workspace',
+ replace_stale_active_link=True,
+ )
+
+ mock_manager.integration_store.deactivate_user_links_except_workspace.assert_called_once_with(
+ 'user1', 2
+ )
+ mock_manager.integration_store.create_workspace_link.assert_called_once_with(
+ keycloak_user_id='user1',
+ jira_dc_user_id='jira_user_123',
+ jira_dc_workspace_id=2,
+ )
+
+
@pytest.mark.asyncio
@patch('server.routes.integration.jira_dc.jira_dc_manager', new_callable=AsyncMock)
async def test_handle_workspace_link_creation_reactivate_existing_link(mock_manager):
@@ -1898,3 +1975,163 @@ class TestJiraDcOAuthUrlEncoding:
assert ' ' not in auth_url
# Verify redirect_uri is properly encoded
assert 'redirect_uri=https%3A%2F%2F' in auth_url
+
+
+# ---------------------------------------------------------------------------
+# Token persistence in the OAuth callback
+# ---------------------------------------------------------------------------
+
+
+@patch('server.routes.integration.jira_dc.redis_client')
+@patch('server.routes.integration.jira_dc.jira_dc_manager', new_callable=AsyncMock)
+@patch(
+ 'server.routes.integration.jira_dc._handle_workspace_link_creation',
+ new_callable=AsyncMock,
+)
+async def test_callback_workspace_integration_persists_tokens(
+ mock_handle_link, mock_manager, mock_redis, mock_request
+):
+ """workspace_integration callback must encrypt and store access + refresh tokens."""
+ state = 'test_state'
+ token_data = {
+ 'access_token': 'at',
+ 'refresh_token': 'rt',
+ 'expires_in': 3600,
+ 'refresh_token_expires_in': 86400,
+ }
+ session_data = {
+ 'operation_type': 'workspace_integration',
+ 'keycloak_user_id': 'user1',
+ 'target_workspace': 'test.atlassian.net',
+ 'webhook_secret': 'secret',
+ 'svc_acc_email': '[email protected]',
+ 'svc_acc_api_key': 'apikey',
+ 'is_active': True,
+ 'state': state,
+ }
+ mock_redis.get.return_value = json.dumps(session_data)
+ httpx_mock = create_httpx_mock(
+ post_response=token_data,
+ get_responses={
+ 'accessible-resources': [{'url': 'https://test.atlassian.net'}],
+ '/myself': {'key': 'jira_user_1'},
+ },
+ )
+ mock_workspace = MagicMock(id=5)
+ mock_manager.integration_store.get_workspace_by_name.return_value = None
+ mock_manager.integration_store.create_workspace.return_value = mock_workspace
+
+ with patch('server.routes.integration.jira_dc.token_manager') as mock_tm:
+ with patch(
+ 'server.routes.integration.jira_dc.JIRA_DC_BASE_URL',
+ 'https://test.atlassian.net',
+ ):
+ mock_tm.encrypt_text.side_effect = lambda v: f'enc({v})'
+ with patch('httpx.AsyncClient', return_value=httpx_mock):
+ await jira_dc_callback(mock_request, 'code', state)
+
+ mock_manager.integration_store.update_user_oauth_tokens.assert_awaited_once()
+ kwargs = mock_manager.integration_store.update_user_oauth_tokens.call_args.kwargs
+ assert kwargs['keycloak_user_id'] == 'user1'
+ assert kwargs['workspace_id'] == 5
+ assert kwargs['encrypted_access_token'] == 'enc(at)'
+ assert kwargs['encrypted_refresh_token'] == 'enc(rt)'
+ assert kwargs['access_token_expires_at'] > 0
+ assert kwargs['refresh_token_expires_at'] > 0
+
+
+@patch('server.routes.integration.jira_dc.redis_client')
+@patch('server.routes.integration.jira_dc.jira_dc_manager', new_callable=AsyncMock)
+@patch(
+ 'server.routes.integration.jira_dc._handle_workspace_link_creation',
+ new_callable=AsyncMock,
+)
+async def test_callback_workspace_integration_null_refresh_token_tolerated(
+ mock_handle_link, mock_manager, mock_redis, mock_request
+):
+ """Missing refresh_token in IdP response must be stored as NULL, not raise."""
+ state = 'test_state'
+ token_data = {'access_token': 'at'} # no refresh_token, no expires_in
+ session_data = {
+ 'operation_type': 'workspace_integration',
+ 'keycloak_user_id': 'user1',
+ 'target_workspace': 'test.atlassian.net',
+ 'webhook_secret': 'secret',
+ 'svc_acc_email': '[email protected]',
+ 'svc_acc_api_key': 'apikey',
+ 'is_active': True,
+ 'state': state,
+ }
+ mock_redis.get.return_value = json.dumps(session_data)
+ httpx_mock = create_httpx_mock(
+ post_response=token_data,
+ get_responses={
+ 'accessible-resources': [{'url': 'https://test.atlassian.net'}],
+ '/myself': {'key': 'jira_user_1'},
+ },
+ )
+ mock_workspace = MagicMock(id=7)
+ mock_manager.integration_store.get_workspace_by_name.return_value = None
+ mock_manager.integration_store.create_workspace.return_value = mock_workspace
+
+ with patch('server.routes.integration.jira_dc.token_manager') as mock_tm:
+ with patch(
+ 'server.routes.integration.jira_dc.JIRA_DC_BASE_URL',
+ 'https://test.atlassian.net',
+ ):
+ mock_tm.encrypt_text.side_effect = lambda v: f'enc({v})'
+ with patch('httpx.AsyncClient', return_value=httpx_mock):
+ await jira_dc_callback(mock_request, 'code', state)
+
+ kwargs = mock_manager.integration_store.update_user_oauth_tokens.call_args.kwargs
+ assert kwargs['encrypted_refresh_token'] is None
+ assert kwargs['access_token_expires_at'] == 0
+ assert kwargs['refresh_token_expires_at'] == 0
+
+
+@patch('server.routes.integration.jira_dc.redis_client')
+@patch('server.routes.integration.jira_dc.jira_dc_manager', new_callable=AsyncMock)
+@patch(
+ 'server.routes.integration.jira_dc._handle_workspace_link_creation',
+ new_callable=AsyncMock,
+)
+async def test_callback_workspace_link_persists_tokens(
+ mock_handle_link, mock_manager, mock_redis, mock_request
+):
+ """workspace_link callback must also persist tokens."""
+ state = 'test_state'
+ token_data = {'access_token': 'at', 'refresh_token': 'rt', 'expires_in': 1800}
+ session_data = {
+ 'operation_type': 'workspace_link',
+ 'keycloak_user_id': 'user2',
+ 'target_workspace': 'test.atlassian.net',
+ 'state': state,
+ }
+ mock_redis.get.return_value = json.dumps(session_data)
+ httpx_mock = create_httpx_mock(
+ post_response=token_data,
+ get_responses={
+ 'accessible-resources': [{'url': 'https://test.atlassian.net'}],
+ '/myself': {'key': 'jira_user_2'},
+ },
+ )
+ mock_workspace = MagicMock(id=9)
+ mock_manager.integration_store.get_workspace_by_name.return_value = mock_workspace
+
+ with patch('server.routes.integration.jira_dc.token_manager') as mock_tm:
+ with patch(
+ 'server.routes.integration.jira_dc.JIRA_DC_BASE_URL',
+ 'https://test.atlassian.net',
+ ):
+ mock_tm.encrypt_text.side_effect = lambda v: f'enc({v})'
+ with patch('httpx.AsyncClient', return_value=httpx_mock):
+ await jira_dc_callback(mock_request, 'code', state)
+
+ mock_manager.integration_store.update_user_oauth_tokens.assert_awaited_once()
+ kwargs = mock_manager.integration_store.update_user_oauth_tokens.call_args.kwargs
+ assert kwargs['keycloak_user_id'] == 'user2'
+ assert kwargs['workspace_id'] == 9
+ assert kwargs['encrypted_access_token'] == 'enc(at)'
diff --git a/enterprise/tests/unit/storage/test_jira_dc_active_link_constraint.py b/enterprise/tests/unit/storage/test_jira_dc_active_link_constraint.py
index 334a1dc955..baf370f172 100644
--- a/enterprise/tests/unit/storage/test_jira_dc_active_link_constraint.py
+++ b/enterprise/tests/unit/storage/test_jira_dc_active_link_constraint.py
@@ -147,3 +147,32 @@ async def test_update_user_integration_status_targets_workspace_link():
assert 'jira_dc_users.jira_dc_workspace_id' in str(executed_statement)
session.commit.assert_awaited_once()
session.refresh.assert_awaited_once_with(user)
+
+
+async def test_deactivate_user_links_except_workspace_targets_stale_active_links():
+ store = JiraDcIntegrationStore()
+
+ result = Mock()
+ result.rowcount = 2
+ session = Mock()
+ session.execute = AsyncMock(return_value=result)
+ session.commit = AsyncMock()
+
+ @asynccontextmanager
+ async def mock_session_maker():
+ yield session
+
+ with patch('storage.jira_dc_integration_store.a_session_maker', mock_session_maker):
+ deactivated_count = await store.deactivate_user_links_except_workspace(
+ 'user-1', 42
+ )
+
+ assert deactivated_count == 2
+ session.execute.assert_called_once()
+ executed_statement = session.execute.call_args.args[0]
+ statement_text = str(executed_statement)
+ assert 'jira_dc_users.keycloak_user_id' in statement_text
+ assert 'jira_dc_users.jira_dc_workspace_id !=' in statement_text
+ assert 'jira_dc_users.status' in statement_text
+ session.commit.assert_awaited_once()
diff --git a/openhands/app_server/integrations/templates/resolver/jira_dc/jira_dc_instructions.j2 b/openhands/app_server/integrations/templates/resolver/jira_dc/jira_dc_instructions.j2
index acfdcd99c5..bbe3cb9ebd 100644
--- a/openhands/app_server/integrations/templates/resolver/jira_dc/jira_dc_instructions.j2
+++ b/openhands/app_server/integrations/templates/resolver/jira_dc/jira_dc_instructions.j2
@@ -12,3 +12,29 @@ Follow these instructions carefully:
4. If the repository already contains a style guides and PR templates, respect those.
5. Write clean, maintainable code that meets the requirements outlined in the issue.
6. Ensure that your code is well-documented and adheres to the project's coding standards.
+
+{% if jira_dc_oauth_enabled %}
+You have credentialed access to the Jira Data Center REST API as the user who triggered this conversation:
+
+ - Base URL: $JIRA_DC_BASE_URL
+ - Auth: Authorization: Bearer $JIRA_DC_TOKEN
+
+The token value is supplied only as a sandbox secret/environment variable. These instructions intentionally refer to the variable name, not the secret value.
+
+Example β€” fetch an issue:
+
+ curl -fsSL -H "Authorization: Bearer $JIRA_DC_TOKEN" \
+ "$JIRA_DC_BASE_URL/rest/api/2/issue/PROJ-123"
+
+Example β€” post a comment:
+
+ curl -fsSL -X POST \
+ -H "Authorization: Bearer $JIRA_DC_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{"body": "Work in progress."}' \
+ "$JIRA_DC_BASE_URL/rest/api/2/issue/PROJ-123/comment"
+
+When posting comments or updating description fields, the body must use Jira Wiki Markup (*bold*, _italic_, {code}...{code}, # numbered lists, * bulleted lists, [text|url]), not Markdown.
+
+Never echo or log the value of $JIRA_DC_TOKEN β€” treat it as a secret.
+{% endif %}