Skip to content

feat: add a Keycloak auth handler - #51

Open
mxw94 wants to merge 4 commits into
FraunhoferIOSB:masterfrom
mxw94:feat/keycloak-auth-handler
Open

feat: add a Keycloak auth handler#51
mxw94 wants to merge 4 commits into
FraunhoferIOSB:masterfrom
mxw94:feat/keycloak-auth-handler

Conversation

@mxw94

@mxw94 mxw94 commented Aug 13, 2026

Copy link
Copy Markdown

Add a Keycloak auth handler

Adds KeycloakAuthHandler, an AuthHandler for FROST servers that delegate
authentication to Keycloak. It obtains an access token
from Keycloak via the password grant and sends it as a bearer token, caching the
token until shortly before it expires so a client that sends many requests does
not request a new token per request.

Usage mirrors the existing basic-auth handler:

import frost_sta_client as fsc

auth_handler = fsc.KeycloakAuthHandler(server_url="https://keycloak.example.com",
                                       realm_name="my-realm",
                                       client_id="frost-client",
                                       username="user",
                                       password="pass")
service = fsc.SensorThingsService(url, auth_handler=auth_handler)

Changes

  • frost_sta_client/service/keycloak_auth_handler.py — the handler, built on
    python-keycloak (added to requirements.txt and setup.py).
  • Exported as fsc.KeycloakAuthHandler.
  • README: a short "Authentication" section covering basic auth and Keycloak.
  • Integration test: tests/test_keycloak_integration.py plus a session fixture
    in tests/conftest.py that starts a Keycloak-protected FROST server from
    frost_server/docker-compose.keycloak.yml (with frost_server/realm-frost-test.json),
    mirroring the existing frost_server fixture. The happy-path test authenticates
    through KeycloakAuthHandler and creates and reads a Thing.

Testing

  • Unit suite: pytest — passes (integration tests skipped without the flag).
  • Integration: FROST_STA_CLIENT_RUN_INTEGRATION=1 pytest tests/test_keycloak_integration.py
    brings up the stack, authenticates, and performs an authenticated create/read.

Notes for reviewers

  • The integration stack addresses Keycloak and FROST through the host's own IP
    (EXTERNAL_IP, filled in by the fixture) so the token issuer is identical
    whether the token is minted on the host or validated inside the FROST
    container.

Servers that delegate authentication to Keycloak need a bearer token rather than
basic auth. KeycloakAuthHandler obtains an access token from Keycloak via the
password grant and caches it until shortly before it expires, so a client that
sends many requests does not request a new token per request.

Ported from the thingsboard-frost-adapter, based on python-keycloak.
A docker compose stack with a Keycloak-protected FROST server, a matching realm
import, and a session fixture that starts it (mirroring the basic-auth fixture).
The happy-path test authenticates through KeycloakAuthHandler and creates and
reads a Thing.
Keep the Keycloak compose file and its realm import next to the existing
FROST compose file, as docker-compose.keycloak.yml.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants