search

nitmir / django-cas-server

A Django Central Authentication Service server implementing the CAS Protocol 3.0 Specification
GNU General Public License v3.0
132 stars 44 forks source link

readme

CAS Server ##########

|travis| |coverage| |licence| |github_version| |pypi_version| |codacy| |doc|

CAS Server is a Django application implementing the CAS Protocol 3.0 Specification <https://apereo.github.io/cas/4.2.x/protocol/CAS-Protocol-Specification.html>_.

By default, the authentication process uses django internal users but you can easily use any source (see the Authentication backend_ section and auth classes in the auth.py file)

.. contents:: Table of Contents

Features

Dependencies

django-cas-server depends on the following python packages:

Minimal version of package dependencies are just indicative and means that django-cas-server has been tested with it. Previous versions of dependencies may or may not work.

Additionally, depending on the Authentication backend_ you plan to use, you may need the following python packages:

Here is a table with the name of python packages and the corresponding packages providing them on debian like systems and centos like systems. You should try as much as possible to use system packages as they are automatically updated when you update your system. You can then install Not Available (N/A) packages on your system using pip3 inside a virtualenv as described in the Installation_ section. For use with python2, just replace python3(6) in the table by python.

+------------------+--------------------------+---------------------+ | python package | debian like systems | centos like systems | +==================+==========================+=====================+ | Django | python3-django | python36-django | +------------------+--------------------------+---------------------+ | requests | python3-requests | python36-requests | +------------------+--------------------------+---------------------+ | requests_futures | python3-requests-futures | N/A | +------------------+--------------------------+---------------------+ | lxml | python3-lxml | python36-lxml | +------------------+--------------------------+---------------------+ | six | python3-six | python36-six | +------------------+--------------------------+---------------------+ | ldap3 | python3-ldap3 | python36-ldap3 | +------------------+--------------------------+---------------------+ | psycopg2 | python3-psycopg2 | python36-psycopg2 | +------------------+--------------------------+---------------------+ | mysql-python | python3-mysqldb | python36-mysql | +------------------+--------------------------+---------------------+

Installation

The recommended installation mode is to use a virtualenv with --system-site-packages

  1. Make sure that python virtualenv is installed

  2. Install python packages available via the system package manager:

    On debian like systems::

    $ sudo apt-get install python3-django python3-requests python3-six python3-lxml python3-requests-futures

    On debian jessie, you can use the version of python-django available in the backports <https://backports.debian.org/Instructions/>_.

    On centos like systems with epel enabled::

    $ sudo yum install python36-django python36-requests python36-six python36-lxml

  3. Create a virtualenv::

    $ virtualenv -p python3 --system-site-packages cas_venv

  4. And activate it <https://virtualenv.pypa.io/en/stable/userguide/#activate-script>__::

    $ cd cas_venv/; . bin/activate

  5. Create a django project::

    $ django-admin startproject cas_project $ cd cas_project

  6. Install django-cas-server. To use the last published release, run::

    $ pip install django-cas-server

    Alternatively if you want to use the version of the git repository, you can clone it::

    $ git clone https://github.com/nitmir/django-cas-server $ cd django-cas-server $ pip install -r requirements.txt

    Then, either run make install to create a python package using the sources of the repository and install it with pip, or place the cas_server directory into your PYTHONPATH <https://docs.python.org/2/using/cmdline.html#envvar-PYTHONPATH>_ (for instance by symlinking cas_server to the root of your django project).

  7. Open cas_project/settings.py in your favourite editor and follow the quick start section.

Quick start

  1. Add "cas_server" to your INSTALLED_APPS setting like this::

    INSTALLED_APPS = ( 'django.contrib.admin', ... 'cas_server', )

    For internationalization support, add "django.middleware.locale.LocaleMiddleware" to your MIDDLEWARE setting like this::

    MIDDLEWARE = [ ... 'django.middleware.locale.LocaleMiddleware', ... ]

  2. Include the cas_server URLconf in your project urls.py like this::

    from django.urls import path, include

    urlpatterns = [ path('admin/', admin.site.urls), ... path('cas/', include('cas_server.urls', namespace="cas_server")), ]

  3. Run python manage.py migrate to create the cas_server models.

  4. You should add some management commands to a crontab: clearsessions, cas_clean_tickets and cas_clean_sessions.

    • clearsessions: please see Clearing the session store <https://docs.djangoproject.com/en/stable/topics/http/sessions/#clearing-the-session-store>_.
    • cas_clean_tickets: old tickets and timed-out tickets do not get purged from the database automatically. They are just marked as invalid. cas_clean_tickets is a clean-up management command for this purpose. It sends SingleLogOut requests to services with timed out tickets and deletes them.
    • cas_clean_sessions: Logout and purge users (sending SLO requests) that are inactive more than SESSION_COOKIE_AGE. The default value is 1209600 seconds (2 weeks). You probably should reduce it to something like 86400 seconds (1 day).

    You could, for example, do as below::

    0 0 cas-user /path/to/project/manage.py clearsessions /5 cas-user /path/to/project/manage.py cas_clean_tickets 5 0 * cas-user /path/to/project/manage.py cas_clean_sessions

  5. Run python manage.py createsuperuser to create an administrator user.

  6. Start the development server and visit http://127.0.0.1:8000/admin/ to add a first service allowed to authenticate user against the CAS (you'll need the Admin app enabled). See the Service Patterns_ section below.

  7. Visit http://127.0.0.1:8000/cas/ to login with your django users.

