Documentation for Kamiwaza 0.8.0

This is documentation for Kamiwaza 0.8.0, which is no longer actively maintained. For the current GA release, see 1.0.1.

Overview

The Authentication Service (AuthService) provides comprehensive user authentication and authorization functionality for the Kamiwaza AI Platform. Located in kamiwaza_client/services/auth.py, this service handles user management, token-based authentication, and role-based access control (RBAC).

Key Features

• User Authentication (token-based)
• Local User Management
• Organization Management
• Role-Based Access Control (RBAC)
• Group Management
• Permission Management

Authentication Methods

Token-Based Authentication

# Login to get access token

token = client.auth.login_for_access_token(
    
    username="user@example.com",
    
    password="secure_password"
)

# Verify token

user = client.auth.verify_token(authorization="Bearer <token>")

Local Authentication

# Create local user

user = client.auth.create_local_user(LocalUserCreate(
    
    username="newuser",
    
    email="user@example.com",
    
    password="securepass"
))

# Login locally

token = client.auth.login_local(username="newuser", password="securepass")

User Management

Available Methods

• create_local_user(user: LocalUserCreate) -> User: Create a new local user
• list_users() -> List[User]: List all users in the system
• read_users_me(authorization: str): Get current user's information
• read_user(user_id: UUID) -> User: Get specific user information
• update_user(user_id: UUID, user: UserUpdate) -> User: Update user details
• delete_user(user_id: UUID): Delete a user
• read_own_permissions(token: str) -> UserPermissions: Get current user's permissions

Organization Management

Available Methods

• create_organization(org: OrganizationCreate) -> Organization: Create new organization
• read_organization(org_id: UUID) -> Organization: Get organization details
• update_organization(org_id: UUID, org: OrganizationUpdate) -> Organization: Update organization
• delete_organization(org_id: UUID): Delete an organization

Group Management

Available Methods

• create_group(group: GroupCreate) -> Group: Create new group
• read_group(group_id: UUID) -> Group: Get group details
• update_group(group_id: UUID, group: GroupUpdate) -> Group: Update group
• delete_group(group_id: UUID): Delete a group
• add_user_to_group(user_id: UUID, group_id: UUID): Add user to group
• remove_user_from_group(user_id: UUID, group_id: UUID): Remove user from group

Role Management

Available Methods

• create_role(role: RoleCreate) -> Role: Create new role
• read_role(role_id: UUID) -> Role: Get role details
• update_role(role_id: UUID, role: RoleUpdate) -> Role: Update role
• delete_role(role_id: UUID): Delete a role
• assign_role_to_group(group_id: UUID, role_id: UUID): Assign role to group
• remove_role_from_group(group_id: UUID, role_id: UUID): Remove role from group

Rights Management

Available Methods

• create_right(right: RightCreate) -> Right: Create new right
• read_right(right_id: UUID) -> Right: Get right details
• update_right(right_id: UUID, right: RightUpdate) -> Right: Update right
• delete_right(right_id: UUID): Delete a right
• assign_right_to_role(role_id: UUID, right_id: UUID): Assign right to role
• remove_right_from_role(role_id: UUID, right_id: UUID): Remove right from role

Error Handling

The service includes built-in error handling for common authentication scenarios:

try:
    
token = client.auth.login_for_access_token(username="user", password="pass")
    
except AuthenticationError:
    
    # Handle authentication failures
    
except APIError as e:
    
    # Handle API errors
    
    print(f"Operation failed: {e}")

Best Practices

1. Always use secure passwords and handle credentials securely
2. Implement proper token management (storage and refresh)
3. Use role-based access control for granular permissions
4. Regular audit of user permissions and access rights
5. Clean up unused users, groups, and roles