Django components#

swh-auth implements some generic backends, models, views and middlewares to easily authenticate a user with Keycloak and OpenID Connect.

OIDC User model#

When swh-auth authenticates users with OIDC in a Django application, it creates an instance of the swh.auth.django.models.OIDCUser model and attaches it to the input django.http.HttpRequest object.

That model acts as a proxy for the django.contrib.auth.models.User model and is not persisted to database as user information is already stored in Keycloak database. As a consequence it will not be considered when calling the makemigrations command from Django application management CLI.

Authentication backends#

swh-auth provides two authentication backends to login users in Django applications:

These backends need to be configured through the following Django settings:

  • SWH_AUTH_SERVER_URL: Base URL of the Keycloak server to interact with

  • SWH_AUTH_REALM_NAME: Name of the realm to use in the Keycloak instance

  • SWH_AUTH_CLIENT_ID: Name of the client to use in the realm

Warning

These backends internally use the Django cache to store authenticated user data. In production environment, it is important to ensure the cache will be shared across the multiple WSGI workers (by using Django memcached cache backend for instance).

Authorization Code flow with PKCE backend#

This backend can be used to authenticate users with the OpenID Connect Authorization Code flow with PKCE (Proof Key for Code Exchange).

PKCE replaces the static secret used in the standard authorization code flow with a temporary one-time challenge, making it feasible to use in public clients.

When using that backend, users are redirected to the Keycloak login UI and are asked to enter their credentials. Once successfully authenticated, users will be redirected back to the Django application.

To use that backend, add "swh.auth.django.backends.OIDCAuthorizationCodePKCEBackend" to the AUTHENTICATION_BACKENDS Django setting.

The backend must be used in collaboration with the dedicated Login / logout views implementing the authentication flow.

Bearer token backend#

This backend for Django REST Framework enables to authenticate Web API users by sending long-lived OpenID Connect refresh tokens in HTTP Authorization headers.

Long lived refresh tokens can be generated in Keycloak by opening an OpenID Connect session with the following scope: openid offline_access.

To use that backend, add "swh.auth.django.backends.OIDCBearerTokenAuthentication" to the REST_FRAMEWORK["DEFAULT_AUTHENTICATION_CLASSES"] Django setting.

Users can then perform authenticated Web API calls by sending their refresh token in HTTP Authorization headers, for instance when using curl:

curl -H "Authorization: Bearer ${TOKEN}" https://....

Login / logout views#

In order to login / logout a user with OIDC Authorization code flow with PKCE, two dedicated Django views are available in swh-auth:

  • oidc-login (/oidc/login/ URL path): initiate authentication flow

  • oidc-logout (/oidc/logout/ URL path): terminate OIDC user session, a next query parameter can be used to redirect to a view of choice once a user is logged out

Add swh.auth.django.views.urlpatterns to your Django application URLs to use them.

Middlewares#

swh-auth provides the swh.auth.django.middlewares.OIDCSessionExpiredMiddleware middleware.

That middleware detects when a user previously logged in using the OpenID Connect authentication backend got his session expired.

In that case it redirects to a Django view whose name is set in the SWH_AUTH_SESSION_EXPIRED_REDIRECT_VIEW Django setting (typically a logout view).

The following query parameter will be set for that view:

  • next: requested URL before the detection of the OIDC session expiration

  • remote_user: indicates that the user was previously authenticated with OIDC

Minimal application example#

A sample minimal Django application using all the features mentioned above can be found in swh-auth Django tests tree.