164 lines
5.5 KiB
Plaintext
164 lines
5.5 KiB
Plaintext
Kerberos authentication for Django
|
|
==================================
|
|
|
|
Provide Kerberos authentication to Django applications.
|
|
|
|
Python 2 and 3, Django >1.8 are supported.
|
|
|
|
Basic usage
|
|
===========
|
|
|
|
Add this to your project `urls.py`::
|
|
|
|
url('^accounts/kerberos/', include('django_kerberos.urls')),
|
|
|
|
And use the default authentication backend, by adding that to your `settings.py` file::
|
|
|
|
AUTHENTICATION_BACKENDS = (
|
|
'django_kerberos.backends.KerberosBackend',
|
|
)
|
|
|
|
Settings
|
|
========
|
|
|
|
`KERBEROS_HOSTNAME`
|
|
-------------------
|
|
|
|
Hostname for retrieving the service key, the correspondig principal will be
|
|
`HTTP/{KERBEROS_HOSTNAME}@DEFAULT_REAML`, default is `None`. If `None` the hostname
|
|
from the request will be used.
|
|
|
|
`KERBEROS_BACKEND_CREATE`
|
|
-------------------------
|
|
|
|
Whether to create user if no existing model can be found, default is `False`.
|
|
|
|
`KERBEROS_BACKEND_ADMIN_REGEXP`
|
|
-------------------------------
|
|
|
|
A regular expression that the principal must match to get superuser privileges,
|
|
default is `None`. A classic example could be `r'^.*/admin$'`.
|
|
|
|
`KERBEROS_SERVICE_PRINCIPAL`
|
|
-----------------------------------
|
|
|
|
The service principal to use when checking a password against the
|
|
KDC, you don't need the secret key for this principal, it should
|
|
just exist inside the Kerberos database as the check is done by
|
|
trying to get ticket for this service. Default is
|
|
None. It's used only by the pseudo password haser
|
|
and the login/password authentication backend.
|
|
|
|
`KERBEROS_KEEP_PASSWORD`
|
|
------------------------
|
|
|
|
Does the KerbersoPasswordBackend store a hash of the
|
|
checked password inside the user model each time a
|
|
user log in. Default is False. It allows your
|
|
website to provide a backup authentication if
|
|
Kerberos is failing or if you ever need to detach
|
|
from the realm.
|
|
|
|
Custom backend
|
|
==============
|
|
|
|
A custom authentication backend can be used, in this case the signature of the
|
|
authenticate method must be::
|
|
|
|
class CustomKerberosBackend(object):
|
|
def authenticate(self, principal=None):
|
|
pass
|
|
|
|
Sample application
|
|
==================
|
|
|
|
First you need to install django-kerberos into your environment like that::
|
|
|
|
python setup.py install
|
|
|
|
If you want to try the sample application you must add this line to your `/etc/hosts` file, absolutely at the beginning::
|
|
|
|
127.0.0.1 test.example.com
|
|
|
|
Then you must connect to your Kerberos administration server and add the
|
|
principal HTTP/test.example.com and export its key in a keytab file::
|
|
|
|
$ kadmin -p myuser/admin
|
|
kadmin: addprinc -randkey HTTP/test.example.com
|
|
kadmin: ktadd -k /tmp/keytab HTTP/test.example.com
|
|
|
|
Finally you can run the sample::
|
|
|
|
cd sample; KRB5_KTNAME=FILE:/tmp/keytab python ./manage.py runserver
|
|
|
|
Now you should be able to login on http://test.example.com:8000/
|
|
|
|
The sample project is configured so that all principal ending with `/admin` get
|
|
the staff and superuser flags. You can change that by editing the key
|
|
`KERBEROS_BACKEND_ADMIN_REGEXP` in `sample/sample/settings.py`.
|
|
|
|
.. caution::
|
|
Only use A pointers for your domain name or if your domain name is a CNAME alias then create the HTTP principal for the target domain.
|
|
|
|
Web browsers implementing the SPNEGO HTTP authenticiation protocol
|
|
canonicalize domain names by always resolving to a DNS A record before
|
|
building the corresponding principal. So if you have the following zone::
|
|
|
|
test.example.com CNAME a.example.com
|
|
a.example.com A a.b.c.d
|
|
|
|
and if you connect to https://test.example.com then the browser is gonna try
|
|
to get a ticket for the HTTP/a.examepl.com service principal not for
|
|
HTTP/test.example.com.
|
|
|
|
Pseudo hasher
|
|
=============
|
|
|
|
A pseudo hasher whose import path is `django_kerberos.hashers.KerberosHasher`
|
|
provide a mean to associate a Django user model to a Kerberos identity.
|
|
|
|
The content of the password field must be `kerberos$<principal name>`.
|
|
|
|
To create an user for a principal you can do::
|
|
|
|
User.objects.create(username=new_username, password='kerberos$' + principal)
|
|
|
|
Login/Password backend
|
|
======================
|
|
|
|
If your users does not have their browser configured
|
|
for SPNEGO HTTP authentication you can also provide
|
|
a classic login/password form which check passwords
|
|
using Kerberos.
|
|
|
|
Autologin
|
|
=========
|
|
|
|
A template include is provided to implement autologin. It calls the Kerberos
|
|
login view using AJAX. AJAX support in the login view makes the view return a
|
|
JSON document containing a boolean value indicating if login was sucessfull.
|
|
If login is succesfull the current view is reloaded.
|
|
|
|
To use this template just add the following code to any of your templates::
|
|
|
|
{% include "django_kerberos/autologin.html" %}
|
|
|
|
After a succesfull login a cookie is created which prevent autologin for the
|
|
next 15 minutes, to permit login using other methods after an immediate logout.
|
|
|
|
The template show an HTML div having the id "kerberos-autologin" and containing
|
|
the text "Autologin..." so that you can add CSS styling to it.
|
|
|
|
The javascript implementation of autologin is a script named
|
|
"js/autlogin.html", it can be reused to implement autologin for other
|
|
proctocols. Its only requirement is to have a view which return 'true' if a
|
|
login is successfull on an HTTP GET request. The script provide a javascript
|
|
function whose signature is::
|
|
|
|
autologin(url, callback[. timeout])
|
|
|
|
url is the URL of the login view, callback is a javascript function which will
|
|
receive true or false depending on the login success and timeout is the number
|
|
of seconds after a succesfull login during which autologin is disabled, default
|
|
is 15 minutes.
|