feat: improve authentication flow based on same JavaScript flow

Author: GuyLewin

custom_components/lifetime_fitness/api.py

@@ -12,17 +12,47 @@
     API_AUTH_REQUEST_PASSWORD_JSON_KEY,
     API_AUTH_REQUEST_SUBSCRIPTION_KEY_HEADER,
     API_AUTH_REQUEST_SUBSCRIPTION_KEY_HEADER_VALUE,
-    API_AUTH_STATUS_JSON_KEY,
-    API_AUTH_STATUS_OK,
     API_AUTH_TOKEN_JSON_KEY,
+    API_AUTH_MESSAGE_JSON_KEY,
+    API_AUTH_STATUS_JSON_KEY,
     API_CLUB_VISITS_ENDPOINT_FORMATSTRING,
     API_CLUB_VISITS_ENDPOINT_DATE_FORMAT,
     API_CLUB_VISITS_AUTH_HEADER,
+    AuthenticationResults,
+    AUTHENTICATION_RESPONSE_MESSAGES,
+    AUTHENTICATION_RESPONSE_STATUSES
 )
 
 _LOGGER = logging.getLogger(__name__)
 
 
+def handle_authentication_response_json(response_json: dict):
+    # Based on https://my.lifetime.life/components/login/index.js
+    message = response_json.get(API_AUTH_MESSAGE_JSON_KEY)
+    status = response_json.get(API_AUTH_STATUS_JSON_KEY)
+    if message == AUTHENTICATION_RESPONSE_MESSAGES[AuthenticationResults.SUCCESS]:
+        return response_json[API_AUTH_TOKEN_JSON_KEY]
+    elif message == AUTHENTICATION_RESPONSE_MESSAGES[AuthenticationResults.PASSWORD_NEEDS_TO_BE_CHANGED]:
+        if API_AUTH_TOKEN_JSON_KEY in response_json:
+            _LOGGER.warning("Life Time password needs to be changed, but API can still be used")
+            return response_json[API_AUTH_TOKEN_JSON_KEY]
+        else:
+            raise ApiPasswordNeedsToBeChanged
+    elif (
+            status == AUTHENTICATION_RESPONSE_STATUSES[AuthenticationResults.INVALID] or
+            message == AUTHENTICATION_RESPONSE_MESSAGES[AuthenticationResults.INVALID]
+    ):
+        raise ApiInvalidAuth
+    elif status == AUTHENTICATION_RESPONSE_STATUSES[AuthenticationResults.TOO_MANY_ATTEMPTS]:
+        raise ApiTooManyAuthenticationAttempts
+    elif status == AUTHENTICATION_RESPONSE_STATUSES[AuthenticationResults.ACTIVATION_REQUIRED]:
+        raise ApiActivationRequired
+    elif status == AUTHENTICATION_RESPONSE_STATUSES[AuthenticationResults.DUPLICATE_EMAIL]:
+        raise ApiDuplicateEmail
+    _LOGGER.error("Received unknown authentication error in response: %s", response_json)
+    raise ApiUnknownAuthError
+
+
 class Api:
     def __init__(self, hass, username: str, password: str) -> None:
         self._username = username
@@ -49,18 +79,12 @@ async def authenticate(self):
                 },
             ) as response:
                 response_json = await response.json()
-                if (
-                        API_AUTH_STATUS_JSON_KEY not in response_json
-                        or response_json[API_AUTH_STATUS_JSON_KEY] != API_AUTH_STATUS_OK
-                ):
-                    _LOGGER.error("Received invalid authentication response: %s", response_json)
-                    raise ApiInvalidAuth
-                self._sso_token = response_json[API_AUTH_TOKEN_JSON_KEY]
+                self._sso_token = handle_authentication_response_json(response_json)
         except ClientResponseError as err:
             if err.status == HTTPStatus.UNAUTHORIZED:
-                _LOGGER.exception("Received invalid authentication status: %d", err.status)
                 raise ApiInvalidAuth
-            raise err
+            _LOGGER.error("Received unknown status code in authentication response: %d", err.status)
+            raise ApiUnknownAuthError
         except ClientConnectionError:
             _LOGGER.exception("Connection error while authenticating to Life Time API")
             raise ApiCannotConnect
@@ -106,10 +130,30 @@ class ApiCannotConnect(Exception):
     """Client can't connect to API server"""
 
 
+class ApiPasswordNeedsToBeChanged(Exception):
+    """Password needs to be changed"""
+
+
+class ApiTooManyAuthenticationAttempts(Exception):
+    """There were too many authentication attempts"""
+
+
+class ApiActivationRequired(Exception):
+    """Account activation required"""
+
+
+class ApiDuplicateEmail(Exception):
+    """There are multiple accounts associated with this email"""
+
+
 class ApiInvalidAuth(Exception):
     """API server returned invalid auth"""
 
 
+class ApiUnknownAuthError(Exception):
+    """API server returned unknown error"""
+
+
 class ApiAuthRequired(Exception):
     """This API call requires authenticating beforehand"""
 

custom_components/lifetime_fitness/config_flow.py

@@ -1,7 +1,6 @@
 """Config flow for Life Time Fitness integration."""
 from __future__ import annotations
 
-from collections import OrderedDict
 import logging
 from typing import Any
 
