homeassistant.auth

Provide an authentication layer for Home Assistant.

class homeassistant.auth.AuthManager(hass: homeassistant.core.HomeAssistant, store: homeassistant.auth.auth_store.AuthStore, providers: Dict[Tuple[str, Optional[str]], homeassistant.auth.providers.AuthProvider], mfa_modules: Dict[str, homeassistant.auth.mfa_modules.MultiFactorAuthModule])[source]

Manage the authentication for Home Assistant.

async async_activate_user(user: homeassistant.auth.models.User) → None[source]

Activate a user.

async_create_access_token(refresh_token: models.RefreshToken, remote_ip: str | None = None) → str[source]

Create a new access token.

async async_create_refresh_token(user: models.User, client_id: str | None = None, client_name: str | None = None, client_icon: str | None = None, token_type: str | None = None, access_token_expiration: timedelta = datetime.timedelta(seconds=1800), credential: models.Credentials | None = None) → models.RefreshToken[source]

Create a new refresh token for a user.

async async_create_system_user(name: str, group_ids: list[str] | None = None) → models.User[source]

Create a system user.

async async_create_user(name: str, group_ids: list[str] | None = None) → models.User[source]

Create a user.

async async_deactivate_user(user: homeassistant.auth.models.User) → None[source]

Deactivate a user.

async async_disable_user_mfa(user: homeassistant.auth.models.User, mfa_module_id: str) → None[source]

Disable a multi-factor auth module for user.

async async_enable_user_mfa(user: homeassistant.auth.models.User, mfa_module_id: str, data: Any) → None[source]

Enable a multi-factor auth module for user.

async async_get_enabled_mfa(user: models.User) → dict[str, str][source]

List enabled mfa modules for user.

async async_get_group(group_id: str) → models.Group | None[source]

Retrieve all groups.

async async_get_or_create_user(credentials: homeassistant.auth.models.Credentials) → homeassistant.auth.models.User[source]

Get or create a user.

async async_get_owner() → models.User | None[source]

Retrieve the owner.

async async_get_refresh_token(token_id: str) → models.RefreshToken | None[source]

Get refresh token by id.

async async_get_refresh_token_by_token(token: str) → models.RefreshToken | None[source]

Get refresh token by token.

async async_get_user(user_id: str) → models.User | None[source]

Retrieve a user.

async async_get_user_by_credentials(credentials: models.Credentials) → models.User | None[source]

Get a user by credential, return None if not found.

async async_get_users() → list[models.User][source]

Retrieve all users.

Link credentials to an existing user.

async async_remove_credentials(credentials: homeassistant.auth.models.Credentials) → None[source]

Remove credentials.

async async_remove_refresh_token(refresh_token: homeassistant.auth.models.RefreshToken) → None[source]

Delete a refresh token.

async async_remove_user(user: homeassistant.auth.models.User) → None[source]

Remove a user.

async async_update_user(user: models.User, name: str | None = None, is_active: bool | None = None, group_ids: list[str] | None = None) → None[source]

Update a user.

async async_validate_access_token(token: str) → models.RefreshToken | None[source]

Return refresh token if an access token is valid.

async_validate_refresh_token(refresh_token: models.RefreshToken, remote_ip: str | None = None) → None[source]

Validate that a refresh token is usable.

Will raise InvalidAuthError on errors.

property auth_mfa_modules

Return a list of available auth modules.

property auth_providers

Return a list of available auth providers.

get_auth_mfa_module(module_id: str) → MultiFactorAuthModule | None[source]

Return a multi-factor auth module, None if not found.

get_auth_provider(provider_type: str, provider_id: str | None) → AuthProvider | None[source]

Return an auth provider, None if not found.

get_auth_providers(provider_type: str) → list[AuthProvider][source]

Return a List of auth provider of one type, Empty if not found.

class homeassistant.auth.AuthManagerFlowManager(hass: homeassistant.core.HomeAssistant, auth_manager: homeassistant.auth.AuthManager)[source]

Manage authentication flows.

async async_create_flow(handler_key: Any, *, context: dict[str, Any] | None = None, data: dict[str, Any] | None = None) → data_entry_flow.FlowHandler[source]

Create a login flow.

async async_finish_flow(flow: homeassistant.data_entry_flow.FlowHandler, result: homeassistant.data_entry_flow.FlowResult) → homeassistant.data_entry_flow.FlowResult[source]

Return a user as result of login flow.

exception homeassistant.auth.InvalidAuthError[source]

Raised when a authentication error occurs.

exception homeassistant.auth.InvalidProvider[source]

Authentication provider not found.

