From 57ad3f29e974e2a244a22f52a51b49f745ac8262 Mon Sep 17 00:00:00 2001 From: Dirk Kulawiak Date: Tue, 10 Nov 2026 14:59:45 +0100 Subject: [PATCH 1/3] Add API key expiration for DB users on Weaviate 1.41+ --- .github/workflows/main.yaml | 6 ++ ci/docker-compose-rbac.yml | 1 + integration/test_users.py | 144 ++++++++++++++++++++++++++++++++++++ weaviate/rbac/models.py | 1 + weaviate/users/async_.pyi | 4 +- weaviate/users/base.py | 103 +++++++++++++++++++------- weaviate/users/sync.pyi | 4 +- weaviate/users/users.py | 2 + 8 files changed, 237 insertions(+), 28 deletions(-) diff --git a/.github/workflows/main.yaml b/.github/workflows/main.yaml index cfdb969e4..110256f9c 100644 --- a/.github/workflows/main.yaml +++ b/.github/workflows/main.yaml @@ -407,8 +407,14 @@ jobs: pip install weaviate_client-*.whl - run: rm -r weaviate - name: start weaviate + env: + # ci/docker-compose-rbac.yml passes it to Weaviate as LICENSE_KEY. + WEAVIATE_LICENSE_KEY: ${{ secrets.WEAVIATE_LICENSE_KEY }} run: /bin/bash ci/start_weaviate.sh ${{ matrix.version }} - name: Run integration tests without auth secrets (auth tests ran in previous job) + env: + # The DB user expiration tests skip where it is empty, as on forks. + WEAVIATE_LICENSE_KEY: ${{ secrets.WEAVIATE_LICENSE_KEY }} run: pytest -v -n auto --dist loadgroup integration build-and-publish: diff --git a/ci/docker-compose-rbac.yml b/ci/docker-compose-rbac.yml index af17ccf08..6c87563cf 100644 --- a/ci/docker-compose-rbac.yml +++ b/ci/docker-compose-rbac.yml @@ -28,6 +28,7 @@ services: RAFT_BOOTSTRAP_EXPECT: "1" AUTHORIZATION_ENABLE_RBAC: "true" AUTHENTICATION_DB_USERS_ENABLED: "true" + LICENSE_KEY: ${WEAVIATE_LICENSE_KEY:-} AUTHENTICATION_OIDC_ENABLED: 'true' AUTHENTICATION_OIDC_CLIENT_ID: 'Peuc12y02UA0eAED1dqSjE5HtGUrpBsx' AUTHENTICATION_OIDC_ISSUER: 'https://auth.weaviate.cloud/Peuc12y02UA0eAED1dqSjE5HtGUrpBsx' diff --git a/integration/test_users.py b/integration/test_users.py index 1a1358887..78006450d 100644 --- a/integration/test_users.py +++ b/integration/test_users.py @@ -1,3 +1,7 @@ +import os +from datetime import datetime, timedelta, timezone +from typing import Callable, Union + import pytest from _pytest.fixtures import SubRequest @@ -5,6 +9,7 @@ from integration.conftest import ClientFactory, _sanitize_collection_name from weaviate.auth import Auth from weaviate.rbac.models import Role, RoleBase, UserTypes +from weaviate.users.sync import _UsersDB RBAC_PORTS = (8092, 50063) RBAC_AUTH_CREDS = Auth.api_key("admin-key") @@ -265,3 +270,142 @@ def test_list_all_include_last_used_time( assert target.last_used_time is not None finally: client.users.db.delete(user_id=user_id) + + +def _skip_unless_user_expiration( + client: Union[weaviate.WeaviateClient, weaviate.WeaviateAsyncClient], +) -> None: + if client._connection._weaviate_version.is_lower_than(1, 41, 0): + pytest.skip("This test requires Weaviate 1.41.0 or higher") + if not os.environ.get("WEAVIATE_LICENSE_KEY"): + pytest.skip("This test requires WEAVIATE_LICENSE_KEY, the server's license key") + + +def _in_days(days: int) -> datetime: + # _in_days drops the microseconds the server does not keep, and uses a non-UTC + # zone so a round trip shows that the client sends the offset. + return (datetime.now(timezone(timedelta(hours=2))) + timedelta(days=days)).replace( + microsecond=0 + ) + + +def test_user_expiration(client_factory: ClientFactory, request: SubRequest) -> None: + with client_factory(ports=RBAC_PORTS, auth_credentials=RBAC_AUTH_CREDS) as client: + _skip_unless_user_expiration(client) + + user_id = _unique_user_id(request.node.name) + in_one_day = _in_days(1) + api_key = client.users.db.create(user_id=user_id, expires_at=in_one_day) + try: + user = client.users.db.get(user_id=user_id) + assert user is not None + assert user.expires_at == in_one_day + listed = next(u for u in client.users.db.list_all() if u.user_id == user_id) + assert listed.expires_at == in_one_day + with weaviate.connect_to_local( + port=RBAC_PORTS[0], grpc_port=RBAC_PORTS[1], auth_credentials=Auth.api_key(api_key) + ) as client2: + assert client2.users.get_my_user().expires_at == in_one_day + + in_two_days = _in_days(2) + client.users.db.update_expiration(user_id=user_id, expires_at=in_two_days) + user = client.users.db.get(user_id=user_id) + assert user is not None + assert user.expires_at == in_two_days + + client.users.db.update_expiration(user_id=user_id, expires_at=None) + user = client.users.db.get(user_id=user_id) + assert user is not None + assert user.expires_at is None + finally: + client.users.db.delete(user_id=user_id) + + +@pytest.mark.asyncio +async def test_user_expiration_async(request: SubRequest) -> None: + async with weaviate.use_async_with_local( + port=RBAC_PORTS[0], grpc_port=RBAC_PORTS[1], auth_credentials=RBAC_AUTH_CREDS + ) as client: + _skip_unless_user_expiration(client) + + user_id = _unique_user_id(request.node.name) + in_one_day = _in_days(1) + await client.users.db.create(user_id=user_id, expires_at=in_one_day) + try: + user = await client.users.db.get(user_id=user_id) + assert user is not None + assert user.expires_at == in_one_day + + in_two_days = _in_days(2) + await client.users.db.update_expiration(user_id=user_id, expires_at=in_two_days) + user = await client.users.db.get(user_id=user_id) + assert user is not None + assert user.expires_at == in_two_days + + await client.users.db.update_expiration(user_id=user_id, expires_at=None) + user = await client.users.db.get(user_id=user_id) + assert user is not None + assert user.expires_at is None + finally: + await client.users.db.delete(user_id=user_id) + + +def test_update_expiration_on_never_expiring_user( + client_factory: ClientFactory, request: SubRequest +) -> None: + with client_factory(ports=RBAC_PORTS, auth_credentials=RBAC_AUTH_CREDS) as client: + _skip_unless_user_expiration(client) + + user_id = _unique_user_id(request.node.name) + api_key = client.users.db.create(user_id=user_id) + try: + user = client.users.db.get(user_id=user_id) + assert user is not None + assert user.expires_at is None + + in_one_day = _in_days(1) + client.users.db.update_expiration(user_id=user_id, expires_at=in_one_day) + user = client.users.db.get(user_id=user_id) + assert user is not None + assert user.expires_at == in_one_day + with weaviate.connect_to_local( + port=RBAC_PORTS[0], grpc_port=RBAC_PORTS[1], auth_credentials=Auth.api_key(api_key) + ) as client2: + assert client2.users.get_my_user().expires_at == in_one_day + + new_api_key = client.users.db.rotate_key(user_id=user_id) + with weaviate.connect_to_local( + port=RBAC_PORTS[0], + grpc_port=RBAC_PORTS[1], + auth_credentials=Auth.api_key(new_api_key), + ) as client2: + assert client2.users.get_my_user().expires_at == in_one_day + finally: + client.users.db.delete(user_id=user_id) + + +def test_update_expiration_of_missing_user(client_factory: ClientFactory) -> None: + with client_factory(ports=RBAC_PORTS, auth_credentials=RBAC_AUTH_CREDS) as client: + _skip_unless_user_expiration(client) + + with pytest.raises(weaviate.exceptions.UnexpectedStatusCodeError): + client.users.db.update_expiration(user_id="I-do-not-exist", expires_at=_in_days(1)) + + +@pytest.mark.parametrize( + "call", + [ + lambda db: db.create(user_id="expiry-unsupported", expires_at=_in_days(1)), + lambda db: db.update_expiration(user_id="expiry-unsupported", expires_at=_in_days(1)), + ], + ids=["create", "update_expiration"], +) +def test_user_expiration_unsupported_version( + client_factory: ClientFactory, call: Callable[[_UsersDB], object] +) -> None: + with client_factory(ports=RBAC_PORTS, auth_credentials=RBAC_AUTH_CREDS) as client: + if not client._connection._weaviate_version.is_lower_than(1, 41, 0): + pytest.skip("This test requires a Weaviate version below 1.41.0") + + with pytest.raises(weaviate.exceptions.WeaviateUnsupportedFeatureError): + call(client.users.db) diff --git a/weaviate/rbac/models.py b/weaviate/rbac/models.py index f1cd89bbe..241bbd9ff 100644 --- a/weaviate/rbac/models.py +++ b/weaviate/rbac/models.py @@ -143,6 +143,7 @@ class WeaviateDBUserRoleNames(TypedDict): createdAt: NotRequired[str] lastUsedAt: NotRequired[str] apiKeyFirstLetters: NotRequired[str] + expiresAt: NotRequired[Optional[str]] class _Action: diff --git a/weaviate/users/async_.pyi b/weaviate/users/async_.pyi index 5770a5063..187038531 100644 --- a/weaviate/users/async_.pyi +++ b/weaviate/users/async_.pyi @@ -1,3 +1,4 @@ +from datetime import datetime from typing import Dict, List, Literal, Optional, Union, overload from typing_extensions import deprecated @@ -52,7 +53,8 @@ class _UsersDBAsync(_UsersDBExecutor[ConnectionAsync]): ) -> Union[Dict[str, Role], Dict[str, RoleBase]]: ... async def assign_roles(self, *, user_id: str, role_names: Union[str, List[str]]) -> None: ... async def revoke_roles(self, *, user_id: str, role_names: Union[str, List[str]]) -> None: ... - async def create(self, *, user_id: str) -> str: ... + async def create(self, *, user_id: str, expires_at: Optional[datetime] = None) -> str: ... + async def update_expiration(self, *, user_id: str, expires_at: Optional[datetime]) -> None: ... async def delete(self, *, user_id: str) -> bool: ... async def rotate_key(self, *, user_id: str) -> str: ... async def activate(self, *, user_id: str) -> bool: ... diff --git a/weaviate/users/base.py b/weaviate/users/base.py index 2a175a8b7..e7a4e204a 100644 --- a/weaviate/users/base.py +++ b/weaviate/users/base.py @@ -6,6 +6,7 @@ from weaviate.connect import executor from weaviate.connect.v4 import ConnectionType, _ExpectedStatusCodes +from weaviate.exceptions import WeaviateUnsupportedFeatureError from weaviate.rbac.models import ( Role, RoleBase, @@ -19,7 +20,11 @@ OwnUser, UserDB, ) -from weaviate.util import _decode_json_response_dict, escape_string +from weaviate.util import ( + _datetime_to_string, + _decode_json_response_dict, + escape_string, +) # Go's zero time value, returned by the server when a timestamp is not set _GO_ZERO_TIME = datetime(1, 1, 1, 0, 0, tzinfo=timezone.utc) @@ -32,6 +37,19 @@ def _parse_optional_timestamp(value: Optional[str]) -> Optional[datetime]: return None if dt == _GO_ZERO_TIME else dt +def _parse_db_user(user: WeaviateDBUserRoleNames) -> UserDB: + return UserDB( + user_id=user["userId"], + role_names=user["roles"], + active=user["active"], + user_type=UserTypes(user["dbUserType"]), + created_at=_parse_optional_timestamp(user.get("createdAt")), + last_used_time=_parse_optional_timestamp(user.get("lastUsedAt")), + api_key_first_letters=user.get("apiKeyFirstLetters"), + expires_at=_parse_optional_timestamp(user.get("expiresAt")), + ) + + class _BaseExecutor(Generic[ConnectionType]): def __init__(self, connection: ConnectionType): self._connection = connection @@ -147,6 +165,7 @@ def resp(res: Response) -> OwnUser: else {} ), groups=parsed["groups"] if "groups" in parsed else [], + expires_at=_parse_optional_timestamp(parsed.get("expiresAt")), ) return executor.execute( @@ -295,6 +314,14 @@ def revoke_roles( class _UsersDBExecutor(Generic[ConnectionType], _BaseExecutor[ConnectionType]): + def __check_expiration_version(self) -> None: + if self._connection._weaviate_version.is_lower_than(1, 41, 0): + raise WeaviateUnsupportedFeatureError( + "DB user expiration", + str(self._connection._weaviate_version), + "1.41.0", + ) + @overload def get_assigned_roles( self, *, user_id: str, include_permissions: Literal[False] = False @@ -360,15 +387,22 @@ def revoke_roles( USER_TYPE_DB, ) - def create(self, *, user_id: str) -> executor.Result[str]: + def create( + self, *, user_id: str, expires_at: Optional[datetime] = None + ) -> executor.Result[str]: """Create a new db user and return its API key. Args: user_id: The id of the new user. + expires_at: The time at which the user's API key stops authenticating, which must be in the future. Weaviate stores it in UTC to the millisecond. If None, the key never expires. Requires Weaviate 1.41+ and a Weaviate license key on the server. Returns: The API key of the newly created user. This key can not be retrieved later. """ + payload: Dict[str, Any] = {} + if expires_at is not None: + self.__check_expiration_version() + payload["expiresAt"] = _datetime_to_string(expires_at) def resp(res: Response) -> str: resp = _decode_json_response_dict(res, "Create user") @@ -378,12 +412,42 @@ def resp(res: Response) -> str: return executor.execute( response_callback=resp, method=self._connection.post, - path=f"/users/db/{user_id}", - weaviate_object={}, + path=f"/users/db/{escape_string(user_id)}", + weaviate_object=payload, error_msg=f"Could not create user '{user_id}'", status_codes=_ExpectedStatusCodes(ok_in=[201], error="Create user"), ) + def update_expiration( + self, *, user_id: str, expires_at: Optional[datetime] + ) -> executor.Result[None]: + """Set or remove the time at which the API key of a db user stops authenticating. + + Requires Weaviate 1.41+ and a Weaviate license key on the server. + + Args: + user_id: The id of the user. + expires_at: The time at which the user's API key stops authenticating, which must be in the future. Weaviate stores it in UTC to the millisecond. If None, the key never expires. + """ + self.__check_expiration_version() + payload: Dict[str, Any] = ( + {"neverExpires": True} + if expires_at is None + else {"expiresAt": _datetime_to_string(expires_at)} + ) + + def resp(res: Response) -> None: + pass + + return executor.execute( + response_callback=resp, + method=self._connection.put, + path=f"/users/db/{escape_string(user_id)}/expiration", + weaviate_object=payload, + error_msg=f"Could not update the expiration of user '{user_id}'", + status_codes=_ExpectedStatusCodes(ok_in=[200], error="Update user expiration"), + ) + def delete(self, *, user_id: str) -> executor.Result[bool]: """Delete a (dynamic) db user. @@ -405,6 +469,8 @@ def resp(res: Response) -> bool: def rotate_key(self, *, user_id: str) -> executor.Result[str]: """Rotate the key of a new db user. + The new key expires when the old one would have. `update_expiration` changes that. + Args: user_id: The id of the user. """ @@ -467,6 +533,8 @@ def get( ) -> executor.Result[Optional[UserDB]]: """Get all information about an user. + `active` stays True after the user's API key expires, so compare `expires_at` with the current time. + Args: user_id: The id of the user. include_last_used_time: If True, the last used time of the user will be included. @@ -477,20 +545,12 @@ def resp(res: Response) -> Optional[UserDB]: return None parsed = _decode_json_response_dict(res, "Get user") assert parsed is not None - return UserDB( - user_id=parsed["userId"], - role_names=parsed["roles"], - active=parsed["active"], - user_type=UserTypes(parsed["dbUserType"]), - created_at=_parse_optional_timestamp(parsed.get("createdAt")), - last_used_time=_parse_optional_timestamp(parsed.get("lastUsedAt")), - api_key_first_letters=parsed.get("apiKeyFirstLetters"), - ) + return _parse_db_user(cast(WeaviateDBUserRoleNames, parsed)) return executor.execute( response_callback=resp, method=self._connection.get, - path=f"/users/db/{user_id}", + path=f"/users/db/{escape_string(user_id)}", params={"includeLastUsedTime": include_last_used_time}, error_msg=f"Could not get user '{user_id}'", status_codes=_ExpectedStatusCodes(ok_in=[200, 404], error="get user"), @@ -499,6 +559,8 @@ def resp(res: Response) -> Optional[UserDB]: def list_all(self, *, include_last_used_time: bool = False) -> executor.Result[List[UserDB]]: """List all DB users. + `active` stays True after a user's API key expires, so compare `expires_at` with the current time. + Args: include_last_used_time: If True, the last used time of each user will be included. """ @@ -506,18 +568,7 @@ def list_all(self, *, include_last_used_time: bool = False) -> executor.Result[L def resp(res: Response) -> List[UserDB]: parsed = _decode_json_response_dict(res, "Get user") assert parsed is not None - return [ - UserDB( - user_id=user["userId"], - role_names=user["roles"], - active=user["active"], - user_type=UserTypes(user["dbUserType"]), - created_at=_parse_optional_timestamp(user.get("createdAt")), - last_used_time=_parse_optional_timestamp(user.get("lastUsedAt")), - api_key_first_letters=user.get("apiKeyFirstLetters"), - ) - for user in cast(List[WeaviateDBUserRoleNames], parsed) - ] + return [_parse_db_user(user) for user in cast(List[WeaviateDBUserRoleNames], parsed)] return executor.execute( response_callback=resp, diff --git a/weaviate/users/sync.pyi b/weaviate/users/sync.pyi index 7e82eee19..d87815955 100644 --- a/weaviate/users/sync.pyi +++ b/weaviate/users/sync.pyi @@ -1,3 +1,4 @@ +from datetime import datetime from typing import Dict, List, Literal, Optional, Union, overload from typing_extensions import deprecated @@ -52,7 +53,8 @@ class _UsersDB(_UsersDBExecutor[ConnectionSync]): ) -> Union[Dict[str, Role], Dict[str, RoleBase]]: ... def assign_roles(self, *, user_id: str, role_names: Union[str, List[str]]) -> None: ... def revoke_roles(self, *, user_id: str, role_names: Union[str, List[str]]) -> None: ... - def create(self, *, user_id: str) -> str: ... + def create(self, *, user_id: str, expires_at: Optional[datetime] = None) -> str: ... + def update_expiration(self, *, user_id: str, expires_at: Optional[datetime]) -> None: ... def delete(self, *, user_id: str) -> bool: ... def rotate_key(self, *, user_id: str) -> str: ... def activate(self, *, user_id: str) -> bool: ... diff --git a/weaviate/users/users.py b/weaviate/users/users.py index 7c213e141..7383bcadd 100644 --- a/weaviate/users/users.py +++ b/weaviate/users/users.py @@ -17,6 +17,7 @@ class OwnUser: user_id: str roles: Dict[str, Role] groups: List[str] + expires_at: Optional[datetime] = field(default=None) @dataclass @@ -33,6 +34,7 @@ class UserDB(UserBase): created_at: Optional[datetime] = field(default=None) last_used_time: Optional[datetime] = field(default=None) api_key_first_letters: Optional[str] = field(default=None) + expires_at: Optional[datetime] = field(default=None) @dataclass From 0693fed4bc88586c5022fefeb1aa6dac5f8f4ed1 Mon Sep 17 00:00:00 2001 From: Dirk Kulawiak Date: Wed, 11 Nov 2026 07:03:08 +0100 Subject: [PATCH 2/3] Add more integration tests for get functions --- integration/test_users.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/integration/test_users.py b/integration/test_users.py index 78006450d..cdb4193a2 100644 --- a/integration/test_users.py +++ b/integration/test_users.py @@ -292,6 +292,8 @@ def _in_days(days: int) -> datetime: def test_user_expiration(client_factory: ClientFactory, request: SubRequest) -> None: with client_factory(ports=RBAC_PORTS, auth_credentials=RBAC_AUTH_CREDS) as client: _skip_unless_user_expiration(client) + # admin-user is a static user from the server's env config, whose key never expires. + assert client.users.get_my_user().expires_at is None user_id = _unique_user_id(request.node.name) in_one_day = _in_days(1) @@ -317,6 +319,8 @@ def test_user_expiration(client_factory: ClientFactory, request: SubRequest) -> user = client.users.db.get(user_id=user_id) assert user is not None assert user.expires_at is None + listed = next(u for u in client.users.db.list_all() if u.user_id == user_id) + assert listed.expires_at is None finally: client.users.db.delete(user_id=user_id) @@ -362,6 +366,10 @@ def test_update_expiration_on_never_expiring_user( user = client.users.db.get(user_id=user_id) assert user is not None assert user.expires_at is None + with weaviate.connect_to_local( + port=RBAC_PORTS[0], grpc_port=RBAC_PORTS[1], auth_credentials=Auth.api_key(api_key) + ) as client2: + assert client2.users.get_my_user().expires_at is None in_one_day = _in_days(1) client.users.db.update_expiration(user_id=user_id, expires_at=in_one_day) From fceb5fa142b8e4082eba3dceae10792685712fe0 Mon Sep 17 00:00:00 2001 From: Dirk Kulawiak Date: Wed, 18 Nov 2026 05:51:53 +0100 Subject: [PATCH 3/3] Docstring fixes --- weaviate/users/base.py | 12 ++++++------ weaviate/users/users.py | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/weaviate/users/base.py b/weaviate/users/base.py index e7a4e204a..34d678e99 100644 --- a/weaviate/users/base.py +++ b/weaviate/users/base.py @@ -394,7 +394,7 @@ def create( Args: user_id: The id of the new user. - expires_at: The time at which the user's API key stops authenticating, which must be in the future. Weaviate stores it in UTC to the millisecond. If None, the key never expires. Requires Weaviate 1.41+ and a Weaviate license key on the server. + expires_at: The future time at which the db user can no longer authenticate. Weaviate stores it in UTC to the millisecond. If None, the user never expires. Requires Weaviate 1.41+ and a Weaviate license key on the server. Returns: The API key of the newly created user. This key can not be retrieved later. @@ -421,13 +421,13 @@ def resp(res: Response) -> str: def update_expiration( self, *, user_id: str, expires_at: Optional[datetime] ) -> executor.Result[None]: - """Set or remove the time at which the API key of a db user stops authenticating. + """Set or remove the time at which a db user can no longer authenticate. Requires Weaviate 1.41+ and a Weaviate license key on the server. Args: user_id: The id of the user. - expires_at: The time at which the user's API key stops authenticating, which must be in the future. Weaviate stores it in UTC to the millisecond. If None, the key never expires. + expires_at: The future time at which the db user can no longer authenticate. Weaviate stores it in UTC to the millisecond. If None, the user never expires. """ self.__check_expiration_version() payload: Dict[str, Any] = ( @@ -469,7 +469,7 @@ def resp(res: Response) -> bool: def rotate_key(self, *, user_id: str) -> executor.Result[str]: """Rotate the key of a new db user. - The new key expires when the old one would have. `update_expiration` changes that. + The user's expiration carries over to the new key. `update_expiration` changes it. Args: user_id: The id of the user. @@ -533,7 +533,7 @@ def get( ) -> executor.Result[Optional[UserDB]]: """Get all information about an user. - `active` stays True after the user's API key expires, so compare `expires_at` with the current time. + `active` stays True after the user expires, so compare `expires_at` with the current time. Args: user_id: The id of the user. @@ -559,7 +559,7 @@ def resp(res: Response) -> Optional[UserDB]: def list_all(self, *, include_last_used_time: bool = False) -> executor.Result[List[UserDB]]: """List all DB users. - `active` stays True after a user's API key expires, so compare `expires_at` with the current time. + `active` stays True after a user expires, so compare `expires_at` with the current time. Args: include_last_used_time: If True, the last used time of each user will be included. diff --git a/weaviate/users/users.py b/weaviate/users/users.py index 7383bcadd..660898db3 100644 --- a/weaviate/users/users.py +++ b/weaviate/users/users.py @@ -30,7 +30,7 @@ class UserBase: @dataclass class UserDB(UserBase): user_type: UserTypes - active: bool + active: bool # Administratively enabled; expiration does not change this value. created_at: Optional[datetime] = field(default=None) last_used_time: Optional[datetime] = field(default=None) api_key_first_letters: Optional[str] = field(default=None)