Metadata-Version: 2.5
Name: keycloak-sdk
Version: 1.0.6
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.6` is on PyPI** — a bare `pip install keycloak-sdk` resolves it. 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.0` was the first release carrying the stability guarantee: a breaking change to the public API requires a **major** bump.
>
> `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 — so it never blocks the event loop (FastAPI and friends):

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


async def handler(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)
```

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 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 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)