async homeassistant.auth.auth_manager_from_config(hass: HomeAssistant, provider_configs: list[dict[str, Any]], module_configs: list[dict[str, Any]]) → AuthManager[source]

Initialize an auth manager from config.

CORE_CONFIG_SCHEMA will make sure do duplicated auth providers or mfa modules exist in configs.

homeassistant.auth.auth_store

Storage for auth models.

class homeassistant.auth.auth_store.AuthStore(hass: homeassistant.core.HomeAssistant)[source]

Bases: object

Stores authentication info.

Any mutation to an object should happen inside the auth store.

The auth store is lazy. It won’t load the data from disk until a method is called that needs it.

async async_activate_user(user: homeassistant.auth.models.User) → None[source]

Activate a user.

async async_create_refresh_token(user: models.User, client_id: str | None = None, client_name: str | None = None, client_icon: str | None = None, token_type: str = 'normal', access_token_expiration: timedelta = datetime.timedelta(seconds=1800), credential: models.Credentials | None = None) → models.RefreshToken[source]

Create a new token for a user.

async async_create_user(name: str | None, is_owner: bool | None = None, is_active: bool | None = None, system_generated: bool | None = None, credentials: models.Credentials | None = None, group_ids: list[str] | None = None) → models.User[source]

Create a new user.

async async_deactivate_user(user: homeassistant.auth.models.User) → None[source]

Activate a user.

async async_get_group(group_id: str) → models.Group | None[source]

Retrieve all users.

async async_get_groups() → list[models.Group][source]

Retrieve all users.

async async_get_refresh_token(token_id: str) → models.RefreshToken | None[source]

Get refresh token by id.

async async_get_refresh_token_by_token(token: str) → models.RefreshToken | None[source]

Get refresh token by token.

async async_get_user(user_id: str) → models.User | None[source]

Retrieve a user by id.

async async_get_users() → list[models.User][source]

Retrieve all users.

Add credentials to an existing user.

async_log_refresh_token_usage(refresh_token: models.RefreshToken, remote_ip: str | None = None) → None[source]

Update refresh token last used information.

async async_remove_credentials(credentials: homeassistant.auth.models.Credentials) → None[source]

Remove credentials.

async async_remove_refresh_token(refresh_token: homeassistant.auth.models.RefreshToken) → None[source]

Remove a refresh token.

async async_remove_user(user: homeassistant.auth.models.User) → None[source]

Remove a user.

async async_update_user(user: models.User, name: str | None = None, is_active: bool | None = None, group_ids: list[str] | None = None) → None[source]

Update a user.

homeassistant.auth.const

Constants for the auth module.

homeassistant.auth.models

Auth models.

class homeassistant.auth.models.Credentials(auth_provider_type: str, auth_provider_id: str | None, data: dict, id: str = NOTHING, is_new: bool = True)[source]

Bases: object

Credentials for a user on an auth provider.

auth_provider_id
auth_provider_type
data
id
is_new
class homeassistant.auth.models.Group(name: str | None, policy: perm_mdl.PolicyType, id: str = NOTHING, system_generated: bool = False)[source]

Bases: object

A group.

id
name
policy
system_generated
class homeassistant.auth.models.RefreshToken(user: User, client_id: str | None, access_token_expiration: timedelta, client_name: str | None = None, client_icon: str | None = None, token_type: str = 'normal', id: str = NOTHING, created_at: datetime = NOTHING, token: str = NOTHING, jwt_key: str = NOTHING, last_used_at: datetime | None = None, last_used_ip: str | None = None, credential: Credentials | None = None, version: str | None = '2021.6.5')[source]

Bases: object

RefreshToken for a user to grant new access tokens.

access_token_expiration
client_icon
client_id
client_name
created_at
credential
id
jwt_key
last_used_at
last_used_ip
token
token_type
user
version
class homeassistant.auth.models.User(name: str | None, perm_lookup: perm_mdl.PermissionLookup, id: str = NOTHING, is_owner: bool = False, is_active: bool = False, system_generated: bool = False, groups: list[Group] = NOTHING, credentials: list[Credentials] = NOTHING, refresh_tokens: dict[str, RefreshToken] = NOTHING)[source]

Bases: object

A user.

credentials
groups
id
invalidate_permission_cache() → None[source]

Invalidate permission cache.

is_active
property is_admin

Return if user is part of the admin group.

is_owner
name
perm_lookup
property permissions

Return permissions object for user.

refresh_tokens
system_generated
class homeassistant.auth.models.UserMeta[source]

Bases: tuple

User metadata.

is_active

Alias for field number 1

name

Alias for field number 0