Skip to content

πŸ™Œ 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.py
index 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 UUID
import jwt
from fastapi import HTTPException, Request
-from keycloak.exceptions import KeycloakError
+from keycloak.exceptions import KeycloakConnectionError
from pydantic import SecretStr
from server.auth.auth_error import (
AuthError,
@@ -277,14 +277,39 @@ class SaasUserAuth(UserAuth):
return self.user_id
async 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_verified
return 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_verified
self._settings = settings
return settings
@@ -381,8 +408,19 @@ class SaasUserAuth(UserAuth):
await self.refresh()
return self.access_token
except 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 None
raise
except Exception as e:
+ if self.auth_type == AuthType.BEARER:
+ logger.warning('bearer_get_access_token_failed', exc_info=True)
+ return None
raise AuthError() from e
async 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_tokens
provider_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):
@classmethod
async 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_auth
except 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_auth
diff --git a/enterprise/server/auth/token_manager.py b/enterprise/server/auth/token_manager.py
index 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 idp
user_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 body
logger.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 e
diff --git a/enterprise/tests/unit/test_saas_user_auth.py b/enterprise/tests/unit/test_saas_user_auth.py
index 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 UserAuthorizationType
from openhands.app_server.integrations.provider import ProviderToken, ProviderType
from 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.asyncio
async 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.asyncio
async 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.
+ """
# Arrange
mock_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')
- )
-
+ # Act
result = await saas_user_auth_from_bearer(mock_request)
+ # Assert
assert isinstance(result, SaasUserAuth)
assert result.user_id == 'test_user_id'
assert result.api_key_org_id == mock_org_id
assert result.api_key_id == 42
assert result.api_key_name == 'Test Key'
+ assert result.auth_type == AuthType.BEARER
mock_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.asyncio
diff --git a/enterprise/tests/unit/test_token_manager_extended.py b/enterprise/tests/unit/test_token_manager_extended.py
index 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.asyncio
async def test_refresh(token_manager):
"""Test refreshing a token."""