Metadata-Version: 2.4
Name: django-kaminarimon
Version: 0.1.0
Summary: Auth(n/z) plugin for Django using kerberos + LDAP
Keywords: django,kerberos,gssapi,spnego,ldap,auth,authentication,authorization,JWT,djangorestframework,DRF
Author: Adrian Torres
Author-email: Adrian Torres <atorresj@redhat.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Environment :: Plugins
Classifier: Framework :: Django
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: django>=4.2.0
Requires-Dist: djangorestframework>=3.15.0
Requires-Dist: djangorestframework-simplejwt>=5.3.1
Requires-Dist: drf-spectacular>=0.27.2
Requires-Dist: kerberos>=1.3.1
Requires-Dist: python-ldap>=3.4.0
Requires-Python: >=3.9
Project-URL: Homepage, https://github.com/RedHatProductSecurity/django-kaminarimon/
Project-URL: Repository, https://github.com/RedHatProductSecurity/django-kaminarimon/
Description-Content-Type: text/markdown

# django-kaminarimon
## What is it?

`django-kaminarimon` (or just kaminarimon) is a library for integrating
kerberos authentication and ldap authorization into a Django/DRF application.

While users can independently choose to integrate one or the other, it is
designed to use both and use JWTs as interface for client<->server auth.

## How to use

### For Kerberos authentication

Set `kaminarimon.auth.KerberosAuthentication` as either:
* `REST_FRAMEWORK["DEFAULT_AUTHENTICATION_CLASSES"]`
* Individually at the view level

This will require the client to send a request with the header
`Authorization: Negotiate <token>` which will initiate the SPNEGO protocol.

If the client does not send the aforementioned header when requesting a view
that requires Kerberos authentication, the `WWW-Authenticate` is sent back to
the client, signaling that it should use SPNEGO protocol for authentication.

> [!TIP]
> By default the host or service principal will use the service's FQDN, but it
> can be overridden by setting the `KRB5_HOSTNAME` environment variable.

### For LDAP authorization

> [!NOTE]
> A lot of the behavior of this authentication backend is currently hardcoded
> to only work with Red Hat systems.

> [!NOTE]
> Anonymous user access to the LDAP server is required for querying user
> information.

> [!WARNING]
> Usage of LDAP authorization on its own withour Kerberos authentication is
> discouraged as it **only** handles authorization, it does not actually
> perform any sort of authentication of the user against the LDAP server,
> i.e. it simply loads the user's groups from the LDAP server.

Simply add the `kaminarimon.backend.LDAPRemoteUser` to the
`AUTHENTICATION_BACKENDS` django setting.

Required settings:
* `AUTH_LDAP_SERVER_URI` -- URI to the LDAP server
* `PUBLIC_READ_GROUPS` -- List of names of groups that, if the user is a member of,
  grant access to the application.
  `SERVICE_MANAGE_GROUP` -- Group that denotes a user as staff and/or superuser.

### Intended usage (kerberos authentication, ldap authorization)

The same settings, warnings, notes and tips for the previous sections apply.

Ensure `kaminarimon.backend.LDAPRemoteUser` is in `AUTHENTICATION_BACKENDS`,
and add `kaminarimon.views.krb5_obtain_token_pair_view` to your `urls.py`,
it is through this view that clients will obtain access and refresh JWT.

In order to protect other views with such authentication tokens, simply mark the
authentication method as `rest_framework_simplejwt.authentication.JWTAuthentication`
or similar as, or set it globally using `DEFAULT_AUTHENTICATION_CLASSES`.

## Running tests

```bash
cd tests/
podman compose -f docker-compose.yml up -d
pytest .
```
