Add password functions (#158)

* Add password functions

* Add password fixes and samples

* Fix magic link update URLs

Author: itaihanski

README.md

@@ -235,6 +235,74 @@ refresh_token = jwt_response[REFRESH_SESSION_TOKEN_NAME].get("jwt")
 
 The session and refresh JWTs should be returned to the caller, and passed with every request in the session. Read more on [session validation](#session-validation)
 
+### Passwords
+
+The user can also authenticate with a password, though it's recommended to
+prefer passwordless authentication methods if possible. Sign up requires the
+caller to provide a valid password that meets all the requirements configured
+for the [password authentication method](https://app.descope.com/settings/authentication/password) in the Descope console.
+
+```python
+# Every user must have a login_id and a password. All other user information is optional
+login_id = "[email protected]"
+password = "qYlvi65KaX"
+user = {
+    "name": "Desmond Copeland",
+    "email": login_id,
+}
+jwt_response = descope_client.password.sign_up(
+    login_id=login_id,
+    password=password,
+    user=user,
+)
+session_token = jwt_response[SESSION_TOKEN_NAME].get("jwt")
+refresh_token = jwt_response[REFRESH_SESSION_TOKEN_NAME].get("jwt")
+```
+
+The user can later sign in using the same login_id and password.
+
+```python
+jwt_response = descope_client.password.sign_in(login_id, password)
+session_token = jwt_response[SESSION_TOKEN_NAME].get("jwt")
+refresh_token = jwt_response[REFRESH_SESSION_TOKEN_NAME].get("jwt")
+```
+
+The session and refresh JWTs should be returned to the caller, and passed with every request in the session. Read more on [session validation](#session-validation)
+
+In case the user needs to update their password, one of two methods are available: Resetting their password or replacing their password
+
+**Changing Passwords**
+
+_NOTE: send_reset will only work if the user has a validated email address. Otherwise password reset prompts cannot be sent._
+
+In the [password authentication method](https://app.descope.com/settings/authentication/password) in the Descope console, it is possible to define which alternative authentication method can be used in order to authenticate the user, in order to reset and update their password.
+
+```python
+# Start the reset process by sending a password reset prompt. In this example we'll assume
+# that magic link is configured as the reset method. The optional redirect URL is used in the
+# same way as in regular magic link authentication.
+login_id := "[email protected]"
+redirect_url := "https://myapp.com/password-reset"
+descope_client.password.send_reset(login_id, redirect_url)
+```
+
+The magic link, in this case, must then be verified like any other magic link (see the [magic link section](#magic-link) for more details). However, after verifying the user, it is expected
+to allow them to provide a new password instead of the old one. Since the user is now authenticated, this is possible via:
+
+```python
+# The refresh token is required to make sure the user is authenticated.
+err := descope_client.password.update(login_id, new_password, token)
+```
+
+`update` can always be called when the user is authenticated and has a valid session.
+
+Alternatively, it is also possible to replace an existing active password with a new one.
+
+```python
+# Replaces the user's current password with a new one
+descope_client.password.replace(login_id, old_password, new_password)
+```
+
 ### Session Validation
 
 Every secure request performed between your client and server needs to be validated. The client sends

descope/authmethod/magiclink.py

@@ -84,7 +84,7 @@ def update_user_email(self, login_id: str, email: str, refresh_token: str) -> st
         Auth.validate_email(email)
 
         body = MagicLink._compose_update_user_email_body(login_id, email)
-        uri = EndpointsV1.update_user_email_otp_path
+        uri = EndpointsV1.update_user_email_magiclink_path
         response = self._auth.do_post(uri, body, None, refresh_token)
         return Auth.extract_masked_address(response.json(), DeliveryMethod.EMAIL)
 
@@ -99,7 +99,7 @@ def update_user_phone(
         Auth.validate_phone(method, phone)
 
         body = MagicLink._compose_update_user_phone_body(login_id, phone)
-        uri = EndpointsV1.update_user_phone_otp_path
+        uri = EndpointsV1.update_user_phone_magiclink_path
         response = self._auth.do_post(uri, body, None, refresh_token)
         return Auth.extract_masked_address(response.json(), DeliveryMethod.SMS)
 

descope/authmethod/password.py

@@ -0,0 +1,229 @@
+from descope.auth import Auth
+from descope.common import REFRESH_SESSION_COOKIE_NAME, EndpointsV1
+from descope.exceptions import ERROR_TYPE_INVALID_ARGUMENT, AuthException
+
+
+class Password:
+    _auth: Auth
+
+    def __init__(self, auth):
+        self._auth = auth
+
+    def sign_up(self, login_id: str, password: str, user: dict = None) -> dict:
+        """
+        Sign up (create) a new user using a login ID and password.
+            (optional) Include additional user metadata that you wish to save.
+
+        Args:
+        login_id (str): The login ID of the user being signed up
+        password (str): The new user's password
+        user (dict) optional: Preserve additional user metadata in the form of
+             {"name": "Desmond Copeland", "phone": "2125551212", "email": "[email protected]"}
+
+        Return value (dict):
+        Return dict in the format
+             {"jwts": [], "user": "", "firstSeen": "", "error": ""}
+        Includes all the jwts tokens (session token, refresh token), token claims, and user information
+
+        Raise:
+        AuthException: raised if sign-up operation fails
+        """
+
+        if not login_id:
+            raise AuthException(
+                400, ERROR_TYPE_INVALID_ARGUMENT, "login_id cannot be empty"
+            )
+
+        if not password:
+            raise AuthException(
+                400, ERROR_TYPE_INVALID_ARGUMENT, "password cannot be empty"
+            )
+
+        uri = EndpointsV1.sign_up_password_path
+        body = Password._compose_signup_body(login_id, password, user)
+        response = self._auth.do_post(uri, body)
+
+        resp = response.json()
+        jwt_response = self._auth.generate_jwt_response(
+            resp, response.cookies.get(REFRESH_SESSION_COOKIE_NAME, None)
+        )
+        return jwt_response
+
+    def sign_in(
+        self,
+        login_id: str,
+        password: str,
+    ) -> dict:
+        """
+        Sign in by verifying the validity of a password entered by an end user.
+
+        Args:
+        login_id (str): The login ID of the user being validated
+        password (str): The password to be validated
+
+        Return value (dict):
+        Return dict in the format
+             {"jwts": [], "user": "", "firstSeen": "", "error": ""}
+        Includes all the jwts tokens (session token, refresh token), token claims, and user information
+
+        Raise:
+        AuthException: raised if sign in operation fails
+        """
+
+        if not login_id:
+            raise AuthException(
+                400, ERROR_TYPE_INVALID_ARGUMENT, "login_id cannot be empty"
+            )
+
+        if not password:
+            raise AuthException(
+                400, ERROR_TYPE_INVALID_ARGUMENT, "Password cannot be empty"
+            )
+
+        uri = EndpointsV1.sign_in_password_path
+        response = self._auth.do_post(uri, {"loginId": login_id, "password": password})
+
+        resp = response.json()
+        jwt_response = self._auth.generate_jwt_response(
+            resp, response.cookies.get(REFRESH_SESSION_COOKIE_NAME, None)
+        )
+        return jwt_response
+
+    def send_reset(
+        self,
+        login_id: str,
+        redirect_url: str = None,
+    ) -> dict:
+        """
+        Sends a password reset prompt to the user with the given
+            login_id according to the password settings defined in the Descope console.
+            NOTE: The user must be verified according to the configured password reset method.
+
+        Args:
+        login_id (str): The login ID of the user to receive a password reset prompt
+        redirect_url (str): Optional parameter that is used by Magic Link or Enchanted Link
+                if those are the chosen reset methods. See the Magic Link and Enchanted Link sections
+                for more details.
+
+        Return value (dict):
+        Return dict in the format
+             {"resetMethod": "", "pendingRef": "", "linkId": "", "maskedEmail": ""}
+            The contents will differ according to the chosen reset method. 'pendingRef'
+            and 'linkId' will only appear of 'resetMethod' == 'enchantedlink'
+
+        Raise:
+        AuthException: raised if send reset operation fails
+        """
+
+        if not login_id:
+            raise AuthException(
+                400, ERROR_TYPE_INVALID_ARGUMENT, "login_id cannot be empty"
+            )
+
+        uri = EndpointsV1.send_reset_password_path
+        response = self._auth.do_post(
+            uri, {"loginId": login_id, "redirectUrl": redirect_url}
+        )
+
+        return response.json()
+
+    def update(self, login_id: str, new_password: str, refresh_token: str) -> None:
+        """
+        Update a password for an existing logged in user using their refresh token.
+
+        Args:
+        login_id (str): The login ID of the user whose information is being updated
+        new_password (str): The new password to use
+        refresh_token (str): The session's refresh token (used for verification)
+
+        Raise:
+        AuthException: raised if refresh token is invalid or update operation fails
+        """
+
+        if not login_id:
+            raise AuthException(
+                400, ERROR_TYPE_INVALID_ARGUMENT, "login_id cannot be empty"
+            )
+
+        if not new_password:
+            raise AuthException(
+                400, ERROR_TYPE_INVALID_ARGUMENT, "new_password cannot be empty"
+            )
+
+        if not refresh_token:
+            raise AuthException(
+                400, ERROR_TYPE_INVALID_ARGUMENT, "Refresh token cannot be empty"
+            )
+
+        uri = EndpointsV1.update_password_path
+        self._auth.do_post(
+            uri, {"loginId": login_id, "newPassword": new_password}, None, refresh_token
+        )
+
+    def replace(self, login_id: str, old_password: str, new_password: str) -> None:
+        """
+        Replace a valid active password with a new one. The old_password is used to
+        authenticate the user. If the user cannot be authenticated, this operation
+        will fail.
+
+        Args:
+        login_id (str): The login ID of the user whose information is being updated
+        old_password (str): The user's current active password
+        new_password (str): The new password to use
+
+        Raise:
+        AuthException: raised if replace operation fails
+        """
+
+        if not login_id:
+            raise AuthException(
+                400, ERROR_TYPE_INVALID_ARGUMENT, "login_id cannot be empty"
+            )
+
+        if not old_password:
+            raise AuthException(
+                400, ERROR_TYPE_INVALID_ARGUMENT, "old_password cannot be empty"
+            )
+
+        if not new_password:
+            raise AuthException(
+                400, ERROR_TYPE_INVALID_ARGUMENT, "new_password cannot be empty"
+            )
+
+        uri = EndpointsV1.replace_password_path
+        self._auth.do_post(
+            uri,
+            {
+                "loginId": login_id,
+                "oldPassword": old_password,
+                "newPassword": new_password,
+            },
+        )
+
+    def get_policy(self) -> dict:
+        """
+        Get a subset of the password policy defined in the Descope console and enforced
+        by Descope. The goal is to enable client-side validations to give users a better UX
+
+        Return value (dict):
+        Return dict in the format
+             {"minLength": 8, "lowercase": true, "uppercase": true, "number": true, "nonAlphanumeric": true}
+            minLength - the minimum length of a password
+            lowercase - the password required at least one lowercase character
+            uppercase - the password required at least one uppercase character
+            number - the password required at least one number character
+            nonAlphanumeric - the password required at least one non alphanumeric character
+
+        Raise:
+        AuthException: raised if get policy operation fails
+        """
+
+        response = self._auth.do_get(EndpointsV1.password_policy_path)
+        return response.json()
+
+    @staticmethod
+    def _compose_signup_body(login_id: str, password: str, user: dict) -> dict:
+        body = {"loginId": login_id, "password": password}
+        if user is not None:
+            body["user"] = user
+        return body

descope/common.py

@@ -76,6 +76,14 @@ class EndpointsV1:
     update_auth_webauthn_start_path = "/v1/auth/webauthn/update/start"
     update_auth_webauthn_finish_path = "/v1/auth/webauthn/update/finish"
 
+    # password
+    sign_up_password_path = "/v1/auth/password/signup"
+    sign_in_password_path = "/v1/auth/password/signin"
+    send_reset_password_path = "/v1/auth/password/reset"
+    update_password_path = "/v1/auth/password/update"
+    replace_password_path = "/v1/auth/password/replace"
+    password_policy_path = "/v1/auth/password/policy"
+
 
 class EndpointsV2:
     public_key_path = "/v2/keys"

descope/descope_client.py

@@ -7,6 +7,7 @@
 from descope.authmethod.magiclink import MagicLink  # noqa: F401
 from descope.authmethod.oauth import OAuth  # noqa: F401
 from descope.authmethod.otp import OTP  # noqa: F401
+from descope.authmethod.password import Password  # noqa: F401
 from descope.authmethod.saml import SAML  # noqa: F401
 from descope.authmethod.totp import TOTP  # noqa: F401
 from descope.authmethod.webauthn import WebAuthn  # noqa: F401
@@ -35,6 +36,7 @@ def __init__(
         self._otp = OTP(auth)
         self._totp = TOTP(auth)
         self._webauthn = WebAuthn(auth)
+        self._password = Password(auth)
 
     @property
     def mgmt(self):
@@ -72,6 +74,10 @@ def saml(self):
     def webauthn(self):
         return self._webauthn
 
+    @property
+    def password(self):
+        return self._password
+
     def validate_permissions(self, jwt_response: dict, permissions: List[str]) -> bool:
         """
         Validate that a jwt_response has been granted the specified permissions.