[Change] Switch authent to use a pre-granted refresh token

Author: philippelt

.netatmo.credentials

@@ -1,7 +1,6 @@
 {
     "CLIENT_ID" : "",
     "CLIENT_SECRET" : "",
-    "USERNAME" : "",
-    "PASSWORD" : ""
+    "REFRESH_TOKEN" : ""
 }
 

README.md

@@ -13,8 +13,11 @@ If you are using a single account with a single home and single weather station,
 If you have multiple homes or were supplying a station name in some method calls, you will have to adapt your code :
  - to supply a home name when looking for data for most class initializers
  - to use the new station name set by Netatmo (which is not your previously set value)
+   
+  
+>BREAKING CHANGE: Netatmo seems no longer (july 2023) to allow grant_type "password", even for an app credentials that belong to the same account than the home. They have added the capability of creating access_token/refresh_token couple from the dev page (the location where app are created). As a consequence, the username/password credentials can no longer be used and you must replace them with a new parameter REFRESH_TOKEN that you will get from the web interface. To get this token, you are required to specify the scope you want to allow to this token. Select all that apply for your library use.
 
->Note: Authentication tokens obtained using ClientAuth will always expires after 3 hours. If you are using long lasting sessions, you must renew this tokens by calling again ClientAuth periodically.
+>SHORT VERSION TO UPGRADE: If you where using a netatmo_credentials file, juste remove USERNAME and PASSWORD fields and add a REFRESH_TOKEN field which value is the one you will obtain from the https://dev.netatmo.com in MyApps selecting you app and using "Token Generator" after selecting required scopes.
 
 ### Install ###
 

lnetatmo.py

@@ -45,19 +45,16 @@
 # Authentication use :
 #  1 - Values hard coded in the library
 #  2 - The .netatmo.credentials file in JSON format in your home directory
-#  3 - Values defined in environment variables : CLIENT_ID, CLIENT_SECRET, USERNAME, PASSWORD
-#      Note: The USERNAME environment variable may interfer with the envvar used by Windows for login name
-#            if you have this issue, do not forget to "unset USERNAME" before running your program
+#  3 - Values defined in environment variables : CLIENT_ID, CLIENT_SECRET, REFRESH_TOKEN
 
 # Each level override values defined in the previous level. You could define CLIENT_ID and CLIENT_SECRET hard coded in the library
-# and username/password in .netatmo.credentials or environment variables
+# and REFRESH_TOKEN in .netatmo.credentials or environment variables
 
 # 1 : Embedded credentials
 cred = {                           # You can hard code authentication information in the following lines
-        "CLIENT_ID" :  "",         #   Your client ID from Netatmo app registration at http://dev.netatmo.com/dev/listapps
+        "CLIENT_ID" :  "",         #   Your client ID from Netatmo app registration at http://dev.netatmo.com
         "CLIENT_SECRET" : "",      #   Your client app secret   '     '
-        "USERNAME" : "",           #   Your netatmo account username
-        "PASSWORD" : ""            #   Your netatmo account password
+        "REFRESH_TOKEN" : ""       #   Your scoped refresh token (generated with app credentials)
         }
 
 # Other authentication setup management (optionals)
@@ -73,17 +70,9 @@ def getParameter(key, default):
         cred.update({k.upper():v for k,v in json.loads(f.read()).items()})
 
 # 3 : Override final value with content of env variables if defined
-#     Warning, for Windows user, USERNAME contains by default the windows logged user name
-#     This usually lead to an authentication error
-if platform.system() == "Windows" and getenv("USERNAME", None):
-    warnings.warn("You are running on Windows and the USERNAME env var is set. " \
-                  "Be sure this env var contains Your Netatmo username " \
-                  "or clear it with <SET USERNAME=> before running your program\n", RuntimeWarning, stacklevel=3)
-
 _CLIENT_ID     = getParameter("CLIENT_ID", cred)
 _CLIENT_SECRET = getParameter("CLIENT_SECRET", cred)
-_USERNAME      = getParameter("USERNAME", cred)
-_PASSWORD      = getParameter("PASSWORD", cred)
+_REFRESH_TOKEN = getParameter("REFRESH_TOKEN", cred)
 
 #########################################################################
 
@@ -174,56 +163,38 @@ class ClientAuth:
     Args:
         clientId (str): Application clientId delivered by Netatmo on dev.netatmo.com
         clientSecret (str): Application Secret key delivered by Netatmo on dev.netatmo.com
