jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-20 15:56:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1279 from allenporter/developer_credentials

Browse Source 
Documentation for Application Credentials platform initial features
This commit is contained in:
Allen Porter 2022-04-30 09:48:32 -07:00 committed by GitHub
commit 416b087326
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 53 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/config_entries_config_flow_handler.md
View File

@ -165,7 +165,7 @@ To get started, run `python3 -m script.scaffold config_flow_discovery` and follo
Home Assistant has built-in support for integrations that offer account linking using [the OAuth2 authorization framework](https://tools.ietf.org/html/rfc6749). To be able to leverage this, you will need to structure your Python API library in a way that allows Home Assistant to be responsible for refreshing tokens. See our [API library guide](api_lib_index.md) on how to do this.
The built-in OAuth2 support works out of the box with locally configured client ID / secret and with the Home Assistant Cloud Account Linking service. This service allows users to link their account with a centrally managed client ID/secret. If you want your integration to be part of this service, reach out to us at [hello@home-assistant.io](mailto:hello@home-assistant.io).
The built-in OAuth2 support works out of the box with locally configured client ID / secret using the [Application Credentials platform](/docs/core/platform/application_credentials) and with the Home Assistant Cloud Account Linking service. This service allows users to link their account with a centrally managed client ID/secret. If you want your integration to be part of this service, reach out to us at [hello@home-assistant.io](mailto:hello@home-assistant.io).
To get started, run `python3 -m script.scaffold config_flow_oauth2` and follow the instructions. This will create all the boilerplate necessary to configure your integration using OAuth2.

52
docs/core/platform/application_credentials.md Normal file
View File

@ -0,0 +1,52 @@
---
title: "Application Credentials"
---
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.
OAuth2 requires credentials that are shared between an application and provider. In Home Assistant, integration specific OAuth2 credentials are provided using one or more 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
Integrations support application credentials with a file in the integration folder called `application_credentials.py` and implement the following:
```python
from homeassistant.core import HomeAssistant
from homeassistant.components.application_credentials import AuthorizationServer
async def async_get_authorization_server(
self, hass: HomeAssistant
) -> AuthorizationServer:
"""Return authorization server."""
return AuthorizationServer(
authorize_url="https://example.com/auth",
token_url="https://example.com/oauth2/v4/token"
)
```
### AuthorizationServer
An `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. |
## Import YAML credentials
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.
### ClientCredential
A `ClientCredential` represents a client credential provided by the user.
| Name | Type | | Description |
| ------------- | ---- | ------------------------------------------------------------------------- | ----------- |
| client_id | str | **Required** | The OAuth Client ID provided by the user. |
| client_secret | str | **Required** | The OAuth Client Secret provided by the user. |