tessl/pypi-homeassistant
Open-source home automation platform running on Python 3.
69
1.18x
auth.mddocs/
Authentication & Authorization
Security framework providing user management, OAuth token handling, multi-factor authentication, and permission-based access control for Home Assistant instances.
Capabilities
Authentication Manager
Central authentication system that manages users, tokens, and authentication providers.
class AuthManager:
"""Manage authentication for Home Assistant."""
def __init__(self, hass: HomeAssistant, store: Store, providers: list,
mfa_modules: list):
"""Initialize auth manager.
Args:
hass: Home Assistant instance
store: Authentication storage
providers: Authentication providers
mfa_modules: MFA modules
"""
@property
def active(self) -> bool:
"""Return True if auth is active."""
@property
def support_legacy(self) -> bool:
"""Return True if legacy API password is supported."""
async def async_get_users(self) -> list[User]:
"""Get all users.
Returns:
List of users
"""
async def async_get_user(self, user_id: str) -> User:
"""Get user by ID.
Args:
user_id: User ID
Returns:
User or None if not found
"""
async def async_get_owner(self) -> User:
"""Get owner user.
Returns:
Owner user
"""
async def async_create_system_user(self, name: str, *, group_ids: list[str] = None,
local_only: bool = None) -> User:
"""Create system user.
Args:
name: User name
group_ids: Group IDs
local_only: Local only access
Returns:
Created user
"""
async def async_create_user(self, name: str, *, group_ids: list[str] = None,
local_only: bool = None) -> User:
"""Create user.
Args:
name: User name
group_ids: Group IDs
local_only: Local only access
Returns:
Created user
"""
async def async_remove_user(self, user: User) -> None:
"""Remove user.
Args:
user: User to remove
"""
async def async_update_user(self, user: User, *, name: str = None,
is_active: bool = None, group_ids: list[str] = None,
local_only: bool = None) -> User:
"""Update user.
Args:
user: User to update
name: New name
is_active: Active status
group_ids: Group IDs
local_only: Local only access
Returns:
Updated user
"""
async def async_activate_user(self, user: User) -> None:
"""Activate user.
Args:
user: User to activate
"""
async def async_deactivate_user(self, user: User) -> None:
"""Deactivate user.
Args:
user: User to deactivate
"""
async def async_create_refresh_token(self, user: User, client_id: str = None,
client_name: str = None,
client_icon: str = None,
token_type: str = None,
access_token_expiration: timedelta = None) -> RefreshToken:
"""Create refresh token.
Args:
user: User for token
client_id: Client ID
client_name: Client name
client_icon: Client icon
token_type: Token type
access_token_expiration: Access token expiration
Returns:
Created refresh token
"""
async def async_get_refresh_token(self, token_id: str) -> RefreshToken:
"""Get refresh token by ID.
Args:
token_id: Token ID
Returns:
Refresh token or None
"""
async def async_get_refresh_token_by_token(self, token: str) -> RefreshToken:
"""Get refresh token by token value.
Args:
token: Token value
Returns:
Refresh token or None
"""
async def async_remove_refresh_token(self, refresh_token: RefreshToken) -> None:
"""Remove refresh token.
Args:
refresh_token: Token to remove
"""
async def async_validate_access_token(self, token: str) -> AccessToken:
"""Validate access token.
Args:
token: Access token
Returns:
Access token object or None if invalid
"""
async def async_create_access_token(self, refresh_token: RefreshToken,
remote_ip: str = None) -> str:
"""Create access token.
Args:
refresh_token: Refresh token
remote_ip: Remote IP address
Returns:
Access token string
"""User Management
User account management including creation, modification, and permission handling.
class User:
"""User account information."""
def __init__(self, name: str, perm_lookup: PermissionLookup, id: str = None,
is_owner: bool = False, is_active: bool = True,
system_generated: bool = False, local_only: bool = False,
group_ids: list[str] = None):
"""Initialize user.
Args:
name: User name
perm_lookup: Permission lookup
id: User ID
is_owner: Is owner user
is_active: Is active user
system_generated: Is system generated
local_only: Local only access
group_ids: Group IDs
"""
@property
def id(self) -> str:
"""Return user ID."""
@property
def name(self) -> str:
"""Return user name."""
@property
def is_owner(self) -> bool:
"""Return True if user is owner."""
@property
def is_active(self) -> bool:
"""Return True if user is active."""
@property
def system_generated(self) -> bool:
"""Return True if user is system generated."""
@property
def local_only(self) -> bool:
"""Return True if user has local only access."""
@property
def groups(self) -> list[Group]:
"""Return user groups."""
@property
def permissions(self) -> AbstractPermissions:
"""Return user permissions."""
def in_group(self, group_id: str) -> bool:
"""Check if user is in group.
Args:
group_id: Group ID
Returns:
True if user is in group
"""
class Group:
"""User group for permission management."""
def __init__(self, name: str, policy: PolicyType, id: str = None):
"""Initialize group.
Args:
name: Group name
policy: Group policy
id: Group ID
"""
@property
def id(self) -> str:
"""Return group ID."""
@property
def name(self) -> str:
"""Return group name."""
@property
def policy(self) -> PolicyType:
"""Return group policy."""Token Management
OAuth token system for authentication and authorization with refresh and access tokens.
class RefreshToken:
"""Refresh token for OAuth authentication."""
def __init__(self, user: User, client_id: str, access_token_expiration: timedelta,
client_name: str = None, client_icon: str = None,
token_type: str = None, id: str = None, jwt_key: str = None,
last_used_at: datetime = None, last_used_ip: str = None,
credential: Credentials = None, version: str = None):
"""Initialize refresh token.
Args:
user: Token user
client_id: Client ID
access_token_expiration: Access token expiration
client_name: Client name
client_icon: Client icon
token_type: Token type
id: Token ID
jwt_key: JWT key
last_used_at: Last used timestamp
last_used_ip: Last used IP
credential: Associated credential
version: Token version
"""
@property
def id(self) -> str:
"""Return token ID."""
@property
def user(self) -> User:
"""Return token user."""
@property
def client_id(self) -> str:
"""Return client ID."""
@property
def client_name(self) -> str:
"""Return client name."""
@property
def client_icon(self) -> str:
"""Return client icon."""
@property
def token_type(self) -> str:
"""Return token type."""
@property
def access_token_expiration(self) -> timedelta:
"""Return access token expiration."""
@property
def jwt_key(self) -> str:
"""Return JWT key."""
@property
def last_used_at(self) -> datetime:
"""Return last used timestamp."""
@property
def last_used_ip(self) -> str:
"""Return last used IP."""
@property
def credential(self) -> Credentials:
"""Return associated credential."""
@property
def version(self) -> str:
"""Return token version."""
class AccessToken:
"""Access token for API authentication."""
def __init__(self, refresh_token: RefreshToken):
"""Initialize access token.
Args:
refresh_token: Associated refresh token
"""
@property
def refresh_token(self) -> RefreshToken:
"""Return refresh token."""
@property
def scopes(self) -> list[str]:
"""Return token scopes."""Authentication Providers
Pluggable authentication providers for different authentication methods.
class AuthProvider:
"""Base authentication provider."""
DEFAULT_TITLE = None
def __init__(self, hass: HomeAssistant, store: Store, config: dict):
"""Initialize auth provider.
Args:
hass: Home Assistant instance
store: Provider storage
config: Provider configuration
"""
@property
def id(self) -> str:
"""Return provider ID."""
@property
def name(self) -> str:
"""Return provider name."""
@property
def type(self) -> str:
"""Return provider type."""
@property
def support_mfa(self) -> bool:
"""Return True if provider supports MFA."""
async def async_login_flow(self, context: dict) -> LoginFlow:
"""Return login flow.
Args:
context: Login context
Returns:
Login flow
"""
async def async_get_or_create_credentials(self, flow_result: dict) -> Credentials:
"""Get or create credentials from flow result.
Args:
flow_result: Login flow result
Returns:
User credentials
"""
async def async_user_meta_for_credentials(self, credentials: Credentials) -> UserMeta:
"""Return user metadata for credentials.
Args:
credentials: User credentials
Returns:
User metadata
"""
class Credentials:
"""User credentials from authentication provider."""
def __init__(self, auth_provider_type: str, auth_provider_id: str,
data: dict, id: str = None, is_new: bool = True):
"""Initialize credentials.
Args:
auth_provider_type: Provider type
auth_provider_id: Provider ID
data: Credential data
id: Credential ID
is_new: Is new credential
"""
@property
def id(self) -> str:
"""Return credential ID."""
@property
def auth_provider_type(self) -> str:
"""Return provider type."""
@property
def auth_provider_id(self) -> str:
"""Return provider ID."""
@property
def data(self) -> dict:
"""Return credential data."""
@property
def is_new(self) -> bool:
"""Return True if credential is new."""Multi-Factor Authentication
Multi-factor authentication system with pluggable MFA modules.
class MfaModule:
"""Base multi-factor authentication module."""
DEFAULT_TITLE = None
def __init__(self, hass: HomeAssistant, config: dict):
"""Initialize MFA module.
Args:
hass: Home Assistant instance
config: Module configuration
"""
@property
def id(self) -> str:
"""Return module ID."""
@property
def name(self) -> str:
"""Return module name."""
async def async_setup_flow(self, user_id: str) -> SetupFlow:
"""Return setup flow.
Args:
user_id: User ID
Returns:
Setup flow
"""
async def async_setup_user(self, user_id: str, setup_data: Any) -> str:
"""Set up MFA for user.
Args:
user_id: User ID
setup_data: Setup data
Returns:
Setup ID
"""
async def async_depose_user(self, user_id: str) -> None:
"""Remove MFA for user.
Args:
user_id: User ID
"""
async def async_is_user_setup(self, user_id: str) -> bool:
"""Check if user has MFA setup.
Args:
user_id: User ID
Returns:
True if user has MFA setup
"""
async def async_validation_flow(self, user_id: str, context: dict) -> ValidationFlow:
"""Return validation flow.
Args:
user_id: User ID
context: Validation context
Returns:
Validation flow
"""
async def async_validate(self, user_id: str, data: dict) -> bool:
"""Validate MFA.
Args:
user_id: User ID
data: Validation data
Returns:
True if validation successful
"""Authentication Constants
# Token types
TOKEN_TYPE_NORMAL = "normal"
TOKEN_TYPE_SYSTEM = "system"
TOKEN_TYPE_LONG_LIVED_ACCESS_TOKEN = "long_lived_access_token"
# Authentication provider types
AUTH_PROVIDER_HOMEASSISTANT = "homeassistant"
AUTH_PROVIDER_LEGACY_API_PASSWORD = "legacy_api_password"
AUTH_PROVIDER_TRUSTED_NETWORKS = "trusted_networks"
AUTH_PROVIDER_COMMAND_LINE = "command_line"
# MFA module types
MFA_MODULE_TOTP = "totp"
MFA_MODULE_NOTIFY = "notify"
# Permission categories
CAT_ENTITIES = "entities"
CAT_CONFIG_ENTRIES = "config_entries"
CAT_AREAS = "areas"
CAT_DEVICES = "devices"
# Permission types
POLICY_READ = "read"
POLICY_CONTROL = "control"
POLICY_EDIT = "edit"
POLICY_ADMIN = "admin"
# Group IDs
GROUP_ID_ADMIN = "system-admin"
GROUP_ID_USER = "system-users"
GROUP_ID_READ_ONLY = "system-read-only"Types
from typing import Any, Dict, List, Optional, Union
from datetime import datetime, timedelta
# User types
UserType = Dict[str, Any]
GroupType = Dict[str, Any]
PermissionType = Dict[str, Any]
PolicyType = Dict[str, Any]
# Token types
RefreshTokenType = Dict[str, Any]
AccessTokenType = str
TokenDataType = Dict[str, Any]
# Authentication types
CredentialsType = Dict[str, Any]
UserMetaType = Dict[str, Any]
LoginFlowType = Any
SetupFlowType = Any
ValidationFlowType = Any
# Permission types
AbstractPermissions = Any
PermissionLookup = AnyInstall with Tessl CLI
npx tessl i tessl/pypi-homeassistantdocs
evals
scenario-1
scenario-2
scenario-3
scenario-4
scenario-5
scenario-6
scenario-7
scenario-8
scenario-9
scenario-10