Documentation for Application Credentials platform initial features

[allenporter]

Proposed change

Propose initial documentation for application credentials platform. The platform is not quite ready for broad use, but has a placeholder with a note for now. This is mostly to make it easier for reviewing the platform and making it easier to determine if this is the right API for reviewers.

See home-assistant/architecture#692 (comment) for discussion.

Type of change

• Document existing features within Home Assistant
• Document new or changing features which there is an existing pull request elsewhere
• Spelling or grammatical corrections, or rewording for improved clarity
• Changes to the backend of this documentation
• Removed stale or deprecated documentation

Additional information

• This PR fixes or closes issue: fixes #
• Link to relevant existing code or pull request: Add application credentials platform core#69148

[frenck]

Hmm... should integration be able to import and deprecate the YAML configuration?

[allenporter]

Yes, definitely. This is called out as a task in the core PR, but didn't spell it out here yet:

Options I can see are:
(1) Use the existing platform method:

async def async_get_developer_credential(
    self, hass: HomeAssistant
) -> DeveloperCredential:

Could also be renamed to have import in the name.

(2) Offer a standalone method for the integration to call that accepts a credentials.

I have a method that in the implementation PR currently private that can be exposed:

async def _async_register_auth_implementation(
    hass: HomeAssistant,
    domain: str,
    developer_credential: DeveloperCredential,
) -> None:

Or we can rename it (e.g. stick "import" in the name). Integrations can call this from setup and create a credential from the data in the config which would be strictly easier, but more disconnected, from using the platform.

---

Are there gaps in these APIs needed to support import?

I did not mention this here yet because I thought there might be practical implications i have not worked out yet, so was going to work through in an integration first.

[allenporter]

I was thinking about this more think that import needs a little more from the API, since it also needs to register the authentication domain. I think I will take the method that returns the credential out of the platform, and make it a static method that the integration calls from setup.

I next need to take another pass updating the docs to match what is proposed in the PR.

[allenporter]

I've updated this to reflect a separate import API. I think it makes sense as a separate method call since new integrations won't need to specify it in the platform.

I was assuming that I didn't need to go to the level of writing out a whole migration guide given the low # of users of the existing local oauth implementation, and that i might be helping with the migration myself anyway -- and i'd probably update as I go through the migration myself to work out the issues.

[MartinHjelmare]

The first sentence is missing something. Now it sounds like all integrations support oauth2.

[MartinHjelmare]

Also here, we should clarify the sentence about cloud account linking, as implementing a local implementation isn't optional.

[allenporter]

Apologies, I deleted the wrong thing, i'll get back to this after sleeping on it.

[allenporter]

OK, i revamped this to add more of the bigger picture overview. I also updated the config flow docs to point here, then added a link back here with details on cloud account linking and nabu casa. Really, I think the cloud account linking stuff may deserve its own page. Or we could move more of that detail here, with a dedicated section, even though it does not technically involve this platform it may be the natural place to show the progression.

[MartinHjelmare]

Yeah, a separate page about account linking may be needed. Although it's not so much for the contributor to do. It's mostly Nabu Casa that needs to set up an application. For now this is good, I think.

[frenck]

😍