Revisit rules for OAuth usage in config flow (for Google)

[allenporter]

Summary

I'd like to make setup/onboarding easier for Nest and Google integrations by revisiting our design standards for OAuth

Current State

Our current stance for integrations that expose devices is that config flows should be used instead of configuration yaml. However there is some nuance for OAuth which I interpret as something like:

• We prefer account linking. Nabu Casa works with the integration owner / cloud provider on Cloud Account Linking to set this up.
• Otherwise, OAuth client id and secret stay in configuration.yaml since this is an advanced feature

Proposal

Change our policy to be:

• We prefer account linking. Nabu Casa works with the integration owner / cloud provider on Cloud Account Linking to set this up.
  • If a workable solution is not possible, grant an exception to allow Client ID / Secret to be used in the config flow
• Otherwise, OAuth client id and secret stay in configuration.yaml since this is an advanced feature

In the last year since proposing home-assistant/core#44529 I've worked with Nabu Casa and Google on assessing feasibility of an account linking process for nest. The current state is that there is not a workable solution.

I am proposing we allow for Google and other integrations what we currently allow for Tuya.
Specifically for Google integrations, the work involved is:

• Move Nest (and all other Google integrations) to use Installed App Auth flow.
  • [Done] This was completed for Nest in Revamp nest authentication config flows and remove need for redirect urls core#59033 (also has some discussion about calendar)
• Use auth setup that is compatible across Google integrations.
• Allow Config Flow w/ Client ID & Secret with beefed up step-by-step walkthroughs

Additional Notes

• My 2021 review of Home Assistant + Google Authentication that i've been using to revamp nest authentication and config flow. Has notes from a discussion with @balloob where we sketched out this proposal.

• I surveyed the top ~50 integrations that involve auth, and figured it was worth sharing this summary:

  • OAuth:
    • Google Assistant, Spotify, Alexa, Netatmo, Xbox all use Cloud Link for OAuth
    • Google Calendar, and Nest use Client ID & Secret in yaml. (Google Assistant also has an option for a service account for pushing data which works differently.)
    • Tuya accepts Access ID, Access Secret but also Username, Password in config flow
  • Other:
    • Smart Things uses a personal access token however OAuth seems like a possible option
    • Xiaomi Miio uses usernames and passwords but might support oauth

• My prior 2020 review of Home Assistant Nest Config Flow

• We could have a shared place in the UI in home assistant to enter client ID and secret could be possible (e.g. somewhere else in settings), but does not change what the user has to do (enter a client id and secret). However, it seems simplest is to just let users share the client/id secret between the two projects. We could alternatively have a shared authentication library somewhere for Google creds if helpful, but not sure it is worth the complexity.

[MartinHjelmare]

I'm not sure how much more easy it'll be if we allow client id and secret in the config flow. The hard part is the cloud application setup, not pasting the client credentials in configuration.yaml or in the config flow.

I think it's a good idea to move to installed app auth flow for Google. It's working well in my WIP branch for Google calendar.

[allenporter]

These are my thoughts when it comes to ease of use:

• Last week: I saw https://community.home-assistant.io/t/set-up-nest/365053

  i am trying to setup nest in HA, i have followed all steps and think i’ve done it right but when i try to install nest it just comes up saying Aborted The component is not configured. Please follow the documentation.

• On #integrations on discord today:

  I followed all of the device access registration steps, completed the configuration.yaml with the correct ID's, restarted Home Assistant, and then when I try to add the integration, I receive error "Aborted. The component is not configured. Please follow the documentation."

  • When I told them their configuration.yaml was invalid they disagreed with me and inisted it was correct.
• Using a config flow we could have a step by step interactive set of instructions corresponding to the 4 steps in the Device Access Registration.
• Supporting some kind of device discovery would be nice, but it seems like a no go to involve configuration.yaml in the middle of that flow.

Thanks for the discussion. Setup has gotten much simpler for users with the move to installed app auth and automated pubsub creation.

[balloob]

I think that it will become easier because at least we don't steer users to configuration.yaml.

[allenporter]

I've added tests in home-assistant/core#62526 that show how nest discovery is currently effectively unsupported due to a config flow based approach not being allowed, and requiring configuration.yaml.

[allenporter]

I'd like to revive the discussion on usability. I have implemented this yet again in home-assistant/core#64680 and home-assistant/home-assistant.io#21303 so we have something concrete we can compare with.

While this has definitely not removed the complexity of the nest setup by any means, I've verfied the usability improvements above:

• Discovery now works, and can find nest devices on the network
• Less confusing error message when configuration.yaml is not present (abort status missing_configuration) when adding the integration, and instead jumps right to setup with instructions.
• The interactive config flow has markdown that links exactly where you need to go and mirrors 1:1 the existing documentation steps
• One trip to cloud console to get the cloud project id was removed. This step often confuses users as its one more chance to get "Cloud Project ID" and "Device Access Project ID" confused
• No more configuration.yaml, no more restarts required.
• Additional back and forth steps are removed (e.g. "write this down in a text file"). Additional steps that required restarts are removed.

So, none of this is hard, but seems pretty clearly aligned with making home assistant easier to use. That said, you are right that all the improvements made in the previous year around Installed App Auth and streamlined documentation have helped significantly.

Any other thoughts with regard to usability?

[balloob]

I think this is a good idea. I wonder if we should adjust the exception to be for cases where the client ID/secret are bound to a single user account? (which is the case here for Nest)

[allenporter]

Yes, that is true, it needs to be for the account owner. )Are there cases where people give instructions to use a shared client id and secret? oh man...)

[frenck]

I would opt for a separate page/panel to add developer accounts (or name it something similar) to register OAuth implementation and NOT make it part of the configuration flow.

What we can do in the config flow, is detect there are no implementations -> redirect the user to the flow to add/register an implementation/developer account. After adding such an account, we can restart the integration setup.

The idea would be similar to blueprints. Register developer accounts/connections to use with integration instances.

It keeps them decoupled, re-useable, and manageable.

[MartinHjelmare]

Fitbit works like that.

[allenporter]

I may be also misunderstanding the point. I think the use case for using credentials across integrations isn't there, but is it more about having a streamlined way for integrations to accept oauth credentails?

Having a streamlined way to accept oauth credentials for simplifying the code base or providing consistency across integrations for users could be interesting. Te 1:many case is what i'm skeptical about and interested in understanding the concrete use cases.

[frenck]

Reusable application credential for integrations, from the top of my head, this is possible for: Spotify, Toon, FitBit, (some) google integrations, Somfy, Netatmo, Withings, xbox.

Upcoming: Geocaching, Twitch, LaMetric

Possibly, but unsure: Smappee, Neato, Lyric

Possible, but not right now for vendor reasons: Home Connect, Tuya

The above is from the top of my head, so I'm sure I missed a bunch.

[allenporter]

I see -- so the huge context I was missing is you want to use this for integrations that already have a well lit path for cloud linking?

[frenck]

I was missing is you want to use this for integrations that already have a well lit path for cloud linking?

Yes, a global feature in handling application/developer credentials.

[allenporter]

One reason I did the survey of top integrations is to see what kind of usage something like this would get. Looking at the top 100 integrations I believe these 4 are eligible:

• Tuya (13% of installs) Currently accepting client id and secret in the config flow, and it has a one-page signup with country, access id, secret, username, and password.
• Google (Calendar) (6% of installs) - Uses configuration.yaml
• Nest (4% of installs) - Uses configuration.yaml
• Home Connect (1% of installs) - Uses configuration.yaml

Has there been discussion with Tuya or Home Connect about cloud linking? Basically, this is why I propose just using the config flow is that i'm not sure there would be sufficient use for a central user interface for this.

How I interpret this variation on the proposal is that we actually do not have a problem with users entering client id and secret into text boxes when setting up integrations. Perhaps we could take a step back away from implementation approach and discuss the principles with respect to OAuth? I think i'm trying to reverse engineer these a bit, without understanding the user problem we're trying to solve.

[balloob]

Tuya is out of the question for account linking as they charge money for that.

Home Connect we've had discussions but we kinda dropped the ball there.

[balloob]

The reason we implemented this policy is to enforce the ideal flow when account linking is available. If we allow asking client ID/secret, we should offer that option to the user even if account linking is available, causing confusion.

This proposal is about adding an exception in case a workable solution doesn't exist. I think that's a good idea (also commented that above)

[allenporter]

Yes, i thought i had some alignment that it made sense, but I was informed in the implementation PR that isn't the case. The status quo isn't acceptable, so i'm motivated to figure out a solution (even if its for satisfying less important use cases, IMO, given account linking is already available for those) and will revisit this after thinking about it more.

[allenporter]

Starting a side thread to go into a detailed overview of a global feature for developer credentials as a path forward to solving the Nest use case which has no options for any streamlined paths today. (Other integrations already have a streamlined path for cloud link, but have a broader need for infrastructure simplicity in order to support much more complex configuration use cases that cannot be supported with yaml)