-        username (str)
-        password (str)
-        scope (Optional[str]): Default value is 'read_station'
-            read_station: to retrieve weather station data (Getstationsdata, Getmeasure)
-            read_camera: to retrieve Welcome data (Gethomedata, Getcamerapicture)
-            access_camera: to access the camera, the videos and the live stream.
-            Several value can be used at the same time, ie: 'read_station read_camera'
+        refresh_token (str) : Scoped refresh token
     """
 
     def __init__(self, clientId=_CLIENT_ID,
                        clientSecret=_CLIENT_SECRET,
-                       username=_USERNAME,
-                       password=_PASSWORD,
-                       scope="read_station read_camera access_camera write_camera " \
-                                 "read_presence access_presence write_presence read_thermostat write_thermostat"):
+                       refreshToken=_REFRESH_TOKEN):
 
-        postParams = {
-                "grant_type" : "password",
-                "client_id" : clientId,
-                "client_secret" : clientSecret,
-                "username" : username,
-                "password" : password,
-                "scope" : scope
-                }
-        resp = postRequest(_AUTH_REQ, postParams)
-        if not resp: raise AuthFailure("Authentication request rejected")
-
         self._clientId = clientId
         self._clientSecret = clientSecret
-        self._accessToken = resp['access_token']
-        self.refreshToken = resp['refresh_token']
-        self._scope = resp['scope']
-        self.expiration = int(resp['expire_in'] + time.time())
+        self._accessToken = None
+        self.refreshToken = refreshToken
+        self.expiration = 0 # Force refresh token
 
     @property
     def accessToken(self):
-
-        if self.expiration < time.time(): # Token should be renewed
-            postParams = {
-                    "grant_type" : "refresh_token",
-                    "refresh_token" : self.refreshToken,
-                    "client_id" : self._clientId,
-                    "client_secret" : self._clientSecret
-                    }
-            resp = postRequest(_AUTH_REQ, postParams)
-            self._accessToken = resp['access_token']
-            self.refreshToken = resp['refresh_token']
-            self.expiration = int(resp['expire_in'] + time.time())
+        if self.expiration < time.time() : self.renew_token()
         return self._accessToken
 
+    def renew_token(self):
+        postParams = {
+                "grant_type" : "refresh_token",
+                "refresh_token" : self.refreshToken,
+                "client_id" : self._clientId,
+                "client_secret" : self._clientSecret
+                }
+        resp = postRequest(_AUTH_REQ, postParams)
+        if self.refreshToken != resp['refresh_token']:
+            print("New refresh token:", resp['refresh_token'])
+        self._accessToken = resp['access_token']
+        self.refreshToken = resp['refresh_token']
+        self.expiration = int(resp['expire_in'] + time.time())
+
 
 class User:
     """
@@ -774,7 +745,7 @@ def postRequest(url, params=None, timeout=10):
         try:
             resp = urllib.request.urlopen(req, params, timeout=timeout) if params else urllib.request.urlopen(req, timeout=timeout)
         except urllib.error.HTTPError as err:
-            logger.error("code=%s, reason=%s" % (err.code, err.reason))
+            logger.error("code=%s, reason=%s, body=%s" % (err.code, err.reason, err.fp.read()))
             return None
     else:
         if params:
@@ -839,7 +810,7 @@ def getStationMinMaxTH(station=None, module=None, home=None):
 
     logging.basicConfig(format='%(name)s - %(levelname)s: %(message)s', level=logging.INFO)
 
-    if not _CLIENT_ID or not _CLIENT_SECRET or not _USERNAME or not _PASSWORD :
+    if not _CLIENT_ID or not _CLIENT_SECRET or not _REFRESH_TOKEN :
            stderr.write("Library source missing identification arguments to check lnetatmo.py (user/password/etc...)")
            exit(1)
 

setup.py

@@ -4,7 +4,7 @@
 
 setup(
     name='lnetatmo',
-    version='2.1.0',
+    version='3.0.0',
     classifiers=[
         'Development Status :: 5 - Production/Stable',
         'Intended Audience :: Developers',
@@ -17,7 +17,7 @@
     scripts=[],
     data_files=[],
     url='https://github.com/philippelt/netatmo-api-python',
-    download_url='https://github.com/philippelt/netatmo-api-python/tarball/v2.1.0.tar.gz',
+    download_url='https://github.com/philippelt/netatmo-api-python/archive/v3.0.0.tar.gz',
     license='GPL V3',
     description='Simple API to access Netatmo weather station data from any python script.'
 )

usage.md

@@ -13,13 +13,15 @@ Python Netatmo API programmers guide
 
 >2020-12-07, Breaking changes due to removal of direct access to devices, "home" being now required (Netatmo redesign)
 
+>2023-07-12, Breaking changes due to deprecation of grant_type "password" for ALL apps
+
 No additional library other than standard Python library is required.
 
 Both Python V2.7x and V3.x.x are supported without change.
 
 More information about the Netatmo REST API can be obtained from http://dev.netatmo.com/doc/
 
-This package support only user based authentication.
+This package support only preauthenticated scoped tokens created along apps.
 
 
 
@@ -32,6 +34,7 @@ Before being able to use the module you will need :
 
   * A Netatmo user account having access to, at least, one station
   * An application registered from the user account (see http://dev.netatmo.com/dev/createapp) to obtain application credentials.
+  * Create a couple access_token/refresh_token at the same time with your required scope (depending of your intents on library use)
 
 In the netatmo philosophy, both the application itself and the user have to be registered thus have authentication credentials to be able to access any station. Registration is free for both.
 
@@ -52,24 +55,19 @@ Authentication data can be supplied with 4 different methods (each method overri
         {
             "CLIENT_ID" : "`xxx",
             "CLIENT_SECRET" : "xxx",
-            "USERNAME" : "xxx",
-            "PASSWORD" : "xxx"
+            "REFRESH_TOKEN" : "xxx"
         }
         $
 
  3. Some or all values can be overriden by environment variables. This is the easiest method if your are packaging your application with Docker. It also allow you to do some testing with other accounts without touching your current ~/.netatmo.credentials file 
 
-        $ export USERNAME=newUsername
-        $ export PASSWORD=password
+        $ export REFRESH_TOKEN="yyy"
         $ python3 MyCodeUsingLnetatmo.py
         ...
         
-    **Note to windows users:**  
-      >  If you are running on Windows platform, take care to the **USERNAME** environment variable that is automatically set with the windows login user name. This is likely to conflict with the user name you are using for your Netatmo account and will result in an unexpected authentication failure. In such case, take care to "unset" the default **USERNAME** env variable before running your code (or set it with your actual Netatmo account ID).
-
  4. Some or all values can be overriden by explicit call to initializer of ClientAuth class  
 
-        # Example: USERNAME and PASSWORD supposed to be defined by one of the previous methods
+        # Example: REFRESH_TOKEN supposed to be defined by one of the previous methods
         authData = lnetatmo.ClientAuth( clientId="netatmo-client-id",
                                         clientSecret="secret" )
 
@@ -151,7 +149,7 @@ The results are Python data structures, mostly dictionaries as they mirror easil
 _CLIENT_ID, _CLIENT_SECRET = Application ID and secret provided by Netatmo
 application registration in your user account
 
-_USERNAME, _PASSWORD : Username and password of your netatmo account
+_REFRESH_TOKEN : Refresh token created along the app client credentials
 
 _BASE_URL and _*_REQ : Various URL to access Netatmo web services. They are
 documented in http://dev.netatmo.com/doc/ They should not be changed unless
@@ -169,9 +167,7 @@ Constructor
 ```python
     authorization = lnetatmo.ClientAuth( clientId = _CLIENT_ID,
                                          clientSecret = _CLIENT_SECRET,
-                                         username = _USERNAME,
-                                         password = _PASSWORD,
-                                         scope = "read_station"
+                                         refreshToken = _REFRESH_TOKEN,
                                         )
 ```
 
@@ -185,17 +181,9 @@ Return : an authorization object that will supply the access token required by o
 Properties, all properties are read-only unless specified :
 
   * **accessToken** : Retrieve a valid access token (renewed if necessary)
-  * **refreshToken** : The token used to renew the access token (normally should not be used)
+  * **refreshToken** : The token used to renew the access token (normally should not be used explicitely)
   * **expiration** : The expiration time (epoch) of the current token
-  * **scope** : The scope of the required access token (what will it be used for) default to read_station to provide backward compatibility.
 
-Possible values for scope are :
- - read_station: to retrieve weather station data (Getstationsdata, Getmeasure)
- - read_camera: to retrieve Welcome data (Gethomedata, Getcamerapicture)
- - access_camera: to access the camera, the videos and the live stream.
-
-Several value can be used at the same time, ie: 'read_station read_camera'
-
 
 
 #### 4-3 User class ####