π OpenHands: AI-Driven Development
fix: decouple API-key (Bearer) auth from Keycloak offline sessions (#14867)
Hiep Le9f03703cd37d
diff --git a/enterprise/server/auth/saas_user_auth.py b/enterprise/server/auth/saas_user_auth.pyindex 1878810453..9a0b7ee277 100644--- a/enterprise/server/auth/saas_user_auth.py+++ b/enterprise/server/auth/saas_user_auth.py@@ -5,7 +5,7 @@ from uuid import UUIDimport jwtfrom fastapi import HTTPException, Request-from keycloak.exceptions import KeycloakError+from keycloak.exceptions import KeycloakConnectionErrorfrom pydantic import SecretStrfrom server.auth.auth_error import (AuthError,@@ -277,14 +277,39 @@ class SaasUserAuth(UserAuth):return self.user_idasync def get_user_email(self) -> str | None:+ # Email lives in the local DB (User row), not only in the Keycloak+ # token. Sourcing it here lets API-key (bearer) auth β which no longer+ # refreshes against Keycloak β still resolve the email. Cookie auth+ # already has ``self.email`` set from the signed token, so the lookup+ # is skipped in that case.+ if self.email is None:+ user = await UserStore.get_user_by_id(self.user_id)+ if user:+ self.email = user.email+ self.email_verified = user.email_verifiedreturn self.email@retry(stop=stop_after_attempt(3),wait=wait_fixed(1),- retry=retry_if_exception_type(KeycloakError),+ # Only retry transient connection failures. A deterministic+ # ``invalid_grant`` (revoked/expired offline session) is a+ # ``KeycloakPostError`` and must not be retried 3x.+ retry=retry_if_exception_type(KeycloakConnectionError),)async def refresh(self):+ # API-key (bearer) auth does not carry an offline token. Load it lazily+ # here, and only when a Keycloak access token is genuinely needed, so+ # that authentication itself never depends on the offline session.+ if (+ self.auth_type == AuthType.BEARER+ and not self.refresh_token.get_secret_value()+ ):+ offline_token = await token_manager.load_offline_token(self.user_id)+ if not offline_token:+ raise ExpiredError()+ self.refresh_token = SecretStr(offline_token)+if self._is_token_expired(self.refresh_token):logger.debug('saas_user_auth_refresh:expired')raise ExpiredError()@@ -329,7 +354,9 @@ class SaasUserAuth(UserAuth):settings_store = await self.get_user_settings_store()settings = await settings_store.load()if settings:- settings.email = self.email+ # Resolve email via get_user_email() so it is populated (from the DB)+ # for bearer auth, which no longer eagerly refreshes from Keycloak.+ settings.email = await self.get_user_email()settings.email_verified = self.email_verifiedself._settings = settingsreturn settings@@ -381,8 +408,19 @@ class SaasUserAuth(UserAuth):await self.refresh()return self.access_tokenexcept AuthError:+ # A Keycloak access token requires the user's offline session. For+ # API-key (bearer) auth that session is optional: provider tokens+ # and the rest of the request context resolve independently, so a+ # missing/revoked offline session must not turn a valid key into a+ # 401. Degrade to None instead of raising.+ if self.auth_type == AuthType.BEARER:+ logger.warning('bearer_get_access_token_refresh_failed', exc_info=True)+ return Noneraiseexcept Exception as e:+ if self.auth_type == AuthType.BEARER:+ logger.warning('bearer_get_access_token_failed', exc_info=True)+ return Noneraise AuthError() from easync def get_provider_tokens(self) -> PROVIDER_TOKEN_TYPE | None:@@ -390,9 +428,6 @@ class SaasUserAuth(UserAuth):if self.provider_tokens is not None:return self.provider_tokensprovider_tokens = {}- access_token = await self.get_access_token()- if not access_token:- raise AuthError()user_secrets = await self.get_secrets()@@ -419,8 +454,12 @@ class SaasUserAuth(UserAuth):if idp_type == ProviderType.AZURE_DEVOPS and not host:host = AZURE_DEVOPS_ORGANIZATION or None- provider_token = await token_manager.get_idp_token(- access_token.get_secret_value(),+ # Resolve the provider token by user_id directly. This reads+ # the encrypted token from the auth_tokens table and refreshes+ # via the provider's OAuth endpoint β no Keycloak access+ # token / offline session required.+ provider_token = await token_manager.get_idp_token_by_user_id(+ self.user_id,idp=idp_type,)# TODO: Currently we don't store the IDP user id in our refresh table. We should.@@ -646,11 +685,13 @@ class SaasUserAuth(UserAuth):@classmethodasync def get_for_user(cls, user_id: str) -> UserAuth:- offline_token = await token_manager.load_offline_token(user_id)- assert offline_token is not None+ # Background / integration resolver contexts must not depend on the+ # user's Keycloak offline session either. The offline token (if any) is+ # loaded lazily by refresh() only when a Keycloak access token is+ # actually required; provider tokens resolve by user_id directly.return SaasUserAuth(user_id=user_id,- refresh_token=SecretStr(offline_token),+ refresh_token=SecretStr(''),auth_type=AuthType.BEARER,)@@ -681,19 +722,20 @@ async def saas_user_auth_from_bearer(request: Request) -> SaasUserAuth | None:validation_result = await api_key_store.validate_api_key(api_key)if not validation_result:return None- offline_token = await token_manager.load_offline_token(- validation_result.user_id- )- saas_user_auth = SaasUserAuth(+ # API-key auth is intentionally decoupled from the Keycloak offline+ # session: we do NOT load an offline token or refresh here. A valid API+ # key alone authenticates the request. Any provider/access token needed+ # downstream is resolved independently (see get_provider_tokens /+ # get_access_token), so a missing or revoked offline session no longer+ # turns a valid key into a 401 BearerTokenError.+ return SaasUserAuth(user_id=validation_result.user_id,- refresh_token=SecretStr(offline_token or ''),+ refresh_token=SecretStr(''),auth_type=AuthType.BEARER,api_key_org_id=validation_result.org_id,api_key_id=validation_result.key_id,api_key_name=validation_result.key_name,)- await saas_user_auth.refresh()- return saas_user_authexcept Exception as exc:raise BearerTokenError from exc@@ -757,12 +799,12 @@ async def saas_user_auth_from_signed_token(signed_token: str) -> SaasUserAuth:async def get_user_auth_from_keycloak_id(keycloak_user_id: str) -> UserAuth:- offline_token = await token_manager.load_offline_token(keycloak_user_id)- if offline_token is None:- logger.info('no_offline_token_found')-- user_auth = SaasUserAuth(+ # Like get_for_user, this is a background / integration entry point that must+ # not require the offline session. Mark it BEARER so get_access_token()+ # degrades gracefully and refresh() lazily loads the offline token only if a+ # Keycloak access token is genuinely needed.+ return SaasUserAuth(user_id=keycloak_user_id,- refresh_token=SecretStr(offline_token or ''),+ refresh_token=SecretStr(''),+ auth_type=AuthType.BEARER,)- return user_authdiff --git a/enterprise/server/auth/token_manager.py b/enterprise/server/auth/token_manager.pyindex e5b9b7a304..0db26b0dcf 100644--- a/enterprise/server/auth/token_manager.py+++ b/enterprise/server/auth/token_manager.py@@ -279,9 +279,22 @@ class TokenManager:) -> str:# Get user info to determine user_id and idpuser_info = await self.get_user_info(access_token=access_token)- user_id = user_info.sub- username = user_info.preferred_username- logger.info(f'Getting token for user {username} and IDP {idp}')+ return await self.get_idp_token_by_user_id(user_info.sub, idp)++ async def get_idp_token_by_user_id(+ self,+ user_id: str,+ idp: ProviderType,+ ) -> str:+ """Load (and refresh if needed) a provider IDP token using only the user_id.++ This path is independent of the user's Keycloak *offline session*: the+ encrypted provider tokens are read from the ``auth_tokens`` table and+ refreshed via the provider's own OAuth endpoint (see+ ``_check_expiration_and_refresh``). No Keycloak round-trip is required,+ so it keeps working after the offline session is revoked or expires.+ """+ logger.info(f'Getting token for user {user_id} and IDP {idp}')token_store = await AuthTokenStore.get_instance(keycloak_user_id=user_id, idp=idp)@@ -291,9 +304,9 @@ class TokenManager:self._check_expiration_and_refresh)if not token_info:- logger.info(f'No tokens for user: {username}, identity provider: {idp}')+ logger.info(f'No tokens for user: {user_id}, identity provider: {idp}')raise ValueError(- f'No tokens for user: {username}, identity provider: {idp}'+ f'No tokens for user: {user_id}, identity provider: {idp}')access_token = self.decrypt_text(str(token_info['access_token']))logger.info(f'Got {idp} token: {access_token[0:5]}')@@ -301,12 +314,12 @@ class TokenManager:except httpx.HTTPStatusError as e:# Log the full response details including the bodylogger.error(- f'Failed to get tokens for user {username}, identity provider {idp} from URL {e.response.url}. '+ f'Failed to get tokens for user {user_id}, identity provider {idp} from URL {e.response.url}. 'f'Status code: {e.response.status_code}, 'f'Response body: {e.response.text}')raise ValueError(- f'Failed to get token for user: {username}, identity provider: {idp}. '+ f'Failed to get token for user: {user_id}, identity provider: {idp}. 'f'Status code: {e.response.status_code}, 'f'Response body: {e.response.text}') from ediff --git a/enterprise/tests/unit/test_saas_user_auth.py b/enterprise/tests/unit/test_saas_user_auth.pyindex 3bd87db74c..64b0e12fa2 100644--- a/enterprise/tests/unit/test_saas_user_auth.py+++ b/enterprise/tests/unit/test_saas_user_auth.py@@ -15,6 +15,7 @@ from server.auth.auth_error import (from server.auth.saas_user_auth import (SaasUserAuth,get_api_key_from_header,+ get_user_auth_from_keycloak_id,saas_user_auth_from_bearer,saas_user_auth_from_cookie,saas_user_auth_from_signed_token,@@ -24,6 +25,7 @@ from storage.user_authorization import UserAuthorizationTypefrom openhands.app_server.integrations.provider import ProviderToken, ProviderTypefrom openhands.app_server.secrets.secrets_models import Secrets+from openhands.app_server.user_auth.user_auth import AuthType@pytest.fixture@@ -284,7 +286,9 @@ class TestGetProviderTokensBitbucketDCHost:'bitbucket.company.com',),):- mock_tm.get_idp_token = AsyncMock(return_value='bdc_access_token')+ mock_tm.get_idp_token_by_user_id = AsyncMock(+ return_value='bdc_access_token'+ )user_auth, mock_session = self._make_user_auth(mock_session_maker)user_auth.get_secrets = AsyncMock(return_value=None)@@ -307,7 +311,9 @@ class TestGetProviderTokensBitbucketDCHost:'bitbucket.company.com',),):- mock_tm.get_idp_token = AsyncMock(return_value='bdc_access_token')+ mock_tm.get_idp_token_by_user_id = AsyncMock(+ return_value='bdc_access_token'+ )user_auth, mock_session = self._make_user_auth(mock_session_maker)user_secrets = Secrets(provider_tokens={@@ -335,7 +341,9 @@ class TestGetProviderTokensBitbucketDCHost:patch('server.auth.saas_user_auth.a_session_maker') as mock_session_maker,patch('server.auth.saas_user_auth.BITBUCKET_DATA_CENTER_HOST', ''),):- mock_tm.get_idp_token = AsyncMock(return_value='bdc_access_token')+ mock_tm.get_idp_token_by_user_id = AsyncMock(+ return_value='bdc_access_token'+ )user_auth, mock_session = self._make_user_auth(mock_session_maker)user_auth.get_secrets = AsyncMock(return_value=None)@@ -368,6 +376,140 @@ async def test_get_provider_tokens_cached(mock_token_manager):mock_token_manager.get_idp_token.assert_not_called()+# =============================================================================+# API-key (bearer) decoupling from Keycloak offline sessions+# =============================================================================+++async def test_get_user_email_lazy_loads_from_db():+ """Bearer auth resolves email from the DB (User row), not from Keycloak."""+ # Arrange+ user_auth = SaasUserAuth(+ user_id='test_user_id',+ refresh_token=SecretStr(''),+ auth_type=AuthType.BEARER,+ )+ mock_user = MagicMock()+ mock_user.email = '[email protected]'+ mock_user.email_verified = True++ with patch('server.auth.saas_user_auth.UserStore') as mock_user_store:+ mock_user_store.get_user_by_id = AsyncMock(return_value=mock_user)++ # Act+ email = await user_auth.get_user_email()++ # Assert+ assert email == '[email protected]'+ assert user_auth.email_verified is True+++async def test_get_access_token_returns_none_for_bearer_when_session_revoked():+ """Bearer get_access_token degrades to None when the offline session is gone.++ A revoked offline session surfaces as a Keycloak refresh failure+ (``invalid_grant``). For API-key auth that must not raise a 401 β the+ Keycloak access token is optional.+ """+ # Arrange+ from keycloak.exceptions import KeycloakPostError++ offline_token = jwt.encode(+ {'sub': 'test_user_id', 'exp': int(time.time()) + 3600},+ 'secret',+ algorithm='HS256',+ )+ user_auth = SaasUserAuth(+ user_id='test_user_id',+ refresh_token=SecretStr(''),+ auth_type=AuthType.BEARER,+ )++ with patch('server.auth.saas_user_auth.token_manager') as mock_tm:+ mock_tm.load_offline_token = AsyncMock(return_value=offline_token)+ mock_tm.refresh = AsyncMock(+ side_effect=KeycloakPostError(+ 'invalid_grant: Offline user session not found'+ )+ )++ # Act+ result = await user_auth.get_access_token()++ # Assert+ assert result is None+++async def test_get_provider_tokens_succeeds_without_offline_session():+ """Provider tokens resolve by user_id with no offline session / refresh.++ The core decoupling: a key whose Keycloak offline session is gone (empty+ refresh token) still gets provider tokens, which come from the auth_tokens+ table + provider OAuth β never a Keycloak refresh.+ """+ # Arrange+ mock_auth_token = MagicMock()+ mock_auth_token.identity_provider = 'github'+ mock_auth_token.id = 'token-id-1'++ mock_session = AsyncMock()+ mock_session.__aenter__ = AsyncMock(return_value=mock_session)+ mock_session.__aexit__ = AsyncMock(return_value=None)+ mock_result = MagicMock()+ mock_result.scalars.return_value.all.return_value = [mock_auth_token]+ mock_session.execute = AsyncMock(return_value=mock_result)++ user_auth = SaasUserAuth(+ user_id='test_user_id',+ refresh_token=SecretStr(''),+ auth_type=AuthType.BEARER,+ )+ user_auth.get_secrets = AsyncMock(return_value=None)++ with (+ patch('server.auth.saas_user_auth.token_manager') as mock_tm,+ patch('server.auth.saas_user_auth.a_session_maker') as mock_session_maker,+ ):+ mock_session_maker.return_value = mock_session+ mock_tm.get_idp_token_by_user_id = AsyncMock(return_value='github_token')+ mock_tm.refresh = AsyncMock()+ mock_tm.load_offline_token = AsyncMock()++ # Act+ result = await user_auth.get_provider_tokens()++ # Assert+ assert result[ProviderType.GITHUB].token.get_secret_value() == 'github_token'+ mock_tm.get_idp_token_by_user_id.assert_called_once_with(+ 'test_user_id', idp=ProviderType.GITHUB+ )+ mock_tm.refresh.assert_not_called()+ mock_tm.load_offline_token.assert_not_called()+++ 'build',+ [+ lambda: SaasUserAuth.get_for_user('test_user_id'),+ lambda: get_user_auth_from_keycloak_id('test_user_id'),+ ],+ ids=['get_for_user', 'get_user_auth_from_keycloak_id'],+)+async def test_background_user_auth_does_not_require_offline_session(build):+ """Background/integration entry points build BEARER auth with no offline token."""+ # Act+ built = await build()++ # Assert+ assert built.user_id == 'test_user_id'+ assert built.auth_type == AuthType.BEARER+ assert built.refresh_token.get_secret_value() == ''++@pytest.mark.asyncioasync def test_get_user_settings_store():"""Test that get_user_settings_store returns a settings store."""@@ -472,18 +614,16 @@ async def test_get_instance_no_auth(mock_request):@pytest.mark.asyncioasync def test_saas_user_auth_from_bearer_success():- """Test successful authentication from bearer token sets user_id and api_key_org_id."""+ """A valid API key authenticates with no Keycloak round-trip.++ Bearer auth must not load an offline token or call refresh(): the key+ alone authenticates the request, so a missing/revoked offline session can+ no longer turn a valid key into a 401.+ """# Arrangemock_request = MagicMock()mock_request.headers = {'Authorization': 'Bearer test_api_key'}- # Create a valid offline token (refresh token)- offline_token = jwt.encode(- {'sub': 'test_user_id', 'exp': int(time.time()) + 3600},- 'secret',- algorithm='HS256',- )-mock_org_id = uuid.uuid4()mock_validation_result = ApiKeyValidationResult(user_id='test_user_id',@@ -501,22 +641,23 @@ async def test_saas_user_auth_from_bearer_success():return_value=mock_validation_result)mock_api_key_store_cls.get_instance.return_value = mock_api_key_store+ mock_token_manager.load_offline_token = AsyncMock()+ mock_token_manager.refresh = AsyncMock()- mock_token_manager.load_offline_token = AsyncMock(return_value=offline_token)- mock_token_manager.refresh = AsyncMock(- return_value=create_mock_jwt_tokens('test_user_id')- )-+ # Actresult = await saas_user_auth_from_bearer(mock_request)+ # Assertassert isinstance(result, SaasUserAuth)assert result.user_id == 'test_user_id'assert result.api_key_org_id == mock_org_idassert result.api_key_id == 42assert result.api_key_name == 'Test Key'+ assert result.auth_type == AuthType.BEARERmock_api_key_store.validate_api_key.assert_called_once_with('test_api_key')- mock_token_manager.load_offline_token.assert_called_once_with('test_user_id')- mock_token_manager.refresh.assert_called_once_with(offline_token)+ # Decoupled from Keycloak: no offline-session load, no refresh.+ mock_token_manager.load_offline_token.assert_not_called()+ mock_token_manager.refresh.assert_not_called()@pytest.mark.asynciodiff --git a/enterprise/tests/unit/test_token_manager_extended.py b/enterprise/tests/unit/test_token_manager_extended.pyindex 307cf6dd4c..987567bc3e 100644--- a/enterprise/tests/unit/test_token_manager_extended.py+++ b/enterprise/tests/unit/test_token_manager_extended.py@@ -228,6 +228,38 @@ async def test_get_idp_token(token_manager, create_keycloak_user_info):mock_token_store.return_value.load_tokens.assert_called_once()+async def test_get_idp_token_by_user_id(token_manager):+ """Resolving an IDP token by user_id needs no Keycloak userinfo round-trip.++ The token is read from the auth_tokens store (and refreshed via the+ provider's OAuth endpoint), so this path is independent of the user's+ Keycloak offline session.+ """+ with (+ patch(+ 'server.auth.token_manager.TokenManager.get_user_info',+ AsyncMock(),+ ) as mock_get_user_info,+ patch('server.auth.token_manager.AuthTokenStore') as mock_token_store_cls,+ ):+ mock_token_store = AsyncMock()+ mock_token_store.return_value.load_tokens.return_value = {+ 'access_token': token_manager.encrypt_text('github_access_token'),+ }+ mock_token_store_cls.get_instance = mock_token_store++ token = await token_manager.get_idp_token_by_user_id(+ 'test_user_id', ProviderType.GITHUB+ )++ assert token == 'github_access_token'+ mock_token_store_cls.get_instance.assert_called_once_with(+ keycloak_user_id='test_user_id', idp=ProviderType.GITHUB+ )+ mock_get_user_info.assert_not_called()++@pytest.mark.asyncioasync def test_refresh(token_manager):"""Test refreshing a token."""