From e35b60aba94d10ff7cb45e612bf072a6f0319180 Mon Sep 17 00:00:00 2001 From: Allen Porter Date: Thu, 7 Apr 2022 15:40:56 +0000 Subject: [PATCH] Rewrote documentation structure based on PR feedback --- docs/core/platform/application_credentials.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/core/platform/application_credentials.md b/docs/core/platform/application_credentials.md index 1893cd6b..0cf17c08 100644 --- a/docs/core/platform/application_credentials.md +++ b/docs/core/platform/application_credentials.md @@ -2,11 +2,13 @@ title: "Application Credentials" --- -Integrations support [Configuration via OAuth2](https://developers.home-assistant.io/docs/config_entries_config_flow_handler#configuration-via-oauth2) and the preferred approach is to use the Home Assistant Cloud Account Linking service. Integrations may also allow users to provide their own OAuth client credentials by adding a `application_credentials.py` and implementing the right functions. +Integrations may support [Configuration via OAuth2](/docs/config_entries_config_flow_handler#configuration-via-oauth2) allowing +users to link their accounts. Integrations may add a `application_credentials.py` file and implement the functions described below. -:::note -Application Credentials is under active development and integrations should still prefer using `LocalOAuth2Implementation`. -::: +OAuth2 requires credentials that are shared between an application and provider. In Home Assistant, integration specific OAuth2 credentials are typically provided using these approaches: + +- *Local OAuth with Application Credentials Component*: Users create their own credentials with the cloud provider, often acting as an application developer, and register the credentials with Home Assistant and integration. This approach is *required* by all integrations that support OAuth2. +- *Cloud Account Linking with Cloud Component*: Nabu Casa registers credentials with the cloud provider, providing a seamless user experience. This approach provides a seamless user experience and is *recommended* ([more info](/docs/config_entries_config_flow_handler#configuration-via-oauth2)). ## Adding support @@ -27,8 +29,6 @@ async def async_get_authorization_server( ) ``` -See below for details on backwards compatibility with YAML credentials. - ## AuthorizationServer An `AuthorizationServer` represents the [OAuth2 Authorization server](https://datatracker.ietf.org/doc/html/rfc6749) used for an integration. @@ -42,9 +42,7 @@ An `AuthorizationServer` represents the [OAuth2 Authorization server](https://da Credentials may be imported by integrations that used to accept YAML credentials using the import API `async_import_client_credential` provided by the application credentials integration. -The `auth_domain` is the domain for the auth implementation in the config entry, which is typically the domain specified in an existing `LocalOAuth2Implementation`. - -## ClientCredential +### ClientCredential A `ClientCredential` represents a client credential provided by the user.