@@ -96,8 +95,18 @@ async def async_step_user(
             info = await validate_input(self.hass, user_input)
         except CannotConnect:
             errors["base"] = "cannot_connect"
+        except PasswordNeedsToBeChanged:
+            errors["base"] = "password_needs_to_be_changed"
+        except TooManyAuthenticationAttempts:
+            errors["base"] = "too_many_authentication_attempts"
+        except ActivationRequired:
+            errors["base"] = "activation_required"
+        except DuplicateEmail:
+            errors["base"] = "duplicate_email"
         except InvalidAuth:
             errors["base"] = "invalid_auth"
+        except UnknownAuthError:
+            errors["base"] = "unknown_auth_error"
         except Exception:  # pylint: disable=broad-except
             _LOGGER.exception("Unexpected exception")
             errors["base"] = "unknown"
@@ -118,5 +127,25 @@ class CannotConnect(HomeAssistantError):
     """Error to indicate we cannot connect."""
 
 
+class PasswordNeedsToBeChanged(HomeAssistantError):
+    """Error to indicate there the password needs to be changed."""
+
+
+class TooManyAuthenticationAttempts(HomeAssistantError):
+    """Error to indicate there were too many authentication attempts."""
+
+
+class ActivationRequired(HomeAssistantError):
+    """Error to indicate that account activation is required."""
+
+
+class DuplicateEmail(HomeAssistantError):
+    """Error to indicate there are multiple accounts associated with this email."""
+
+
+class UnknownAuthError(HomeAssistantError):
+    """Error to indicate server returned unexpected authentication error."""
+
+
 class InvalidAuth(HomeAssistantError):
     """Error to indicate there is invalid auth."""

custom_components/lifetime_fitness/const.py

@@ -1,4 +1,5 @@
 """Constants for the Life Time Fitness integration."""
+import enum
 
 DOMAIN = "lifetime_fitness"
 VERSION = "0.0.0-dev"  # Updated by release workflow
@@ -27,8 +28,8 @@
 API_AUTH_REQUEST_USERNAME_JSON_KEY = "username"
 API_AUTH_REQUEST_PASSWORD_JSON_KEY = "password"
 API_AUTH_TOKEN_JSON_KEY = "ssoId"
+API_AUTH_MESSAGE_JSON_KEY = "message"
 API_AUTH_STATUS_JSON_KEY = "status"
-API_AUTH_STATUS_OK = "0"
 
 API_CLUB_VISITS_ENDPOINT_FORMATSTRING = \
     "https://myaccount.lifetimefitness.com/myaccount/api/member/clubvisits?end_date={end_date}&start_date={start_date}"
@@ -45,3 +46,25 @@
 ATTR_VISITS_THIS_MONTH = "visits_this_month"
 ATTR_VISITS_THIS_WEEK = "visits_this_week"
 ATTR_LAST_VISIT_TIMESTAMP = "last_visit_timestamp"
+
+
+class AuthenticationResults(enum.Enum):
+    SUCCESS = 0
+    PASSWORD_NEEDS_TO_BE_CHANGED = 1
+    INVALID = 2
+    TOO_MANY_ATTEMPTS = 3
+    ACTIVATION_REQUIRED = 4
+    DUPLICATE_EMAIL = 5
+
+
+AUTHENTICATION_RESPONSE_MESSAGES = {
+    AuthenticationResults.SUCCESS: "Success",
+    AuthenticationResults.PASSWORD_NEEDS_TO_BE_CHANGED: "Password needs to be changed.",
+    AuthenticationResults.INVALID: "Invalid username or password"
+}
+AUTHENTICATION_RESPONSE_STATUSES = {
+    AuthenticationResults.INVALID: "-201",
+    AuthenticationResults.TOO_MANY_ATTEMPTS: "-207",
+    AuthenticationResults.ACTIVATION_REQUIRED: "-208",
+    AuthenticationResults.DUPLICATE_EMAIL: "-209"
+}

custom_components/lifetime_fitness/strings.json

@@ -12,7 +12,12 @@
     },
     "error": {
       "cannot_connect": "[%key:common::config_flow::error::cannot_connect%]",
+      "password_needs_to_be_changed": "[%key:common::config_flow::error::password_needs_to_be_changed%]",
+      "too_many_authentication_attempts": "[%key:common::config_flow::error::too_many_authentication_attempts%]",
+      "activation_required": "[%key:common::config_flow::error::activation_required%]",
+      "duplicate_email": "[%key:common::config_flow::error::duplicate_email%]",
       "invalid_auth": "[%key:common::config_flow::error::invalid_auth%]",
+      "unknown_auth_error": "[%key:common::config_flow::error::unknown_auth_error%]",
       "unknown": "[%key:common::config_flow::error::unknown%]"
     }
   },

custom_components/lifetime_fitness/translations/en.json

@@ -2,7 +2,12 @@
     "config": {
         "error": {
             "cannot_connect": "Failed to connect",
+            "password_needs_to_be_changed": "Password needs to be changed",
+            "too_many_authentication_attempts": "Too many attempts, your account has been locked",
+            "activation_required": "Account activation via email required",
+            "duplicate_email": "Your email is associated with more than one account. Please login with your username or member #",
             "invalid_auth": "Invalid authentication",
+            "unknown_auth_error": "Unexpected error status received from API. Check Home Assistant logs for more details and contact the developer",
             "unknown": "Unexpected error"
         },
         "step": {