drf-keycloak-auth 0.5.3

A convenience libary for authenticating users from Keycloak access tokens

DRF Keycloak Auth

Requirements

• Python >= 3.10
• Django
• Django Rest Framework
• Python Keycloak

Installation

$ pip install drf-keycloak-auth

Add the application to your project's INSTALLED_APPS in settings.py.

INSTALLED_APPS = [
    ...
    'drf_keycloak_auth',
]

In your project's settings.py, add this to the REST_FRAMEWORK configuration. Note that if you want to retain access to the browsable API, then you will want KeycloakSessionAuthentication too.

REST_FRAMEWORK = {
  ...
  'DEFAULT_AUTHENTICATION_CLASSES': [
    ...
    'drf_keycloak_auth.authentication.KeycloakSessionAuthentication',
    'drf_keycloak_auth.authentication.KeycloakAuthentication',
  ]
}

The drf_keycloak_auth application comes with the following settings as default, which can be overridden in your project's settings.py file. Make sure to nest them within DRF_KEYCLOAK_AUTH as below:

# should be comma separated string
KEYCLOAK_ROLES_TO_DJANGO_IS_STAFF = \
    os.getenv('KEYCLOAK_ROLES_TO_DJANGO_IS_STAFF')

DEFAULTS = {
    'KEYCLOAK_SERVER_URL': os.getenv('KEYCLOAK_SERVER_URL'),
    'KEYCLOAK_REALM': os.getenv('KEYCLOAK_REALM'),
    'KEYCLOAK_CLIENT_ID': os.getenv('KEYCLOAK_CLIENT_ID'),
    'KEYCLOAK_CLIENT_SECRET_KEY': os.getenv('KEYCLOAK_CLIENT_SECRET_KEY'),
    'KEYCLOAK_VERIFY_SSL': os.getenv('KEYCLOAK_VERIFY_SSL', True),
    'KEYCLOAK_AUTH_HEADER_PREFIX':
        os.getenv('KEYCLOAK_AUTH_HEADER_PREFIX', 'Bearer'),
    'KEYCLOAK_ROLE_SET_PREFIX':
        os.getenv('KEYCLOAK_ROLE_SET_PREFIX', 'role:'),
    'KEYCLOAK_MANAGE_LOCAL_USER':
        os.getenv('KEYCLOAK_MANAGE_LOCAL_USER', True),
    'KEYCLOAK_MANAGE_LOCAL_GROUPS':
        os.getenv('KEYCLOAK_MANAGE_LOCAL_GROUPS', False),
    'KEYCLOAK_DJANGO_USER_UUID_FIELD':
        os.getenv('KEYCLOAK_DJANGO_USER_UUID_FIELD', 'pk'),
    'KEYCLOAK_FIELD_AS_DJANGO_USERNAME':
        os.getenv('KEYCLOAK_FIELD_AS_DJANGO_USERNAME', 'preferred_username'),
    'KEYCLOAK_ROLES_TO_DJANGO_IS_STAFF': (
        [x.strip() for x in KEYCLOAK_ROLES_TO_DJANGO_IS_STAFF.split(',')]
        if KEYCLOAK_ROLES_TO_DJANGO_IS_STAFF
        else ['admin']  # can be list, tuple or set
    )
}

All you need to do now is have your client code handle the Keycloak authentication flow, retrieve the access_token for the user, and then use the access_token for the user in an Authorization header in requests to your API.

Bearer <token>

Roles will be present in request.roles with a KEYCLOAK_ROLE_SET_PREFIX prefix (only if succesfully authenticated), e.g.:

['role:admin', 'a4a9be6e-bd04-42f8-9377-27d9db82216f']

except for the authenticated user's pk field, e.g. for a user model using uuid's as primary key:

['role:user', 'a4a9be6e-bd04-42f8-9377-27d9db82216f']

where the pk can be used for checking object ownership.

If you wish to create your own role permissions:

https://www.django-rest-framework.org/api-guide/permissions/#custom-permissions

simply import and use the prefix helper:

from .keycloak import prefix_role

ROLE_USER = prefix_role('user')
ROLE_SERVICE = prefix_role('service')
ROLE_ADMIN = prefix_role('admin')

request.user.is_staff will be modified based upon roles in KEYCLOAK_ROLES_TO_DJANGO_IS_STAFF. These roles can be hard coded as a list, tuple or set, or from a comma-separated env var. Functionality ignored if KEYCLOAK_ROLES_TO_DJANGO_IS_STAFF is None or empty.

If your user model doesn't / can't have a UUID primary key, override the KEYCLOAK_DJANGO_USER_UUID_FIELD setting to indicate a unique UUIDField on your model, e.g.:

KEYCLOAK_DJANGO_USER_UUID_FIELD = 'uuid'

Voila!

Multi tenancy/site support

An application can be configured for multiple sites by using different Keycloak Realms on the same or seperate Keycloak instances by using the environment var KEYCLOAK_MULTI_OIDC_JSON

The client OIDC adaptor json file can be downloaded from Keycloak.

KEYCLOAK_MULTI_OIDC_JSON:

{
    "auth.example.org": {
        "realm": "example",
        "auth-server-url": "https://auth.example.org/auth/",
        "ssl-required": "external",
        "resource": "my-client",
        "verify-token-audience": true,
        "credentials": {
          "secret": "my-secret"
        }
    }
}

KeycloakMultiAuthentication should be configured as the authentication class.

REST_FRAMEWORK = {
  ...
  'DEFAULT_AUTHENTICATION_CLASSES': [
    ...
    'drf_keycloak_auth.authentication.KeycloakMultiAuthentication',
  ]
}

---

NOTE: This will ignore DEFAULTS parameters for hostname, realm and client credentials.
All other parameters are still shared accross sites.

---

Session auth

This library includes KeycloakSessionAuthentication for using the Standard flow Keycloak login to interact directly with a browsable API.

Requires 'Standard flow' to be enabled in the Keycloak client and a valid redirect URL to be configured.

Configuration

settings.py:

  'DEFAULT_AUTHENTICATION_CLASSES': [
    'drf_keycloak_auth.authentication.KeycloakSessionAuthentication',
  ]

urls.py:

    urlpatterns = [
        path('api-auth/', include('drf_keycloak_auth.urls', namespace='rest_framework'))
    ]

Contributing

• Please raise an issue/feature and name your branch 'feature-n' or 'issue-n', where 'n' is the issue number.