ACKC Release v1.0.0

Changes

[v1.0.0] Refactor API wrappers to use centralized helper methods

Date: Thu Aug 7 02:37:26 2025 -0700

Replace manual additional_properties handling with BaseAPI helpers
throughout all API modules. Fix parameter passing, response checks,
and async/sync consistency issues.

Add project infrastructure:

• Apache 2.0 license and contributing guidelines
  • NOTE: Above incorrectly referenced MIT license in commit message
• GitHub Actions workflow for PyPI publishing
• Python packaging configuration with uv
• CLI tool initialization module

API fixes:

• Use _sync_ap/_async_ap for additional_properties extraction
• Use _sync_ap_list/_async_ap_list for list comprehensions
• Use _sync, _sync_detailed, and _sync_detailed_model properly
• Fix operations without body params to use correct helpers
• Correct missing parameters and type signatures
• Standardize response unwrapping and error handling

Update documentation and configure project metadata for distribution.

Complete API coverage with proper type annotations and response unwrapping

Date: Wed Aug 6 17:12:06 2025 -0700

• Add missing API modules: attack_detection, client_initial_access,
  client_attribute_certificate, client_registration_policy, scope_mappings,
  client_role_mappings, role_mapper, roles_by_id
• Fix return type annotations to use specific model types instead of generic
  list/dict throughout all API modules
• Unwrap response wrapper types that only contain additional_properties
• Update all method docstrings with proper Args, Returns, and Raises sections
• Export APIError alongside AuthError for consistency
• Ensure 100% Keycloak Admin API endpoint coverage

Add OpenAPI spec download automation to client generation

Date: Wed Aug 6 14:07:08 2025 -0700

• Create download_openapi.py to fetch latest Keycloak OpenAPI spec.
• Track spec changes via SHA256 hash in metadata file.
• Auto-download spec when missing or with -d/--download flag.

Add 2FA/OTP support to password authentication

Date: Tue Aug 5 20:37:25 2025 -0700

Implement two-factor authentication support by adding OTP parameter to password
grant methods. OTP codes are sent as a separate 'totp' field to Keycloak.
Also includes CLI support via --otp and --otp-code flags.

Additional changes:

• Standardize all string quotes to use double quotes for consistency
• Update CLI tools to support OTP authentication
• Fix token acquisition functions to pass OTP parameter through

Refactor token acquisition APIs for security and clarity

Date: Tue Aug 5 19:30:12 2025 -0700

• Add OAuth2 scope support to all token acquisition methods
• Enforce keyword-only arguments for all public token methods
• Make device flow callback required (was optional but essential)
• Update CLI tool to use subcommands for better UX
• Fix documentation to reference correct auth-token command
• Add typed callback signatures for device flow

Breaking changes:

• All token methods now require keyword arguments
• Device flow callback is now mandatory
• CLI uses subcommands instead of flags for auth methods

Update token tool defaults

Date: Tue Aug 5 12:58:17 2025 -0700

• Set client-id and client-secret defaults to None in argparse
• Allows for default override in the client factory

Refactor environment handling and improve auth configuration

Date: Tue Aug 5 12:28:51 2025 -0700

• Add ackc.env module with KEYCLOAK_ENV_PREFIX support for multi-project deployments
• Add KEYCLOAK_AUTH_REALM environment variable for separate auth realm configuration
• Refactor all modules to use centralized env handling
• Add client_secret parameter to password auth methods for confidential clients
• Rename jwt_decode → jwt_userinfo for clarity (server-side validation)
• Move JWT parsing to BaseKeycloakClient.jwt_decode() class method
• Clean up KeycloakClient by removing redundant init override
• Fix token tool: use keyword args, proper imports, remove bad exception handling
• Bump version to 0.5.0 and upgrade deps:
  • - anyio==4.9.0
  • + anyio==4.10.0
  • - certifi==2025.7.14
  • + certifi==2025.8.3
  • - urllib3-future==2.13.900
  • + urllib3-future==2.13.901

Modernize and refactor auth-token tool for reusability

Date: Tue Aug 5 00:04:36 2025 -0700

• Remove async usage from get_token_device() in favor of sync version
• Add missing sync get_token_device() method to BaseKeycloakClient
• Refactor tool into composable functions for Django integration
• Add init_parser() to support Django's add_arguments pattern
• Support dict args in run() for Django management commands
• Use callback pattern for device flow instead of hardcoded prints
• Add client factory pattern with env-aware default factory
• Remove redundant comments and clean up code
• Add comprehensive module docstring with usage examples

Make realm parameter optional in base and API classes

Date: Mon Aug 4 23:24:36 2025 -0700

• Made realm optional in BaseKeycloakClient methods (defaults to self.realm)
• Fixed jwt_refresh parameter order for consistency with other jwt_* methods
• Updated export_realm_config to use cleaner pattern for realm default
• Removed unnecessary hasattr() checks when calling to_dict()
• Fixed return type in realms.py API from dict to RealmRepresentation
• All API modules now have realm as optional parameter (except realms.py)

Improve realm parameter handling and fix API return types

Date: Mon Aug 4 23:07:33 2025 -0700

• Make realm parameter optional (defaults to instance realm) across all methods
• Use "realm = realm or self.realm" pattern to avoid repetition
• Fix RealmsAPI.get() and aget() to return RealmRepresentation instead of dict
• Remove unnecessary hasattr() checks in export_realm_config - objects always have to_dict()
• Make parameter order consistent for jwt_refresh methods (refresh_token first)
• Update method docstrings to indicate realm defaults to instance realm
• Bump version to 0.3.1

These changes make the API more consistent and improve type safety by ensuring
proper return types from API methods.

Add OAuth2 methods and improve token handling

Date: Mon Aug 4 22:21:32 2025 -0700

• Bump version to 0.3.0
• Add exchange_authorization_code() for OAuth2 authorization code flow
• Add jwt_refresh() to refresh tokens using refresh tokens
• Add needs_refresh property to check if internal token needs refreshing
• Add jwt_needs_refresh() static method for external JWT validation
• Fix get_token() to return full token dict instead of just access token string
• Fix refresh_token() to actually use refresh tokens when available
• Make token properties private (_access_token, _refresh_token)
• Update get_login_url() to accept params for flexible query parameters
• Add refresh_buffer_seconds parameter for token expiry checking
• Fix get_token_device() to return full token response

CLI improvements:

• Add mutually exclusive argument groups to get-token tool
• Require --password when --username is provided
• Support quiet mode for password prompts
• Fix help text formatting with raw description formatter
• Improve mc.py health check output to identify probe type

Code cleanup:

• Remove obvious inline comments from non-generated files
• Keep docstrings and meaningful comments intact
• Fix error handling to use specific exception types

Add JWT validation methods and improve token handling in KeycloakClient

Date: Mon Aug 4 19:27:30 2025 -0700

• Add jwt_decode() method to get user info from JWT via OIDC userinfo endpoint
• Add jwt_introspect() method for token validation via introspection endpoint
• Update get_token_password() to return full token response dict
• Refactor internal token storage from string to dict for access to all fields
• Add access_token property for safe extraction of JWT from token response
• Add InvalidTokenError exception for malformed tokens
• Improve method naming and docstrings with detailed return value examples
• Update version to 0.2.1

Update readme.md with updated Keycloak documentation links and examples

Date: Wed Jul 30 15:00:35 2025 -0700

• Fix broken Keycloak documentation URLs across various API sections.
• Add example for auth-mc management command.
• Expand authentication examples with Cloudflare integration and auth realm overrides.

Update readme.md for attrs models and Keycloak 26+ compatibility

Date: Wed Jul 30 14:25:47 2025 -0700

• Replace Pydantic with attrs in documentation.
• Update Keycloak version requirement to 26+.
• Add instructions to delete unnecessary generated files.

Add Keycloak management interface client and CLI tool

Date: Wed Jul 30 13:52:33 2025 -0700

• Create KeycloakManagementClient for health/metrics endpoints (port 9000)
• Add attrs-based models for health responses (HealthCheck, HealthResponse)
• Implement auth-mc CLI tool with health and metrics commands
• Support text and JSON output formats for all endpoints
• Add KEYCLOAK_MANAGEMENT_URL environment variable support
• Enable KC_HEALTH_ENABLED and KC_METRICS_ENABLED in docker compose
• Remove custom Dockerfile in favor of standard Keycloak image with env vars
• Bump version to 0.2.0

Add registration and login utilities for Keycloak clients

Date: Wed Jul 30 13:06:00 2025 -0700

• Introduced utility methods for building URLs for login, registration, and realm configuration.
• Enhanced async and sync support for checking registration enablement.
• Updated dependencies to include attrs.
• Improved documentation and examples for key methods.

Initial project files.

Date: Wed Jul 30 00:58:02 2025 -0700

Installation

uv add ackc==1.0.0