[Feature Request] : Updated UniFi controller integration/widget

[BreckanM]

Description

When Ubiquiti made an update to the user management of the UI Console (aka needing 2FA), all my UniFi widget config stopped working.
Now that the UI API has been published, would it be possible to update the UniFi elements (https://gethomepage.dev/widgets/services/unifi-controller/) to use the newly published API via API Key instead of username/password ?

Other

No response

[BreckanM]

update: the API error seen from Homepage is :

API Error: HTTP Error 499
URL: https://a.b.c.d/proxy/network/api/stat/sites
Response Data:
{"data":{"required":"2fa","authenticators":[{"blocked_reason":null,"created":"2024-02-20T02:23:21.874215Z","email":"redacted","id":"","last_success":null,"status":"active","type":"email"},{"created":"2024-02-20T02:22:46.456470Z","id":"","last_success":"2025-02-13T11:46:19.327943Z","name":"Authenticator app","status":"active","type":"totp"}],"publicKeyCredentialRequestOptions":null,"user":{"default_mfa":"","id":""},"mfaCookie":"UBIC_2FA="},"code":"MFA_AUTH_REQUIRED","message":"MFA token required to authenticate to SSO","level":"debug"}

[shamoon]

Do you have documentation of some api key change? I dont see anything.

And to get around the MFA you can create a local account, which I doubt has stopped working

[BreckanM]

local account did the trick - thanks for the heads up!

[jm1tchell]

Just wanted to say that API key access would be nice if it's possible.

I also managed to get the local account working, so thanks for the hint. Took a few restarts and container prunes, but I got there.

[JakePi3]

I've been using this widget for a long time - over a year. Yesterday I switched over from running the controller software in a container to actually using the network plugin on the new Dream Router 7. This means it's no longer running virtualised on a separate IP, but is actually integrated into the router itself.

Both homepage widgets stopped working when I modified the address. I.e. the widget and the service.

Digging through the API docs on unifi, I believe there were breaking changes from the controller software.

New URLs:
https://192.168.1.1/proxy/network/integrations/v1/sites

instead of:
https://192.168.1.1/api/stat/sites

However, it does appear that
https://192.168.1.1/proxy/network/api/stat/sites

continues to work, which means I can potentially just adjust the prefix in my config.. It's possible the response body is different. I will paste anonymized sample at bottom of message.

A larger problem is the new way of issuing credentials. They allow the capability to generate an API key, which is then passed as the value of header X-API-KEY.

I can't get the user/pass local account to work at all, and I can only generate an API key for the admin user.

Appreciate this is brand new hardware that was just released, hope you can support.

The following was retrieved from https://192.168.1.1/proxy/network/api/stat/sites using curl and X-API-KEY:

{
  "meta": { "rc": "ok" },
  "data": [
    {
      "anonymous_id": "4d019f4e-9479-472c-bd11-8add5445ed8d",
      "name": "default",
      "external_id": "a84d8245-bea7-4efb-9ef5-7e7f0feacc51",
      "_id": "1",
      "attr_no_delete": true,
      "attr_hidden_id": "default",
      "desc": "Default",
      "health": [
        {
          "subsystem": "wlan",
          "num_user": 10,
          "num_guest": 2,
          "num_iot": 0,
          "tx_bytes-r": 48941,
          "rx_bytes-r": 8134,
          "status": "ok",
          "num_ap": 2,
          "num_adopted": 2,
          "num_disabled": 0,
          "num_disconnected": 0,
          "num_pending": 0
        },
        {
          "subsystem": "wan",
          "num_gw": 1,
          "num_adopted": 1,
          "num_disconnected": 0,
          "num_pending": 0,
          "status": "ok",
          "wan_ip": "mas.ked.ip.add",
          "gateways": [],
          "netmask": "255.255.240.0",
          "nameservers": [],
          "num_sta": 34,
          "tx_bytes-r": 9722,
          "rx_bytes-r": 192968,
          "gw_mac": "00:00:00:00:00:00",
          "gw_name": "Router",
          "gw_system-stats": {
            "cpu": "14.8",
            "mem": "42.4",
            "uptime": "12088"
          },
          "gw_version": "4.1.18.21536",
          "isp_name": "Hyper Global Media Net",
          "isp_organization": "HGMN",
          "uptime_stats": {
            "WAN": {
              "alerting_monitors": [
                {
                  "availability": 100.0,
                  "latency_average": 18,
                  "target": "ping.ui.com",
                  "type": "icmp"
                },
                {
                  "availability": 100.0,
                  "latency_average": 101,
                  "target": "1.1.1.1",
                  "type": "dns"
                },
                {
                  "availability": 100.0,
                  "latency_average": 100,
                  "target": "8.8.8.8",
                  "type": "dns"
                }
              ],
              "availability": 99.50249999761581,
              "latency_average": 18,
              "monitors": [
                {
                  "availability": 100.0,
                  "latency_average": 16,
                  "target": "www.microsoft.com",
                  "type": "icmp"
                },
                {
                  "availability": 100.0,
                  "latency_average": 16,
                  "target": "google.com",
                  "type": "icmp"
                },
                {
                  "availability": 100.0,
                  "latency_average": 17,
                  "target": "1.1.1.1",
                  "type": "icmp"
                }
              ],
              "time_period": 12017,
              "uptime": 11577
            }
          }
        },
        {
          "subsystem": "www",
          "status": "ok",
          "tx_bytes-r": 9722,
          "rx_bytes-r": 192968,
          "latency": 19,
          "uptime": 12056,
          "drops": 1,
          "xput_up": 30.0,
          "xput_down": 939.0,
          "speedtest_status": "Success",
          "speedtest_lastrun": 1740781187,
          "speedtest_ping": 15,
          "gw_mac": "00:00:00:00:00:00"
        },
        {
          "subsystem": "lan",
          "lan_ip": null,
          "status": "ok",
          "num_user": 16,
          "num_guest": 6,
          "num_iot": 0,
          "tx_bytes-r": 66866,
          "rx_bytes-r": 17461,
          "num_sw": 3,
          "num_adopted": 3,
          "num_disconnected": 0,
          "num_pending": 0
        },
        { "subsystem": "vpn", "status": "unknown" }
      ],
      "num_new_alarms": 0
    }
  ]
}

Lots of interesting information there including a sample of recent pings and speedtests. I believe the destination sites are hard coded.

[shamoon]

Oh cool, I have that new API on my UDMP and didnt even realize!

Crazy that endpoint /proxy/network/api/stat/sites seems to literally not be documented in their official docs (!), but its ideal because it returns all of the same data, so supporting this turns out to be pretty doable 🎉

If anyone using the new API would like to test this out, there's a docker image tagged feature-unifi-network-api you can try, and let me know.

[JakePi3]

I'm getting mixed results. Now, I had to do a completely separate install to get the docker version. I'm normally running homepage as Proxmox LXC which is created from the tarball.

I installed the docker version on my unraid server using ghcr.io/gethomepage/homepage:feature-unifi-network-api

I had to set the HOMEPAGE_ALLOWED_HOSTS variable as well to get dev version to work.

My results:

Initially the service widget does populate with data, but subsequent requests result in:

    API Error: HTTP Error 403
    URL: https://192.168.1.1/proxy/network/api/stat/sites
    Response Data:
    {"code":"AUTHENTICATION_FAILED","message":"Authentication failed","level":"debug"}

It's not a rate limit or anything like that since the curl request continues to work as before.

I was also seeing intermittent authentication errors with some of my other widgets (Audiobookshelf, pihole, and immich). But they were coming and going unlike unifi which only succeeded once.

Same story with the widget. It loads initially and then just has an API error.

Looking at homepage.log:

[2025-03-01T14:50:56.639Z] error: <unifiProxyHandler> HTTP 403 logging in to Unifi. Data: {"code":"AUTHENTICATION_FAILED","message":"Authentication failed","level":"debug"}

Weird that this message references "logging in". Would expect login to be unnecessary when api key is passed as header.

[shamoon]

Thanks for testing. Funny, its not working for me in docker either, I'll see what's up with that....

[shamoon]

Ok, once its done building (20 min from now) please re-pull the image and re-try, thanks!

https://github.com/gethomepage/homepage/actions/runs/13606902703

[JakePi3]

I patched my local installation and recompiled, largely based on your branch. Works fine for me, no issues.

Things I noticed while implementing my patch.

The /proxy/network prefix is already pre-defined as udmpPrefix so I think it would be fine to reuse instead of having a special case for v2.

It may also be the case that user/pass are still available.

For DreamRouter7:

The udmpPrefix (/proxy/network) applies (as we've tested it)
The login endpoint is https://192.168.1.1/api/auth/login
The login body has keys (username, password, rememberMe and token)

token is an empty string, but rememberMe is different from the current homepage loginBody which has the key remember

  const loginBody = { username: widget.username, password: widget.password, remember: true };

Also, if we ARE using the API key, it may not be worth trying to login.

Alternatively we can abandon the use of keys and focus on getting login to work with the variants I outlined above. I suspect it was failing just due to the changes I've outlined not that they've disabled it.

The API keys feel like an afterthought and security doesn't seem like a strong point here. Passwords are sent in plaintext, and the api keys can ONLY be generated locally for the admin user so there's no View-only API key available, and no benefit over username/password.

So if we can finesse the login to be compatible it may not be necessary to increment the version.

[shamoon]

Cool, this should work. If you're willing to test the branch: dev...refs/heads/feature/unifi-network-api or the docker image is building again: https://github.com/gethomepage/homepage/actions/runs/13607372524

[JakePi3]

yep I'll test the docker image

BTW, I struggled to get this to fail after trying to back out my changes. I accidentally left in just one line of code:

prefix = udmpPrefix;

Just before the line widget.prefix = prefix;

Even without changing the login body the widget was still working. I think the login API is very permissive, just ignoring attributes it doesn't understand.

So I think in the end this will be a very simple change just have to heuristically detect that it's actually running version 4 of the API and go down the right branch.

For reference I'm running 4.1.18 of the UDR7 OS and 9.0.114 of the Network application.

Just one final thing to think about: When I created a separate account for homepage (with view-only permissions to the networking component, and no access to control plane) the user can get locked out for a few minutes with a 429 response if homepage hammers the login with too many incorrect attempts. I don't know what recovery looks like if homepage continually tries to log in (even once correct credentials are supplied).

I think it's outside the scope of this PR, I see the same thing happening with pihole even with only correct attempts.

[JakePi3]

Ok docker image tested, it's working for me.

[shamoon]

Great, thanks for your help.

#4860