Add set and expire password (#197)

* add set and expire password

* readme

* fix readme

* rename set password arguments

* CR fixes

* CR fixes

* improve readme

* improve readme

* improve readme

Author: asafshen

README.md

@@ -445,7 +445,7 @@ tenants = tenants_resp["tenants"]
 
 ### Manage Users
 
-You can create, update, delete or load users, as well as search according to filters:
+You can create, update, delete or load users, as well as setting new password, expire password and search according to filters:
 
 ```Python
 # A user must have a login ID, other fields are optional.
@@ -513,6 +513,20 @@ users = users_resp["users"]
         # Do something
 ```
 
+#### Set or Expire User Password
+
+You can set or expire a user's password.
+Note: When setting a password, it will automatically be set as expired.
+The user will not be able log-in using an expired password, and will be required replace it on next login.
+
+```Python
+// Set a user's password
+descope_client.mgmt.user.setPassword('<login-id>', '<some-password>');
+
+// Or alternatively, expire a user password
+descope_client.mgmt.user.expirePassword('<login-id>');
+```
+
 ### Manage Access Keys
 
 You can create, update, delete or load access keys, as well as search according to filters:

descope/management/common.py

@@ -23,6 +23,8 @@ class MgmtV1:
     user_update_custom_attribute_path = "/v1/mgmt/user/update/customAttribute"
     user_add_role_path = "/v1/mgmt/user/update/role/add"
     user_remove_role_path = "/v1/mgmt/user/update/role/remove"
+    user_set_password_path = "/v1/mgmt/user/password/set"
+    user_expire_password_path = "/v1/mgmt/user/password/expire"
     user_add_tenant_path = "/v1/mgmt/user/update/tenant/add"
     user_remove_tenant_path = "/v1/mgmt/user/update/tenant/remove"
     user_generate_otp_for_test_path = "/v1/mgmt/tests/generate/otp"

descope/management/user.py

@@ -719,6 +719,53 @@ def remove_tenant_roles(
         )
         return response.json()
 
+    def set_password(
+        self,
+        login_id: str,
+        password: str,
+    ) -> None:
+        """
+            Set the password for the given login ID.
+            Note: The password will automatically be set as expired.
+            The user will not be able to log-in with this password, and will be required to replace it on next login.
+            See also: expire_password
+
+        Args:
+        login_id (str): The login ID of the user to set the password to.
+        password (str): The new password to set to the user.
+
+        Raise:
+        AuthException: raised if the operation fails
+        """
+        self._auth.do_post(
+            MgmtV1.user_set_password_path,
+            {"loginId": login_id, "password": password},
+            pswd=self._auth.management_key,
+        )
+        return
+
+    def expire_password(
+        self,
+        login_id: str,
+    ) -> None:
+        """
+            Expires the password for the given login ID.
+            Note: user sign-in with an expired password, the user will get an error with code.
+            Use the `password.send_reset` or `password.replace` methods to reset/replace the password.
+
+        Args:
+        login_id (str): The login ID of the user expire the password to.
+
+        Raise:
+        AuthException: raised if the operation fails
+        """
+        self._auth.do_post(
+            MgmtV1.user_expire_password_path,
+            {"loginId": login_id},
+            pswd=self._auth.management_key,
+        )
+        return
+
     def generate_otp_for_test_user(
         self,
         method: DeliveryMethod,

tests/management/test_user.py

@@ -1014,6 +1014,79 @@ def test_generate_otp_for_test_user(self):
                 timeout=DEFAULT_TIMEOUT_SECONDS,
             )
 
+    def test_user_set_password(self):
+        # Test failed flows
+        with patch("requests.post") as mock_post:
+            mock_post.return_value.ok = False
+            self.assertRaises(
+                AuthException,
+                self.client.mgmt.user.set_password,
+                "login-id",
+                "some-password",
+            )
+
+        # Test success flow
+        with patch("requests.post") as mock_post:
+            network_resp = mock.Mock()
+            network_resp.ok = True
+            mock_post.return_value = network_resp
+            self.client.mgmt.user.set_password(
+                "login-id",
+                "some-password",
+            )
+            mock_post.assert_called_with(
+                f"{common.DEFAULT_BASE_URL}{MgmtV1.user_set_password_path}",
+                headers={
+                    **common.default_headers,
+                    "Authorization": f"Bearer {self.dummy_project_id}:{self.dummy_management_key}",
+                },
+                params=None,
+                data=json.dumps(
+                    {
+                        "loginId": "login-id",
+                        "password": "some-password",
+                    }
+                ),
+                allow_redirects=False,
+                verify=True,
+                timeout=DEFAULT_TIMEOUT_SECONDS,
+            )
+
+    def test_user_expire_password(self):
+        # Test failed flows
+        with patch("requests.post") as mock_post:
+            mock_post.return_value.ok = False
+            self.assertRaises(
+                AuthException,
+                self.client.mgmt.user.expire_password,
+                "login-id",
+            )
+
+        # Test success flow
+        with patch("requests.post") as mock_post:
+            network_resp = mock.Mock()
+            network_resp.ok = True
+            mock_post.return_value = network_resp
+            self.client.mgmt.user.expire_password(
+                "login-id",
+            )
+            mock_post.assert_called_with(
+                f"{common.DEFAULT_BASE_URL}{MgmtV1.user_expire_password_path}",
+                headers={
+                    **common.default_headers,
+                    "Authorization": f"Bearer {self.dummy_project_id}:{self.dummy_management_key}",
+                },
+                params=None,
+                data=json.dumps(
+                    {
+                        "loginId": "login-id",
+                    }
+                ),
+                allow_redirects=False,
+                verify=True,
+                timeout=DEFAULT_TIMEOUT_SECONDS,
+            )
+
     def test_generate_magic_link_for_test_user(self):
         # Test failed flows
         with patch("requests.post") as mock_post: