MFA token config flow

README.md

@@ -1,10 +1,10 @@
 [![buy me a coffee](https://img.shields.io/badge/If%20you%20like%20it-Buy%20us%20a%20coffee-green.svg?style=for-the-badge)](https://www.buymeacoffee.com/leighcurran)
 [![hacs_badge](https://img.shields.io/badge/HACS-Custom-orange.svg?style=for-the-badge)](https://github.com/custom-components/hacs)
-![Maintenance](https://img.shields.io/maintenance/yes/2022.svg?style=for-the-badge)
+![Maintenance](https://img.shields.io/maintenance/yes/2025.svg?style=for-the-badge)
 
 # Aurora+ for Home Assistant
 
-The Aurora+ integration adds support for retriving data from the Aurora+ API such as:
+The Aurora+ integration adds support for retrieving data from the Aurora+ API such as:
 
 - EstimatedBalance - This is shown in the Aurora+ app as 'Balance'
 - UsageDaysRemaining - This is shown in the Aurora+ app as 'Days Prepaid'
@@ -16,20 +16,58 @@ The Aurora+ integration adds support for retriving data from the Aurora+ API suc
 - NumberOfUnpaidBills
 - BillOverDueAmount
 
+It also uses https://github.com/ldotlopez/ha-historical-sensor/ to fetch hourly
+usage from the previous day, and make it available for the Energy dashboard:
+
+- Dollar Value Usage (Total and per-Tariff)
+- Kilowatt Hour Usage (Total and per-Tariff)
+
 Note: To use the Aurora+ integration you need a valid account with Aurora.
 
 ## Configuration
-Using *YAML*: add `auroraplus` platform to your sensor configuration in `configuration.yaml`. Example:
-
-```yaml
-# Example configuration.yaml entry
-sensor:
-  - platform: auroraplus
-    name: "Power Sensor"
-    username: [email protected]
-    password: Password
-    scan_interval:
-      hours: 2
-    rounding: 1
-```
-Note: Name, scan_interval and rounding are optional. If scan_interval is not set a default value of 1 hours will be used. If rounding is not set a default value of 2 will be used. Most Aurora+ data is updated daily.
+
+This integration uses Home Assistant's config flow. Simply go to `Settings` /
+`Devices & Services`, choose `Add Integration`, and search for `Aurora+`.
+
+In the configuration dialog, you need to input an OAuth access key, which allows
+access to your account's data without MFA. Authentication and API access is done
+via https://github.com/shtrom/AuroraPlus/tree/oauth-mfa-token, which you can
+also use to obtain the ID token.
+
+The easiest way to get a fresh token is to use [this
+page](https://shtrom.github.io/AuroraPlus/)). Follow the instructions to login
+to AuroraPlus and provide the URL of the error page to obtain an `id_token`
+suitable to bootstrap authentication in HA.
+
+If you'd prefer not to trust a random page on the web with your AuroraPlus
+credentials, you can also obtain the token locally.  On any machine able to run
+Python (not necessarily your Home Assistant server), install the AuroraPlus
+Python module from the URL above. You can then follow the instructions at
+https://github.com/shtrom/AuroraPlus/tree/oauth-mfa-token?tab=readme-ov-file#obtain-a-token.
+
+Essentially, just run
+
+   aurora_get_token
+
+and follow the instructions (open link, enter MFA, copy URL of error page back).
+
+## CAVEATs
+
+1. The Aurora+ API doesn't deliver real-time metering, so the data for current
+   usage will always be unavailable. It only provides updates containing data
+   for the previous day, in daily batches. Those batches may not be available
+   until late the next day, leading to a lag of 1 to 2 days in the energy
+   dashboard.
+
+2. Upon adding the integration, only tariffs with readings on the previous
+   week will be available to add to the energy dashboard. This could be
+   an issue if the plan was just changed. Sensors for the new tariffs won't
+   show up. Simply restart Home Assistant the next week for new sensors to
+   be created.
+
+3. Upon reauthenticating, a bunch of SQLAlchemyError will prop up in the logs.
+   They are currently believed to be harmless, and stop happening after a
+   restart.
+
+4. Support for multiple services is not complete, and would rely on matching
+   functionality not available in the Python library yet.

custom_components/auroraplus/__init__.py

@@ -1 +1,45 @@
-"""The auroraplus sensor integration."""
+"""The auroraplus sensor integration."""
+
+import logging
+
+from homeassistant.exceptions import (
+    ConfigEntryNotReady,
+    PlatformNotReady,
+)
+
+
+from .api import aurora_init
+from .const import CONF_TOKEN, CONF_ID_TOKEN, DOMAIN
+from .coordinator import AuroraPlusCoordinator
+
+_LOGGER = logging.getLogger(__name__)
+
+
+async def async_setup_entry(hass, entry):
+    """Set up entry."""
+    hass.data.setdefault(DOMAIN, {})
+    hass.data[DOMAIN][entry.entry_id] = dict(entry.data)
+
+    id_token = entry.data.get(CONF_ID_TOKEN)
+    token = entry.data.get(CONF_TOKEN)
+
+    try:
+        api = await hass.async_add_executor_job(aurora_init, token, id_token)
+    except OSError as err:
+        raise PlatformNotReady("Connection to Aurora+ failed") from err
+
+    entry.async_on_unload(
+        entry.add_update_listener(AuroraPlusCoordinator.update_listener)
+    )
+
+    entry.runtime_data = AuroraPlusCoordinator(hass, entry, api)
+
+    if not (
+        hasattr(entry.runtime_data, "week")
+        and entry.runtime_data.week.get("TariffTypes")
+    ):
+        raise ConfigEntryNotReady("No tariffs in returned data, yet")
+
+    await hass.config_entries.async_forward_entry_setups(entry, ["sensor"])
+
+    return True

custom_components/auroraplus/api.py

@@ -0,0 +1,38 @@
+import logging
+
+from auroraplus import AuroraPlusApi, AuroraPlusAuthenticationError
+from requests.exceptions import HTTPError
+
+from homeassistant.exceptions import (
+    ConfigEntryAuthFailed,
+)
+
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def aurora_init(
+    token: dict = {},
+    id_token: str | None = None,
+    access_token: str | None = None,
+):
+    _LOGGER.debug(f"aurora_init {token=} {id_token=} {access_token=}")
+    try:
+        api = AuroraPlusApi(token=token, id_token=id_token, access_token=access_token)
+
+        # We need this data in AuroraPlusCoordinator.__init__so we have the
+        # serviceAgreementID, preiseAddress, and tariffs over the previous
+        # week however HomeAssistant is not happy if the calls are made there.
+
+        api.get_info()
+        api.getweek()
+
+    except AuroraPlusAuthenticationError as e:
+        raise ConfigEntryAuthFailed("authentication failure on init") from e
+    except HTTPError as e:
+        status_code = e.response.status_code
+        if status_code in [401, 403]:
+            raise ConfigEntryAuthFailed("authentication failure on init") from e
+        raise e
+
+    return api

custom_components/auroraplus/config_flow.py

@@ -1,8 +1,109 @@
+import logging
+from typing import Any
+
+import homeassistant.helpers.config_validation as cv
 from homeassistant import config_entries
-from .const import DOMAIN
+from homeassistant.const import (
+    CONF_ACCESS_TOKEN,
+)
+from homeassistant.exceptions import ConfigEntryAuthFailed
+
+
+import voluptuous as vol
+
+from .api import aurora_init
+from .const import (
+    CONF_ID_TOKEN,
+    CONF_SERVICE_AGREEMENT_ID,
+    CONF_TOKEN,
+    DOMAIN,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+# PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend(
+AUTH_SCHEMA = vol.Schema(
+    {
+        vol.Required(CONF_ID_TOKEN): cv.string,
+    }
+)
 
 
 class AuroraPlusConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
     """AuroraPlus config flow."""
 
+    VERSION = 0
+    MINOR_VERSION = 1
+    reauth_entry = None
+
+    async def async_step_user(self, user_input: dict[str, Any] | None = None):
+        return await self._configure(user_input)
+
+    async def _configure(self, user_input: dict[str, Any] | None = None):
+        """
+        Get id_token from the user, and create a new service.
+
+        If self.reauth_entry is set, this entry will be updated instead.
+
+        """
+        errors = {}
+        if user_input is not None:
+            id_token = user_input.get(CONF_ID_TOKEN)
+            try:
+                api = await self.hass.async_add_executor_job(aurora_init, {}, id_token)
+                address = api.premiseAddress
+                await self.async_set_unique_id(api.serviceAgreementID)
+
+                if self.reauth_entry:
+                    self.hass.config_entries.async_update_entry(
+                        self.reauth_entry,
+                        data={
+                            CONF_ACCESS_TOKEN: None,
+                            CONF_ID_TOKEN: id_token,
+                            CONF_SERVICE_AGREEMENT_ID: api.serviceAgreementID,
+                            CONF_TOKEN: None,
+                        },
+                    )
+                    await self.hass.config_entries.async_reload(
+                        self.reauth_entry.entry_id
+                    )
+                    return self.async_abort(reason="reauth_successful")
+
+                else:
+                    return self.async_create_entry(
+                        title=address,
+                        data={
+                            CONF_ACCESS_TOKEN: None,
+                            CONF_ID_TOKEN: id_token,
+                            CONF_SERVICE_AGREEMENT_ID: api.serviceAgreementID,
+                            CONF_TOKEN: None,
+                        },
+                    )
+
+            except ConfigEntryAuthFailed:
+                errors = {
+                    "base": "auth",
+                }
+
+        return self.async_show_form(
+            step_id="user",
+            data_schema=AUTH_SCHEMA,
+            errors=errors,
+        )
+
+    async def async_step_reauth(self, user_input=None):
+        """Perform reauth upon an API authentication error."""
+        self.reauth_entry = self.hass.config_entries.async_get_entry(
+            self.context["entry_id"]
+        )
+        return await self.async_step_reauth_confirm()
+
+    async def async_step_reauth_confirm(self, user_input=None):
+        """Dialog that informs the user that reauth is required."""
+        if user_input is None:
+            return self.async_show_form(
+                step_id="reauth_confirm",
+                data_schema=vol.Schema({}),
+            )
 
+        return await self.async_step_user()

custom_components/auroraplus/const.py

@@ -0,0 +1,28 @@
+import datetime
+
+DOMAIN = "auroraplus"
+
+CONF_TOKEN = "token"
+CONF_ID_TOKEN = "id_token"
+CONF_SERVICE_AGREEMENT_ID = "service_agreement_id"
+CONF_ROUNDING = "rounding"
+
+SENSOR_ESTIMATEDBALANCE = 'Estimated Balance'
+SENSOR_DOLLARVALUEUSAGE = 'Dollar Value Usage'
+SENSOR_KILOWATTHOURUSAGE = 'Kilowatt Hour Usage'
+SENSOR_KILOWATTHOURUSAGETARIFF = 'Kilowatt Hour Usage Tariff'
+SENSOR_DOLLARVALUEUSAGETARIFF = 'Dollar Value Usage Tariff'
+
+SENSORS_MONETARY = [
+    SENSOR_ESTIMATEDBALANCE,
+    SENSOR_DOLLARVALUEUSAGE,
+]
+
+
+POSSIBLE_MONITORED = SENSORS_MONETARY + [SENSOR_KILOWATTHOURUSAGE]
+
+DEFAULT_MONITORED = POSSIBLE_MONITORED
+
+DEFAULT_ROUNDING = 2
+DEFAULT_SCAN_INTERVAL = datetime.timedelta(hours=1)
+