Settings

All settings are optional. Add them to settings.py to customize django-cas-server:

Template settings

Note that the old bootstrap3 template is available in cas_server/bs3/

Authentication settings

Federation settings

New version warnings settings

Tickets validity settings

Tickets miscellaneous settings

Forms settings

Mysql backend settings

Deprecated, see the Sql backend settings_. Only useful if you are using the mysql authentication backend:

Sql backend settings

Only useful if you are using the sql authentication backend. You must add a "cas_server" database to settings.DATABASES <https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-DATABASES>__ as defined in the django documentation. It is then the database used by the sql backend.

Ldap backend settings

Only useful if you are using the ldap authentication backend:

Test backend settings

Only useful if you are using the test authentication backend:

Authentication backend

django-cas-server comes with some authentication backends:

Logs

django-cas-server logs most of its actions. To enable login, you must set the LOGGING (https://docs.djangoproject.com/en/stable/topics/logging) variable in settings.py.

Users successful actions (login, logout) are logged with the level INFO, failures are logged with the level WARNING and user attributes transmitted to a service are logged with the level DEBUG.

For example to log to syslog you can use :

.. code-block:: python

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'cas_syslog': {
            'format': 'cas: %(levelname)s %(message)s'
        },
    },
    'handlers': {
        'cas_syslog': {
            'level': 'INFO',
            'class': 'logging.handlers.SysLogHandler',
            'address': '/dev/log',
            'formatter': 'cas_syslog',
        },
    },
    'loggers': {
        'cas_server': {
            'handlers': ['cas_syslog'],
            'level': 'INFO',
            'propagate': True,
        },
    },
}

Or to log to a file:

.. code-block:: python

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'cas_file': {
            'format': '%(asctime)s %(levelname)s %(message)s'
        },
    },
    'handlers': {
        'cas_file': {
            'level': 'INFO',
            'class': 'logging.FileHandler',
            'filename': '/tmp/cas_server.log',
            'formatter': 'cas_file',
        },
    },
    'loggers': {
        'cas_server': {
            'handlers': ['cas_file'],
            'level': 'INFO',
            'propagate': True,
        },
    },
}

Service Patterns

In a CAS context, Service refers to the application the client is trying to access. By extension we use service for the URL of such an application.

By default, django-cas-server does not allow any service to use the CAS to authenticate users. In order to allow services, you need to connect to the django admin interface using a django superuser, and add a first service pattern.

A service pattern comes with 9 fields:

A service pattern has 4 associated models:

When a user asks for a ticket for a service, the service URL is compared against each service pattern sorted by position. The first service pattern that matches the service URL is chosen. Hence, you should give low position to very specific patterns like ^https://www\.example\.com(/.*)?$ and higher position to generic patterns like ^https://.*. So the service URL https://www.examle.com will use the service pattern for ^https://www\.example\.com(/.*)?$ and not the one for ^https://.*.

Federation mode

django-cas-server comes with a federation mode. When CAS_FEDERATE is True, users are invited to choose an identity provider on the login page, then, they are redirected to the provider CAS to authenticate. This provider transmits to django-cas-server the user username and attributes. The user is now logged in on django-cas-server and can use services using django-cas-server as CAS.

In federation mode, the user attributes are cached upon user authentication. See the settings CAS_TGT_VALIDITY to force users to reauthenticate periodically and allow django-cas-server to refresh cached attributes.

The list of allowed identity providers is defined using the django admin application. With the development server started, visit http://127.0.0.1:8000/admin/ to add identity providers.

An identity provider comes with 5 fields:

In federation mode, django-cas-server build user's username as follow: provider_returned_username@provider_suffix. Choose the provider returned username for django-cas-server and the provider suffix in order to make sense, as this built username is likely to be displayed to end users in applications.

Then using federate mode, you should add one command to a daily crontab: cas_clean_federate. This command clean the local cache of federated user from old unused users.

You could for example do as below::

10 0 * cas-user /path/to/project/manage.py cas_clean_federate

.. |travis| image:: https://badges.genua.fr/travis/com/nitmir/django-cas-server/master.svg :target: https://travis-ci.com/nitmir/django-cas-server

.. |pypi_version| image:: https://badges.genua.fr/pypi/v/django-cas-server.svg :target: https://pypi.org/project/django-cas-server/

.. |github_version| image:: https://badges.genua.fr/github/tag/nitmir/django-cas-server.svg?label=github :target: https://github.com/nitmir/django-cas-server/releases/latest

.. |licence| image:: https://badges.genua.fr/pypi/l/django-cas-server.svg :target: https://www.gnu.org/licenses/gpl-3.0.html

.. |codacy| image:: https://badges.genua.fr/codacy/grade/255c21623d6946ef8802fa7995b61366/master.svg :target: https://www.codacy.com/app/valentin-samir/django-cas-server

.. |coverage| image:: https://intranet.genua.fr/coverage/badge/django-cas-server/master.svg :target: https://badges.genua.fr/coverage/django-cas-server/master

.. |doc| image:: https://badges.genua.fr/local/readthedocs/?version=latest :target: http://django-cas-server.readthedocs.io