Developer Credentials

A new component will be added for managing Developer Credentials. A Developer Credential is:

• client id
• client secret
• an identifier e.g. (domain, client id)

The credentials component can support these operations (e.g. websocket/storage) similar to blueprints:

• list: Return all developer accounts (domain, client id)
• add: Create developer credential identified by (domain, client id) with the client secret
• delete: By identifier. A developer credential may not be deleted if it is currently in use by a config entry.

Users have an expectation that a deleting a credential means it is completely gone (all copies are gone, all access tokens or refresh tokens are gone, etc). Edit is not a supported operation.

Example user flow end to end

As an example user journey for illustration:

• Integration registers that it supports Developer Credentials
• User starts config flow. If the integration supports cloud link, that is still used by default with no change. Otherwise, user is instructed to register a developer credential, or is automatically navigated there. (compared with a missing_configuration error today)
• User creates a Developer Credential. (Note: User may also start at this step)
• User resumes the config flow. If there is just one auth implementation the flow would proceed as normal. Otherwise, it acts just like auth implementations do today.

An integrations config flow remains unchanged, and relies on the oauth config flow to pick/manage/show auth implementations and create config entries on its behalf. The integration config flow doesn't need to know about details of credentials.

Authorization Server and Authentication Impl

You can think of this effort like splitting up the responsibilities of a LocalOAuthImplementation, and changing up the registration mechanism. Integrations are still responsible for declaring the Authorization Server to use: an authorize url, and token url.

We consider these degrees of freedom between Developer Credentials, Authorization Server, and Config Entries to inform how registration works:

• Multiple Developer Credentials for an Authorization Server. Use case: config entry for each account that I have.
• Multiple Authorization Servers for an integration. Use case: Different auth types e.g. Installed App auth, Web Auth, backwards compatibility needed if preferred types change over time
• Multiple uses of the same Developer Credential and Authorization Server: Use case: separate config entry per cloud device, in above fitbit example.
• Authorization Server config varies per Config Entry. Use case: An authorization url contains a nest project id

The number of combinations implies to me we may want a pretty flat representation of these things, but we can get into this in detailed design next.

Integration setup will register an Authorization server, and Developer Credentials for any accounts currently in yaml. Integration setup for a config entry is similar to today (e.g. asks for an auth implementation for a given config entry). The config entry has a pointer/reference to a developer credential, which is also used for delete protection above.

When considering the user experience, integrations may need to customize Developer Credentials setup with extra instructions/markdown or links -- though many integrations with trivial authentication setup may not even need this.

A handful of integrations will operate on Developer Credentials at a lower level, similar to how yaml compatibility works, or how oauth config flows are customized today. This keeps integration specific complexity within the integrations, allowing for more integrated user experience while keeping the developer credentials APIs simple e.g. (screenshot #1, screenshot #2) shows an example config flow that constructs inputs that appear in the Authorization Server URL, with an integrated setup to minimize bounding back and forth between consoles decreasing likelihood of mismatched credentials. Or put another way, custom config flows must use the developer credentials infrastructure and wiring.

I would like feedback on this high level direction before getting into the next level of implementation details.

[frenck]

Read the above, the generic flow of things matches with what I had in mind, so from my end 👍
The idea to add a platform for it is great btw, there are probably tons of little details we run into, but the big picture sounds like the right path to take.

[frenck]

Config flow would be a good candidate to remove from the manifest as it can be derived from existence of config_flow.py

Yes/no. Not sure if it is still the case, but we had a couple of cases that used an import flow, but not a user-based flow. In that case, there would be a config flow, but not marked as such in the manifest (so it would not show up in the UI).

[frenck]

So, looking at upstream implementations, my biggest concern is the simplest one: "Developer Credentials"

I think that name is incorrect and not really end-user-friendly. The term "developer" scares people unneeded. I would suggest "Application Credentials", or (as specs call it) "Client Credentials"

[allenporter]

Agreed, I had never heard the term "developer" used in this context before until this discussion thread.

(1) For developer end users, I do think it makes sense to be aligned to the spec e.g. "Client Credentials" so happy to go with that.

(2) For actual home assistant end users, my impression is we would pick a name for the interface that makes sense in that context and it would be different from the name used in the component. e.g. w/ "Applications", "Accounts", "Linked" in the name

[allenporter]

For (1) I'm warming up to using Application Credentials as the component name, and then Client Credentials for the client id and secret.

[frenck]

Closing this architectural topic, as we have covered this now.

../Frenck