core: Enphase API Security Update breaks integration
The problem
My Enphase Envoy integration stopped working yesterday evening (2/28). While diagnosing the issue, I noticed that Emphase had sent an email titled “Security enhancements to Enphase IQ Gateway API” announcing some security updates being rolled out. I’ve included most of the email I received below for reference, but they did include a link to updated API Documentation Here.
It appears that these changes are being applied automatically and are breaking the existing API integration for Home Assistant.
What version of Home Assistant Core has the issue?
Home Assistant 2023.2.3
What was the last working version of Home Assistant Core?
No response
What type of installation are you running?
Home Assistant OS
Integration causing the issue
Enphase Envoy
Link to integration documentation on our website
https://www.home-assistant.io/integrations/enphase_envoy
Diagnostics information
home-assistant_enphase_envoy_2023-03-01T17-27-15.663Z.log
Example YAML snippet
No response
Anything in the logs that might be useful for us?
2023-03-01 08:05:18.744 WARNING (MainThread) [homeassistant.config_entries] Config entry 'Envoy 202202141489' for enphase_envoy integration not ready yet: Error communicating with API: All connection attempts failed; Retrying in background
2023-03-01 08:15:24.975 ERROR (MainThread) [homeassistant.components.enphase_envoy] Unexpected error fetching envoy Envoy 202202141489 data: Could not connect or determine Envoy model. Check that the device is up at 'http://192.168.211.16'.
Additional information
The email included: At Enphase, we take security seriously. We want to ensure that all customers and stakeholders have access to the most secure and reliable operating environment possible.
We’ll be updating the API security protocols associated with the software running on the IQ Gateway, and we’re writing to share information about these changes with all Enphase homeowners, installers, software developers, and partners who may be affected.
These updates have begun propagating across accounts and will continue to roll out over time to all accounts. If you’re creating, using, or maintaining custom monitoring software that relies on interactions with IQ Gateway local interfaces, formally known as Envoy, this critical information will require your review and potential action.
Here is a summary of the changes that will go into effect with release 07.03.120 and higher: • Added a new capability to generate and authenticate secure access tokens via web UI to secure all custom applications and API calls. • Documentation now includes examples of how to use URLs to get tokens programmatically using shell script-based or Python-based methods. • Revised documentation also explains how to connect securely using the updated IQ Gateway local UI and/or IQ Gateway APIs.
About this issue
- Original URL
- State: closed
- Created a year ago
- Reactions: 10
- Comments: 153 (63 by maintainers)
For those that want to test I’ve packaged the new code as a custom integration that can be installed with HACS. As it is sourced from @briancmpbll repository that is currently actively maintained by @posixx, this test version is slightly behind that one and differs from it by all changes needed to let it pass all the HA Core code Linting and pre-commit tests. There’s also some other features added from @vincentwolsink repository.
FYI, The BeautifulSoup has been replaced and @posixx 3 phase support is now migrated as well, but untested as I have no 3phase. Now working on some more recent changes to migrate.
@sophof my fork is here – it still fails some pre-commit hooks from home-assistant
https://github.com/mbeijen/home-assistant/tree/enphase-envoy-v7-firmware-support
I more or less took the HACS version and tried to ‘massage’ it into Home Assistant core ‘proper’. It works for me, however they use a few non-standard ways of doing stuff – they use the BeautifulSoup library which is not used in other integrations except for the ‘scrape’ integration. So I’d want to port this over to more ‘normal’ ways of Home Assistant programming before submitting the work. However due to ‘summer’ I’ll have no possibility to work on this in the upcoming 4 weeks. If anyone else will want to have a go in the mean time, please do!
Hi there, I just got an Enphase system installed last week and modified Home Assistant to get it working. I can also take over and contribute my changes upstream?
I am a software developer but so far have not contributed to Home Assistant yet. I’ve just dropped Greg a mail asking if he would be able or willing to review contributions from my side.
With the closure of this issue and upcoming updated Enphase Envoy in HA Core, work in the Envoy_2_Core_custom_test repo has been stopped. Repository remains available for now but no changes will be applied.
For those of you that need to continue using a custom integration and were using Envoy_2_Core_custom_test may switch over to @briancmpbll 's repository. All changes made since Envoy_2_Core was forked from @briancmpbll 's one are now in PR offered back, but not yet applied. A test version with all applied changes can be loaded using HACS from https://github.com/catsmanac/home_assistant_custom_envoy. Same concept as with Envoy_2_Core_Test, it’s trying/testing until PR are merged. This test one now contains same functionaity as latest release of Envoy_2_core_test
FYI: Got my HA Core dev environment going. Now working on removing BS4 / BeautifulSoup as that is in the no-go zone of HA Core and fails checks. 3phase was added by @posixx to the @briancmpbll custom integration but still needs to be added here.
This is an open source project, work is not limited to be done by certain people, anyone can contribute. Feel free to jump in and fix/improve the situation.
…/Frenck
I just tested my 3 Envoys (1 legacy, 2 IQ) with 0.2.7 and it looks fine so far.
I’ve just published 0.2.1 of the work in custom integration format for testing. This ‘probably’ works with legacy models too. It includes the fixes done in the @briancmpbll custom integration for legacy model and those were tested with 1 model but not yet by another model so verdict pending. This version also includes the most recent PR by @posixx and myself.
@mbeijen, @sophof PR6 contains all commits, so 1-5 may be skipped.
What’s pending:
Also waiting on an update to the official integration, as I really don’t want to have to setup HACS just for this
Ok, found the issue. Somewhere in the course of the updates, sending the username and password to the envoy inverters webpage was dropped as new firmware used this token stuff and the legacy Envoy doesn’t have this page. But ENVOY-S with old firmware still does.
Still have to work on updating the github, that will be tomorrow, but if you want to try the fix download this file and make it a .py file again and copy it to config/custom_components/enphase_envoy on your HA system, best safe the original one there first. Then cycle HA. Provided it’s still 0.2.8 there. envoy_reader.py.txt
I can confirm that this fixed it for me.
Thanks for your advice @joostlek, I’ve never contributed to HA Core, just to custom integrations, so I’m blank on this. The story is that @mbeijen forked HA Core and pulled the @briancmpbll custom integration into his branch enphase-envoy-v7-fw-support and started first work to meet HA pre-commit tests. I forked from his repo as he went on vacation and added the PR applied to @briancmpbll after his pull and more changes to meet pre-commit tests.
So splitting is probably needed, but since it’s in @mbeijen repo is used I’m not sure how to persue this. Assume his plan was to start working on this when he’s back from vacation.
As for testing, excellent idea, but still have to dive into that subject, any help appreciated.
As for the translations, that would be great, no idea how that’s done and how to start it.
Current version is close to ready, aside from a legacy issue and testing.
I can confirm that it works for me with the following situation:
Situation about energy dashboard and entity’s are exactly the same as @JayKuswahey (as expected)
All looks to be fine so far. Wil check further and report if/when I find issues.
@catsmanac thank you very much for working on this issue.
@catsmanac I added version
0.2.1to my install and can say that I indeed have data again with ‘Enphase IQ Gateway S-Standard’ (formerly known as ‘Envoy S’) since a couple hours.It’s not posting on the main or energy dashboard yet, that usually take a couple of hours, but the sensors are populated again, with identical Identity IDs as with the old core install.
edit 1: added more information like rosiaantje did
edit 2: 8 hours later still no data on dashboards. Might have to do something manually? I know I saw someone posting on having to update entities to not lose historic data?
Anyway, I went to Settings -> Devices & Services -> Enphase Envoy (Dev-2-Core) click on “1 device” -> click on link “Enphase Envoy (Dev-2-Core)” in “Device Info” card -> Click on “14 entities” (changes depending on how many converters you have) under “Devices” -> Click on any line -> Click on the cogwheel top right corner of the card -> Change the “name” and “Entity ID” to what it used to be.
In my case, I had to change "envoy
serialnumberinverter_122123059299" back into “envoy_inverter_122123059299”However, when done, I noticed the following in my docker logs:
So, I guess I made things worse… I gave things identical names, but they still don’t align on the energy dashboard due to different IDs in the database. I suppose I’m halfway there, either rename IDs or alter the dashboard to use different IDs, but I need a push in the right direction.
edit 3: Okay, so I think I have it fixed. Apologies if this is not the right spot to document it, but I feel it’s appropriate?
With the new integration instalment you get new sensors, which you can then rename to the previous names, apparently you can ignore the unique constraint errors. When the names changed, the main dashboard immediately updates, so the values are successfully read.
However, the energy dashboard will still be looking at the old sensor, and thus not update. You need to go into Settings -> Dashboard -> click the Energy dashboard name -> click “Add Solar Production” -> Select the new lifetime producer (and delete the old one. Within a couple hours the graph should be populated again with generated solar power.
This is in my case resulted in having a negative 7067 kwh solar production! This kind of makes sense in hindsight, as it’s a new sensor and therefore starts counting from 0 again. But seeing it’s the same sensor name as previously you’ll get a difference of the total production of the previous sensor…
Using an old topic as basis I fixed it like this:
STOP Home Assistant and MAKE A BACKUP!!
After starting HA again, the graph on the Energy Dashboard is now fine again, with a HUGE spike on yesterday, as July was a sunny month and it’s the total of some 19 days… Hope this helps!!
Pinging @catsmanac @rosiaantje so they are aware of my edits
I experienced this when I installed my first custom integration manually not using HACS. After I unzipped it created all the files, but the folder had the name of the custom install and not the domain name. Check if your files are installed in config/custom_components/enphase_envoy and not config/custom_components/envoy_2_core_custom_test or something else.
Other option is missing or old language files in the translations folder.
I’ve also seen unexpected text when forgetting to hit CTRL-F5 to refresh browser cache. When switching between integrations without CTRL-F5 you may still see form or text of previous one.
A 257 commit PR would be a pain to review ! As it was mentioned before it would be better to break it in smaller PR.
The rebase is actually for your changes not for the changes in core. A rebase will take the latest code from the master branch ( what you call the recent changes in core ), and then apply your changes on top of it. It’s a way to make sure your changes depend on what’s has already be done, it will also make merging your changes back into the master branch easier. For a more detailed explanation : https://www.atlassian.com/git/tutorials/rewriting-history/git-rebase
The token sits in the authorization header of each request but is not checked each time. When 401 Authorization failure occurs, authorization and new cookie is requested using the jwt page of the envoy using the token. This occurs at each HA restart or reload. If the token has expired a new one is requested from Enphase and that is then used for new jwt authorization and cookie and in the authorization header. The debug log shows something is in the authorization header or not for each request, but this does not imply that the authorization with the jwt page is done.
Example at startup/reload below where you see the authorization cycle at first failure and a next one
So unless you are seeing multiple occurrences of ‘Received 401 from Envoy’ it is expected behavior.
This is the original design by @DanBeard that was the starting point for @briancmpbll further development with recent adds by @posixx before it became the starting point for @mbeijen update of core that we are now all looking at. This method has not changed in that time. Not sure if authorization header needs to be send each time or if it would have negative impact, but it seems to work fine.
v 0.2.8 looks good for me. Everything reporting as expected after an update two hours ago
Home Assistant 2023.8.0 Supervisor 2023.07.1 Operating System 10.3 Frontend 20230802.0 - latest Envoy Firmware: D7.6.175 Envoy S Metered
I’ll see how it goes over the next 24 hours to check for the dropouts I mentioned in another thread. On v 0.2.6 it became unavailable this morning at 06:40 for 2 minutes.
Working great for me: v. 0.2.8 Firmware D7. 3.130 IQ Gateway X-IQ-AM1-240-4 HA 2023.8.0
HACS v0.2.8 is working for me 🎉
Home Assistant 2023.8.0 Supervisor 2023.07.1 Operating System 10.3 Envoy Firmware: D7.6.175 System: Envoy-S-Metered-EU
0.2.7 is released after testing the fix for legacy successful by @DMedina559 with ENVOY LCD / Legacy
Updated to v0.2.6 via HACS. Everything seems to be working fine on my system;
Envoy-S-Metered-EU, 3 Phase, with clamps, 20 solar panels SKU: ENV-S-WM-230 Firmware: D7.6.175
Updated successfully, no errors so far, entity
sensor.envoy_current_power_productionlast updated 27 seconds ago 👍🏼You need to clear your browser cache, because localization has not been refreshed properly, try a Ctrl + F5 combo (on windows at least)
It still works with with owner token too, but obviously you have less entities available, as some endpoints are not available for owner tokens, but all the general information is still available.
And yes, it is only applicable for enphase/envoy installations that require the JWT from enlighten (so FW D7 and higher)
@rioug thanks for the feedback and confirmation. Looks like we’re getting close.
@catsmanac
Which token version is stored? There is a 12-hour token for “installers” and a 12-month token for owners. Which one you get is determined by your log-in method. I think the data is also a little different.
Given I haven’t been thrown out, I am assuming it has the 12 month version.
@catsmanac I have been testing your integration for the past few weeks with an Envoy S Metered EU with version 0.2.1, 0.2.3 and now 0.2.5. It’s been working great ! I had a look at your documentation as well. it looks good 👍 and it answered my question around L1 entities ! I have a consumption clamp installed so I can confirm that L1 sensors return the same number as the other sensors. Thanks for your work !
@wtadler I have been running your automation for a day now and it seems to be working well. Only thing that I needed to alter was the 1e-6 to 1e-3 part of your code to get a reading in kWh on my installation.
Thank you
With help of @madbrain76 and @DMedina559 we were able to get the last issuesresolved that prevented use with Legacy models. The changes needed are also forwarded into the HA Core dev work. I added the commit to PR6.
The Envoy_2_Core_custom_test custom integration for use with HACS has been updated to version 0.2.3. If you loaded it already in HACS, it will show an available update shorthly I assume.
With this, testing is also open for those with legacy ENVOY or mixed legacy and new. As usual, it’s testing so issues may surface and in that case you may need to revert to what you had before.
With this step needed functional changes are done. Testing should now confirm this and next stage to meet what ever Home Assistant requires can be done. The latter should include dealing with the MIT license that currently applies to envoy_reader.py. The original author @jesserizzo is willing to help to do what’s needed to change this to what HA will require.
@wtadler I added the automation, the values did not change but but that might be because it is now night time overe here. We will see if it worked tomorrow. Thank you!
Thanks @tedmies, it got me worried for a moment. At least it detected no metering.
The key line in this case is
where it gets the production data for metered version and in your case without the clamps connected. The formatted json from the tail-end of the line looks like below. The type eim section in the Production section is for the production clamps and the activecount is 0 telling there’s none connected. The integration will take the wNow and whLifetime from the first type: inverters section. That just explains where the number is coming for, there’s not much other data to go by. In @braincmpbll custom integration issues there’s much talk about these numbers in case on no installed meters, but I hadn’t seen @wtadler observation elsewhere. Good learning
That will probably depend on having testers for the old Envoy types. As long as this is a custom integration that is less of an issue, but if the core one gets replaced and it breaks the old Envoy model that would be a bigger issue as there’s no custom integration for that afaik. Testing with new models is needed as well, but the current custom integrations are fallback if something fails.
Currently I’m working in the @briancmpbll custom repo on issues that were reported with old envoy models and then bring them into this core dev work.
Short answer, it’s probably tight.
3 phase here and eager to start testing!
As this now seems to have become the coordination thread for adding V7 support to enphase envoy to let you know I’m running ENVOY-S EU standard (non-metered) so only can test that type (still working on test env for HA Core changes). We would need testers for ENVOY-S Metered, ENVOY-S metered with no CT’s connected, ENVOY-S 3 phase systems and also for V5 firmware and older envoy types for backward compatibility testing.
I have forked @mbeijen ha core and for now created 3 commits based on his enphase-envoy-v7-firmware-support branch
Can you open up your code for what you’ve done so far? Currently the biggest issue here appears to be that people are a bit confused about the open source method. You can check how to set up a development environment here: https://developers.home-assistant.io/docs/development_environment
Just share your fork on github and link it here, then someone else can follow up on your work if they feel like it in the coming 4 weeks. As far as I can see there’s now 4 different people working on a solution all on their own, the trick is to combine these efforts.
No promises, but I might have some time in about a week 😉
Can you please create a pull request and reference this issue number?
Also, for everyone, the token created on their online token service seem to be valid for one year if requested by the “system owner”. I suppose the firmware update has provided some public key that the Envoy device has locally to validate the tokens. So, even if the connection to Internet is lost, the token should allow to call the APIs on the LAN for quite some time.
I was able to generate an access token for the Enphase IQ Gateway local interface API via https://entrez.enphaseenergy.com/entrez_tokens
Possible duplicate of #79382