From ed9fde84fe918fe0705c332a3c2953b828b36574 Mon Sep 17 00:00:00 2001 From: Allen Porter Date: Sat, 2 Apr 2022 21:19:01 +0000 Subject: [PATCH] Documentation for initial developer credentials platform --- docs/core/platform/developer_credentials.md | 51 +++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 docs/core/platform/developer_credentials.md diff --git a/docs/core/platform/developer_credentials.md b/docs/core/platform/developer_credentials.md new file mode 100644 index 00000000..2ce1c35b --- /dev/null +++ b/docs/core/platform/developer_credentials.md @@ -0,0 +1,51 @@ +--- +title: "Developer 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 Clount Account Linking service. Integrations may also allow users to provide their own developer credentials by adding a `developer_credentials.py` and implementing the right functions. + +:::note +Developer Credentials is under active development and integrations should still prefer using +`LocalOAuth2Implementation`. +::: + +## Adding support + +Integrations support developer credentials with a file in the integration folder called `developer_credetnails.py` and implement the following: + +```python +from homeassistant.core import HomeAssistant +from homeassistant.components.developer_credentials.AuthorizationServer +from homeassistant.components.developer_credentials.DeveloperCredential + + +async def async_get_authorization_server( + self, hass: HomeAssistant +) -> AuthorizationServer: + """Return authorization server.""" + + +# Optional: Only implement if needed to provide a credential from configuration.yaml +async def async_get_developer_credential( + self, hass: HomeAssistant +) -> DeveloperCredential: + """Return a developer credential from configuration.yaml.""" +``` + +## AuthorizationServer + +A `AuthorizationServer` represents the [OAuth2 Authorization server](https://datatracker.ietf.org/doc/html/rfc6749) used for an integration. + +| Name | Type | | Description | +| ------------- | ---- | -------------------------------------------------------------------------------------------------- | ----------- | +| authorize_url | str | **Required** | The OAuth authorize URL that the user is redirected to during the configuration flow. | +| token_url | str | **Required** | The URL used for obtaining an access token. | + +## DeveloperCredential + +A `DeveloperCredential` represents the a developer credential provided by the user. This is only provided for backward compatibility by integrations that allowed users to specify developer credentials via `configuration.yaml`. + +| Name | Type | | Description | +| ------------- | ---- | ------------------------------------------------------------------------- | ----------- | +| client_id | str | **Required** | The developer credential client ID provided by the user. | +| client_secret | str | **Required** | The developer credential client secret provided by the user. |