diff --git a/docs/core/platform/application_credentials.md b/docs/core/platform/application_credentials.md index 01ccafe9..7d465933 100644 --- a/docs/core/platform/application_credentials.md +++ b/docs/core/platform/application_credentials.md @@ -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. @@ -96,4 +123,4 @@ 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. | \ No newline at end of file +| client_secret | str | **Required** | The OAuth Client Secret provided by the user. |