API reference

class nameko_keycloak.auth.AuthenticationService(keycloak: KeycloakOpenID, fetch_user: Callable[[str, dict[str, Any]], Any | None], sso_cookie_prefix: str = 'nameko-keycloak')

Provides a way to retrieve properly authenticated user from a request.

As we store user credentials in an external service (Keycloak), this service checks for two things:

• first, validate access token found in the request

• if Keycloak confirms the token is valid, look up local User

Only when the user exists in both Keycloak and local database, we consider them authenticated.

get_user_from_access_token(access_token: str) → Any | None

Find a local User corresponding to Keycloak access token.

get_user_from_request(request: Request, **kwargs) → Any | None

Find a local User corresponding to some token in the HTTP request.

nameko_keycloak.auth.get_token_from_request(request: Request, cookie_name: str) → str | None

Try to locate access token in the incoming request.

The function first reads access token from a (HttpOnly) cookie sent by a browser. If such cookie does not exist, we try a standard OAuth2 approach with token in header (sent by Oauth2 clients like Insomnia).

class nameko_keycloak.dependencies.KeycloakProvider(*args, **kwargs)

get_dependency(worker_ctx) → KeycloakOpenID

Called before worker execution. A DependencyProvider should return an object to be injected into the worker instance by the container.

setup() → None

Called on bound Extensions before the container starts.

Extensions should do any required initialisation here.

class nameko_keycloak.fakes.FakeKeycloak

Fake to be used wherever tests need to interact with Keycloak.

This class emulates a few APIs of KeycloakOpenID that we use for SSO workflow.

We’re working under a very important assumption here: You need to pass user’s email as code when generating their token. This is obviously not true in real life where Keycloak manages generating secure tokens from one-time codes, but here it simplifies a lot.

The Keycloak user database is simulated by a key-value storage where you insert an item when calling token(), and fetch from storage when calling decode_token() or refresh_token().

class nameko_keycloak.service.HookMethod(*values)

class nameko_keycloak.service.KeycloakSsoServiceMixin

Add this to your nameko service to provide SSO authentication with Keycloak.

Expected service dependencies or class attributes:

• keycloak which must be an instance of KeycloakProvider

• sso_cookie_prefix - a string that will be used to namespace cookies (useful when there are multiple SSO-enabled apps hosted on same domain)

• sso_cookie_path - path part of the URL of your application, set as Path cookie attribute

• sso_login_url - absolute URL to handler which delegates to keycloak_login_sso()

• sso_token_url - absolute URL to handler which delegates to keycloak_token_sso()

• sso_refresh_token_url - absolute URL to handler which delegates to keycloak_refresh_token_sso()

• frontend_url - absolute URL to a user-facing web app that communicates with this backend service

keycloak_login_sso(request: Request) → Response

Redirects to SSO login form configured to return back to HTTP service.

keycloak_logout(request: Request) → Response

Invalidates session in Keycloak, deletes cookies and redirects to login.

Note

Keycloak logout API invalidates only refresh token, not access token. This is by design, as access tokens should be short lived anyway.

keycloak_refresh_token_sso(request: Request) → Response

Generates a new access token, given a cookie with a valid refresh token.

keycloak_token_sso(request: Request) → Response

Handles redirect from successful login in SSO.

The SSO passes a code query string parameter which we then use to generate a OAuth access token. We make sure that a local User exists before they are allowed to reach frontend URL. If all goes well, the access token and several other metadata are stored in cookies.

keycloak_validate_token_sso(request: Request) → Response

Checks that access token is valid and a corresponding local User exists.