Skip to content

5.21.0 — 2026-10-24

← 5.21.1 | 5.20.1 → | ↑ 5.x series

Added

Models - Keycloak DTOs

  • Keycloak DTO Package - Added archipy.models.dtos.keycloak with pydantic DTOs for every Keycloak admin REST representation the adapter uses, generated from the Keycloak admin OpenAPI spec.
    • KeycloakBaseDTO is standalone and does not derive from BaseDTO, whose extra="ignore" would hide typos and drop fields newer Keycloak versions add
    • Request DTOs (Keycloak*RequestDTO) forbid unknown fields, matching the Unrecognized field 400 that Keycloak answers
    • Response DTOs (Keycloak*DTO) keep unknown fields in model_extra
    • Dict-style access on responses (result["id"], result.get("id")) and dict payloads still work and emit a DeprecationWarning until 6.0.0
  • Typed Results - Create, update, delete and assign calls return KeycloakCreateResultDTO, KeycloakUpdateResultDTO, KeycloakDeleteResultDTO or KeycloakAssignResultDTO instead of a dict or bytes.
    • Create results carry the id of the new resource, found by lookup because Keycloak answers with an empty body
    • skip_exists creates report msg == "Already exists" and no id
  • Typed Token Data - Tokens, UserInfo, decoded and introspected claims, the discovery document and the JWKS are KeycloakTokenDTO, KeycloakUserInfoDTO, KeycloakTokenClaimsDTO, KeycloakWellKnownDTO and KeycloakCertsDTO.
  • Typed Protocol Mapper Configs - Added one config DTO for each of 51 protocol mapper types (OIDC, SAML, oid4vc, docker-v2) in protocol_mapper_config_dtos, with to_config(), to_mapper(name), from_config() and parse_protocol_mapper_config().
  • Token Exchange Types - Added TokenExchangeTokenType and the token exchange and AuthZEN DTOs.

Adapters - Keycloak

  • Calls python-keycloak Lacks - Added about 280 admin calls, made through the admin connection with its error handling.
    • Realms: list, delete, events, admin events, event settings, client policies, profiles, types, default groups, localization, partial import and export, logout-all, revocation push, session deletion, SMTP test
    • Users: filtered list and count, user profile, credentials, consents, federated identities, sessions, groups, impersonation, email actions
    • Clients: list, get, update, delete by UUID, secrets, registration token, scope evaluation, installation providers, nodes, session counts
    • Roles by name and by id, role mappings and scope mappings for users, groups, clients and client scopes
    • Identity providers with mappers, organizations (identity providers, members, invitations, groups and role mappings), required actions, authentication providers, realm keys, brute force detection, client initial access tokens, client certificates
    • Authorization services: settings, filtered lists, searches, resource and scope details, providers, policy and permission evaluation
    • Protocol mappers: get by id, bulk add, list by protocol
  • Token Exchange - token_exchange(KeycloakTokenExchangeRequestDTO) covers standard token exchange (V2), the delegation preview and the legacy fields, and can exchange a token for a JWT assertion.
  • JWT Authorization Grant - jwt_bearer_grant(assertion, scope) implements RFC 7523 and the identity assertion grant (ID-JAG). With token_exchange it chains identity across two realms.
  • RPT Requests - request_rpt(token, audience, permissions) performs the UMA ticket grant of the authz-client library.
  • AuthZEN - get_authzen_configuration, authzen_evaluation and authzen_evaluations call the experimental AuthZEN endpoints with the caller's own bearer token. Keycloak 26.8 rejects an evaluation without resource.type, so the DTO requires it.
  • Typed Mapper Calls - add_*_mapper_with_config, update_*_mapper_config and get_*_mapper_config add, replace and read a client scope or client protocol mapper from a typed config.
  • Request DTOs for Config - create_realm, update_realm, create_client, create_organization and update_organization accept an optional config request DTO next to their keyword arguments.

Changed

Adapters - Keycloak

  • Resource Layout - breaking: the adapter is organized by Keycloak admin REST resource. The adapter_mixins and port_mixins packages are removed and resources/ and protocols/ are private (_resources, _protocols, _base, _connection, _type_aliases).
    • Import KeycloakAdapter, AsyncKeycloakAdapter, KeycloakPort, AsyncKeycloakPort and the Keycloak*Type names from archipy.adapters.keycloak.adapters and archipy.adapters.keycloak.ports
    • archipy.adapters.keycloak.auth is unchanged
  • DTO Return Types - behavior: methods that returned dict, bytes or a TypedDict return DTOs. isinstance(result, dict) is now false. The Keycloak*Type names for groups, roles, organizations, client scopes, protocol mappers and components are aliases of the DTOs.
  • Auth Context - behavior: AuthenticatedUserDTO.raw_user_info and token_info are KeycloakUserInfoDTO and KeycloakTokenClaimsDTO. The fastapi_auth dependency yields the user info DTO. request.state values are still deprecated dicts.
  • Not Found Mapping - behavior: every Keycloak 404 maps to ResourceNotFoundError, where some used to surface as InternalError.

Not Supported

  • Workflows - The server answers workflow calls as YAML and the admin connection cannot set Accept per call.
  • Non-JSON Bodies - Calls that send text/plain, multipart or form-encoded bodies are left out: user credential label, realm localization single text, client description converter, certificate uploads, organization invite-user and invite-existing-user.

Tests

Tests - Keycloak

  • Scenarios by Concern - Tagged the Keycloak scenarios (@realms, @users, @roles, @tokens, @authz, @organizations, @clientscopes, @groups and others) so a subset can run on its own.
  • Live Coverage - Added sync and async scenarios against a real Keycloak for the new calls, including token exchange, the JWT grant, chaining across two realms, RPT requests, AuthZEN, typed mapper configs that change real tokens, and Keycloak's own rejection of unknown fields.
  • DTO Scenarios Without Containers - Added keycloak_dtos.feature and keycloak_protocol_mapper_configs.feature for DTO behavior.
  • Test Container Command - KeycloakContainer replaces any with_command call with its cmd argument, so the old feature list was never applied. The container now starts with --features=organization,authzen.

Chore

  • Ruff Settings - Registered the Keycloak DTO bases as runtime-evaluated pydantic classes and updated the per-file ignores for the new layout.
  • Docs - Rewrote the Keycloak tutorial for the DTO style and the new calls, and added every Keycloak DTO module to the DTO API reference.