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-14 12:56:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add documentation for custom auth implentations in application credentials (#1328)

Browse Source
This commit is contained in:
Allen Porter 2022-05-15 06:42:59 -07:00 committed by GitHub
parent 0688f1e52f
commit 967b7b04af
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 32 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
docs/core/platform/application_credentials.md
View File

@ -7,7 +7,7 @@ users to link their accounts. Integrations may add a `application_credentials.py
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.
- *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 the 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
@ -28,9 +28,7 @@ from homeassistant.core import HomeAssistant
from homeassistant.components.application_credentials import AuthorizationServer
async def async_get_authorization_server(
self, hass: HomeAssistant
) -> AuthorizationServer:
async def async_get_authorization_server(hass: HomeAssistant) -> AuthorizationServer:
"""Return authorization server."""
return AuthorizationServer(
authorize_url="https://example.com/auth",
@ -47,6 +45,35 @@ An `AuthorizationServer` represents the [OAuth2 Authorization server](https://da
| 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. |
### Custom OAuth2 Implementations
Integrations may alternatively provide a custom `AbstractOAuth2Implementation` in `application_credentials.py` like the following:
```python
from homeassistant.core import HomeAssistant
from homeassistant.helpers import config_entry_oauth2_flow
from homeassistant.components.application_credentials import AuthImplementation, AuthorizationServer, ClientCredential
class OAuth2Impl(AuthImplementation):
"""Custom OAuth2 implementation."""
# ... Override AbstractOAuth2Implementation details
async def async_get_auth_implementation(
hass: HomeAssistant, auth_domain: str, credential: ClientCredential
) -> config_entry_oauth2_flow.AbstractOAuth2Implementation:
"""Return auth implementation for a custom auth implementation."""
return OAuth2Impl(
hass,
auth_domain,
credential,
AuthorizationServer(
authorize_url="https://example.com/auth",
token_url="https://example.com/oauth2/v4/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.