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])

Manage the authentication for Home Assistant.

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

Activate a user.

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

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

Create a new refresh token for a user.

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

Create a system user.

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

Create a user.

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

Deactivate a user.

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

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

Enable a multi-factor auth module for user.

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

List enabled mfa modules for user.

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

Retrieve all groups.

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

Get or create a user.

async async_get_owner() → models.User | None

Retrieve the owner.

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

Get refresh token by id.

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

Get refresh token by token.

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

Retrieve a user.

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

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

async async_get_users() → list[models.User]

Retrieve all users.

async async_link_user(user: homeassistant.auth.models.User, credentials: homeassistant.auth.models.Credentials) → None

Link credentials to an existing user.

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

Remove credentials.

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

Delete a refresh token.

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

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

Update a user.

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

Return refresh token if an access token is valid.

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

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

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

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

Return an auth provider, None if not found.

get_auth_providers(provider_type: str) → list[AuthProvider]

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)

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

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

Return a user as result of login flow.

exception homeassistant.auth.InvalidAuthError

Raised when a authentication error occurs.

exception homeassistant.auth.InvalidProvider

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

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)

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

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

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

Create a new user.

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

Activate a user.

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

Retrieve all users.

async async_get_groups() → list[models.Group]

Retrieve all users.

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

Get refresh token by id.

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

Get refresh token by token.

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

Retrieve a user by id.

async async_get_users() → list[models.User]

Retrieve all users.

async async_link_user(user: homeassistant.auth.models.User, credentials: homeassistant.auth.models.Credentials) → None

Add credentials to an existing user.

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

Update refresh token last used information.

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

Remove credentials.

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

Remove a refresh token.

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

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

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)

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)

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.7.2')

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)

Bases: object

A user.

credentials

groups

id

invalidate_permission_cache() → None

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

Bases: tuple

User metadata.

is_active

Alias for field number 1

name

Alias for field number 0