Metadata-Version: 2.5
Name: keycloak-sdk
Version: 1.0.7
Summary: Keycloak SDK for Python — auth (OIDC/OAuth2) + Admin REST API, wrapping python-keycloak
Project-URL: Homepage, https://github.com/xzawed/KeyCloakSDK/tree/main/python
Project-URL: Repository, https://github.com/xzawed/KeyCloakSDK
Project-URL: Issues, https://github.com/xzawed/KeyCloakSDK/issues
Author-email: xzawed <xzawed31@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: admin,keycloak,oauth2,oidc,sso
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: joserfc<2,>=1.7
Requires-Dist: python-keycloak<8,>=7.1
Provides-Extra: dev
Requires-Dist: mypy<3,>=2.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=9.0; extra == 'dev'
Requires-Dist: ruff<0.18,>=0.6; extra == 'dev'
Requires-Dist: testcontainers[keycloak]>=4.14; extra == 'dev'
Description-Content-Type: text/markdown

# Keycloak SDK for Python

Authentication (OIDC / OAuth2) and the Admin REST API for [Keycloak](https://www.keycloak.org/) behind one consistent facade, with hardened JWT validation and a full async mirror.

Part of a **nine-language polyglot SDK** (Java · Python · Node · Go · C# · PHP · Rust · Ruby · Kotlin) — one API surface, isomorphic across all of them: [github.com/xzawed/KeyCloakSDK](https://github.com/xzawed/KeyCloakSDK).

> **`1.0.7` is on PyPI** — a bare `pip install keycloak-sdk` resolves it. A patch release on top of `1.0.6`; no public API changed. **Security**: the admin client now holds the access token it sends as a Bearer to one rule shared by all nine SDKs: leading and trailing SP, HTAB, CR and LF are stripped, and unless what remains is a non-empty RFC 6750 `b64token` (ASCII letters and digits and `-._~+/`, with `=` only at the end) the request is not sent and the call fails with `KeycloakAuthError`, which does not quote the token; the SDK's token providers do not cache such a token. Sync and `aio` now judge alike: sync used to send a leading tab, an inner space, Latin-1, C1 or NBSP as is, `aio` sent an inner space, and both rejected a trailing newline instead of stripping it. ⚠️ A token that ends in a newline used to be rejected and is now stripped and sent. The responses the SDK reads itself (token, introspection, JWKS and admin) are now read in full within the configured timeout, counted from when the request is sent. The timeout used to apply to each read only, so a server that trickled bytes, each just inside the read timeout, held one call for about the size cap times the read timeout (7 seconds with a 1-second setting); such a call now ends with the existing timeout error, within the deadline plus one read (exactly at the deadline on `aio`). The sync lane also checks that deadline on every raw read from the socket — the status line, headers, chunk-size lines, trailers and TLS records included — because with the body deadline alone, a server that trickled those held one http.client call for 7 seconds (1-second setting); it now ends at about 1.0 second with the same `KeycloakTransportError`. Still open: an HTTPS proxy (TLS inside TLS). A JWKS key set now expires 300 seconds after the load that fetched it finished, and an expired set is treated as a cold cache: the next validation fetches it again through the cold-load path (the same single flight and the same failure backoff) and rejects the token if that fetch fails, instead of validating with the stale keys. Until now the Python SDK gave a key set no lifetime, so it kept accepting a key the IdP had removed until a token with a new `kid` arrived. ⚠️ If the JWKS cannot be reached for more than 300 seconds, validation fails — by design, because the SDK cannot tell an unreachable JWKS from a key the IdP has removed. The failure backoff's jitter (×[0.5, 1.0)) was drawn again at every check, so the same failure could refuse a validation at 190 ms and send the next one to the IdP at 191 ms; it is now drawn once, when the failure happens. The backoff's exponent had no cap, so after about 1,025 consecutive failures an `OverflowError` kept the JWKS from ever being fetched again, even once the IdP was back (reproduced at 1,100); the exponent is now capped at 16. **Fixed**: this README said `keycloak_sdk.aio` does not block the event loop — every request is awaited, but `AsyncKeycloakClient.create(config)` and the first `kc.admin` access build the HTTP client and read the TLS trust store on the calling thread, which can take close to 1 second on Windows. The README now says so: create the client once when the application starts and reuse it. The behaviour is unchanged. **Changed**: ⚠️ a sync response now fails with `KeycloakTransportError` when it exceeds its byte budget, the body cap plus 65,536 bytes — 1,114,112 for token, introspection, logout and admin error responses, 116,736 for the JWKS, and none for an admin success body. Sync used to receive 16 MiB of trailers (on CPython versions that do not bound the number of trailers) and the tail after a gzip token body, and an admin error response with large framing came out as `KeycloakNotFoundError` and the like. A JWKS error message may now carry `HTTP response exceeds 116736 bytes on the wire`. ⚠️ An admin response — lists and `raw` success bodies included — must now arrive in full within the configured timeout (the response deadline above); a large list over a slow link used to be received to its end and is now a timeout error, so raise the timeout if you fetch large lists over a slow link. The Go, Rust, Node, PHP and .NET admin clients already behaved this way. ⚠️ The four `KeycloakConfigError` messages that were in Korean are now in English — `admin API access requires client_secret (client-credentials grant)` and `admin access requires config (use KeycloakClient.create(config))`, in the same form on `aio`. The exception types and cause chains are unchanged; only code that compares message strings is affected. The docstrings `help()` and IDEs show for the public API (what `__all__` of `keycloak_sdk` and `keycloak_sdk.aio` reaches) and the comments of the two examples this README links are now in English; the code is unchanged. `1.0.0` was the first release carrying the stability guarantee: a breaking change to the public API requires a **major** bump.
>
> `1.0.6` was a patch release on top of `1.0.5`; no public API changed. **Security**: the admin client read a response body to its end even after it had the result. python-keycloak sends its requests without `stream`, so requests (sync) and httpx (`aio`) read the whole body before the result is looked at: a server wrote all of the 64 MiB it attached to the 201 body of a `create` or the 2xx body of an `update` or `delete`, and a server that stalled after a 201's head turned a `create` that already had its `Location` into a `KeycloakTransportError` at the end of the read timeout (4,008–4,019 ms with a 4-second timeout). Error bodies were read whole too — a 404 with 64 MiB put 67,108,864 characters in `keycloak_error` (a peak of 201 MB for one call), a 65,278-byte gzip error body inflated to 64 MiB, and the tail after a gzip member was read to its end as well — sync and `aio` alike. The facade's write calls (`create`, `update` and `delete` on the five resources, sync and `aio`) now leave a 2xx body unread (the server wrote at most 458,754 bytes; 2–10 ms in front of a stalled server, plaintext and TLS 1.3), and an error body (3xx and above) is held only up to 1,048,576 bytes, the token-response cap: one byte more is read to see whether it goes over, the SDK itself decompresses within that cap, and nothing after the end of a compressed stream is read (a peak of 3.5 MB for one call with a 64 MiB error body). The exception class (`KeycloakNotFoundError` and the like) is unchanged and `keycloak_error` is cut at that length. A python-keycloak method called through `raw` still receives a 2xx body (its error body has the same cap), success bodies (`get`, `search`, lists) are not capped, the connection of a response not read to its end is discarded, and the connection of a 2xx with no body (an empty 201, a 204) is reused as before. Admin requests now ask for `Accept-Encoding: gzip, deflate` only — what the SDK can decompress within the cap. ⚠️ When `update` or `delete` gets a 2xx with a body instead of a 204 (python-keycloak expects only 204), the error is unchanged but its `keycloak_error` is empty, and against a server that sends a JSON body with a 201, `realms.create` no longer raises the `KeycloakTransportError` (python-keycloak's `TypeError`) it used to. `validate()` (sync and `aio`) also loaded the JWKS before it looked at the token, so on a cold cache one garbage token cost one IdP request. A token whose `len()` exceeds 256,000 is now rejected with `TokenValidationError` (`token exceeds 256000 bytes` — not a signature-failure subtype, so it triggers no refetch) before the JWKS is loaded or the token decoded, and the id_token check of a code exchange does the same. joserfc's limit on the payload segment (128,000 bytes by default) is raised to this cap — left at its default, it would reject a genuinely signed token within the cap (255,993 characters) as `TokenSignatureError`, and Python would accept different tokens from the other eight languages. The 512-byte limit on the header segment, which is decoded as JSON before the signature, is unchanged.
>
> `1.0.5` was a patch release on top of `1.0.4`; no public API changed. **Security**: when the admin client's own token grant fails, `KeycloakAdminError.keycloak_error` is now `None`. It used to carry the token endpoint's error body, so an IdP that echoed what it received (`Bad credentials: <secret>` in `error_description`) left the admin client secret — raw, form- or percent-encoded, or base64 as `client_id:secret` — or the admin refresh token in that attribute (`vars(e)`), sync and `aio` alike. The type, the message (`Keycloak admin error (HTTP <status>)`) and `status_code` are unchanged, and an error from an admin REST call itself still carries its body. An access token an HTTP header cannot carry — a C0 control character other than HTAB (CR, LF and NUL included), DEL, or a character the lane's transport cannot put in a header — is now refused with `KeycloakAuthError` before any admin request; the facade used to report some of these as a connection failure (`KeycloakTransportError`) and send others to the server in `Authorization`. A token the SDK's admin grant receives is not cached (`admin token grant returned an access token an HTTP header cannot carry (…)`; the next call requests a new one), and one that arrived another way — an injected `KeycloakAdmin(token=…)` or the `raw.connection.token` setter — fails as `admin request not sent: …`; neither message quotes the token. ⚠️ A python-keycloak method called through `raw` now stops on such a token with `KeycloakAuthError` instead of `keycloak.exceptions.KeycloakConnectionError`, and that error's chain no longer quotes the bearer as the one from requests or h11 did. **Fixed**: the sync client (`KeycloakClient`) no longer sends a request a second time on its own after the connection breaks. python-keycloak's session retry (`max_retries=1`, POST included — after a `503` with `Retry-After` it first slept that long) made the IdP receive token grants, introspection, logout, JWKS fetches, the admin client's creates, updates, deletes and reads, and `raw` actions twice, so a create could run twice and an authorization code or refresh token could be presented twice. The failure now raises the same SDK error at once (`KeycloakTransportError` for a transport failure). ⚠️ A call that a retry used to rescue on a connection that breaks once now fails, connection establishment included, and an adapter mounted through `raw` has its retry setting overwritten — retry the calls that are safe to repeat yourself. `aio` never sent a request twice and is unchanged.
>
> ⚠️ **One breaking change since `0.1.0`, and it is narrow** (it landed in `0.2.0`; `1.0.0` adds none): the `keycloak_sdk.jwt` module moved to `keycloak_sdk._internal.jwt`. Only code that imported `JwtValidator` **from that path directly** is affected — it was never in `__all__` and appears in no quickstart. The normal validation path, `kc.auth.validate(token)`, is unchanged. The move was structural: `py.typed` makes every module's signatures part of the public type surface, so a module under the top level was publishing joserfc's `KeySet` as part of this SDK's API.

## Requirements

- Python **3.10+**
- Ships the PEP 561 `py.typed` marker, so consumers can type-check with `mypy` too

## Install

```bash
pip install keycloak-sdk
```

The distribution name is `keycloak-sdk`; the import package is `keycloak_sdk`.

## Quickstart

```python
from keycloak_sdk import KeycloakClient, KeycloakConfig

config = KeycloakConfig(
    server_url="https://kc.example.com",
    realm="myrealm",
    client_id="admin-cli",
    client_secret="changeme",  # load the real value from an env var / secrets manager
)

# The `with` block closes both sessions on exit — the auth session and, since the admin facade owns its own `requests.Session` pair, those too (`AdminClient.close()` is not a no-op).
with KeycloakClient.create(config) as kc:
    # 1) Issue a client-credentials token. repr(TokenSet) masks every token value.
    token = kc.auth.client_credentials_token()

    # 2) Validate it — algorithm pinning, exact iss, aud containment, mandatory exp, clock skew.
    validated = kc.auth.validate(token.access_token)
    print(f"subject={validated.subject} aud={validated.audience}")

    # 3) Admin API — admin is created lazily on first access. create() returns the new user id.
    user_id = kc.admin.users.create({"username": "alice", "enabled": True})
    users = kc.admin.users.search(first=0, max=20)
```

`validate()` expects the token's `aud` to contain `client_id` by default, but a stock realm does not put the client id into a client-credentials token. Either set `expected_audience="my-api"` on the config to check the audience your tokens actually carry, or add an audience mapper to the client in Keycloak (Client scopes → dedicated scope → Add mapper → Audience). `expected_audience` applies to access tokens only: the id_token that `exchange_code(..., nonce=...)` verifies must always carry `client_id` in `aud` (OIDC Core §3.1.3.7).

### Async

`keycloak_sdk.aio` is a complete async mirror — same method names (the sync `close()` is `aclose()` here), value types, and exceptions — and every network call is awaited, so requests do not block the event loop (FastAPI and friends). Construction does block it: `AsyncKeycloakClient.create(config)` and the first access to `kc.admin` build their HTTP clients and load the TLS trust store on the calling thread, which takes a noticeable fraction of a second on Windows. Create one client when the application starts and reuse it:

```python
from keycloak_sdk import KeycloakConfig
from keycloak_sdk.aio import AsyncKeycloakClient


async def run(config: KeycloakConfig) -> None:
    async with AsyncKeycloakClient.create(config) as kc:
        token = await kc.auth.client_credentials_token()
        validated = await kc.auth.validate(token.access_token)
        users = await kc.admin.users.search(first=0, max=20)
```

Among the client's methods, only `authorization_url` stays synchronous — it assembles a URL and needs no network.

## Security defaults

The SDK replaces the unsafe library defaults rather than inheriting them:

- **Algorithm pinning** — the header-supplied `alg` is never trusted, so `alg: none` and HS/RS confusion are rejected structurally: joserfc decodes against the configured allowlist, and an empty allowlist is refused at construction rather than falling back to joserfc's permissive default set.
- **Strict claim checks** — exact `iss` match, `aud` containment, mandatory `exp`, `nbf` enforced when present, and a bounded clock skew.
- **DoS-safe JWKS** — a key set is used for at most 300 s after its fetch completed; the next validation then fetches it again like a cold cache, and if that fetch fails the validation fails (no fallback to the old keys, even during an IdP outage). Within that age, a refetch is triggered only by an unresolved key ID and never by a bad signature, and is rate-limited to a minimum interval (`jwks_min_refetch_seconds`, 30s by default) — so **once the key set has been fetched**, no volume of forged tokens makes the SDK issue more than one forced JWKS request per interval. A *failed* fetch is bounded separately: consecutive failures back off exponentially (0.2s, doubling, capped at 5s, with jitter), and inside that window the SDK **fails fast without contacting the IdP**. So a cold cache during an IdP outage no longer turns every validation into a request (measured: 20 attempts → 1 request, down from 20; the sync and async clients share the same state machine). ⚠️ The SDK never sleeps — it returns the error immediately, so retry pacing stays the caller's decision.
- **Bounded token input** — a token longer than 256,000 bytes is rejected with `TokenValidationError` before it is decoded and before any JWKS request.
- **Secret handling** — `repr()` of the config and token types masks secrets and tokens as `***` (no prefix leak), and TLS verification is on by default.

Masking covers this SDK's own `repr()`; it cannot cover what your logging framework or a traceback does with a value you hand it. Python has no erasable string type, so the client secret lives in an ordinary `str` for its lifetime — masking is defence in depth, not an erasure guarantee.

## Versioning and support

This SDK is **`1.0`** and follows SemVer: a breaking change to the public API requires a **major** bump. That promise is machine-backed — CI diffs this lane's public API against the **previously published artifact** on every build (`griffe check`), and a removal or an incompatible change fails the build. ⚠️ **The gate compares the API _surface_.** A change that leaves the surface identical but alters behaviour is not caught by it, so read the release notes before upgrading.

Only the newest released version of each language SDK receives security fixes; there are no long-term-support lines and older releases are not backported to.

**Each of the nine languages versions independently.** All nine reached `1.0.0` in the same release wave because they earned the same guarantee at the same time — they do **not** move in lockstep afterwards.

## Documentation

- [Project overview](https://github.com/xzawed/KeyCloakSDK) — all nine languages, what is identical and what is not
- [Changelog](https://github.com/xzawed/KeyCloakSDK/blob/main/CHANGELOG.md) — **read this before upgrading**; breaking changes are listed per language
- [Getting started](https://github.com/xzawed/KeyCloakSDK/blob/main/docs/guides/getting-started.md#python) — install and quickstart for this language
- [Compatibility](https://github.com/xzawed/KeyCloakSDK/blob/main/docs/reference/compatibility.md) — which Keycloak server range and base libraries each published version shipped against
- [Deploying a Keycloak server](https://github.com/xzawed/KeyCloakSDK/blob/main/docs/guides/deploying-keycloak-server.md) — the server this SDK talks to
- [Security policy](https://github.com/xzawed/KeyCloakSDK/blob/main/SECURITY.md)
- Full examples: [`quickstart.py`](https://github.com/xzawed/KeyCloakSDK/blob/main/python/examples/quickstart.py) · [`async_quickstart.py`](https://github.com/xzawed/KeyCloakSDK/blob/main/python/examples/async_quickstart.py)

## License

[Apache-2.0](https://github.com/xzawed/KeyCloakSDK/blob/main/python/LICENSE)
