Getting started — django-mama-cas 0.2 documentation

### Navigation

- index
- modules |
- next |
- previous |
- django-mama-cas 0.2 documentation »

# Getting started

## Prerequisites

The primary prerequesite of django-mama-cas is Django itself. For django-mama-cas 0.2, Django 1.4 or later is required. Earlier versions of Django may work, but are not tested or supported. See the Django downloads page for information on downloading and installing Django.

The Python requests library is also required, but should be automatically installed during the installation process described below.

You will also need at least one authentication backend installed and configured, depending on your authoritative authentication source.

## Installing django-mama-cas

### Via pip

The easiest way to install django-mama-cas is using pip. Simply type:

    pip install django-mama-cas

It is recommended to run this command within a virtualenv so django-mama-cas is installed in an isolated environment instead of system wide.

### Via a downloaded package

You can also manually download django-mama-cas from GitHub. Extract the downloaded archive and install it with:

    python setup.py install

Alternately, you can manually put django-mama-cas anywhere, provided it is on the Python path. If you take the route, you will also need to manually install the requests library dependency.

## Configuration

Once installed, add django-mama-cas to your project by modifying the `INSTALLED_APPS` setting within your project’s `settings.py` to include this line:

    'mama_cas',

Once django-mama-cas is added to the project, run `python manage.py syncdb` to create the required database tables.

### Settings

django-mama-cas can be modified using several custom settings. None are required, but can be used to override the defaults.

MAMA_CAS_TICKET_EXPIRE (default: 5)
  Controls the length of time, in minutes, between when a service or proxy ticket is generated and when it expires. If the ticket is not validated before this time is up, it will become invalid. This does NOT affect the duration of a user’s single sign-on session.
MAMA_CAS_TICKET_RAND_LEN (default: 32)
  Sets the number of random characters created as part of the ticket string. It should be long enough that the ticket cannot be brute forced within a reasonable amount of time. Longer values are more secure, but could cause compatibility problems with some clients.
MAMA_CAS_USER_ATTRIBUTES (default: {})

  A dictionary of name and `User` attribute values to be returned along with a service or proxy validation success. The name can be any meaningful string, while the attribute must correspond with an attribute on the `User` object. For example:

      MAMA_CAS_USER_ATTRIBUTES = {
          'givenName': 'first_name',
          'sn': 'last_name',
          'email': 'email',
      }

MAMA_CAS_PROFILE_ATTRIBUTES (default: {})

  A dictionary of name and user profile attribute values to be returned along with a service or proxy validation success. The name can be any meaningful string, while the attribute must correspond with an attribute on the user profile object. If no user profile is configured or available, this setting will be ignored. For example:

      MAMA_CAS_PROFILE_ATTRIBUTES = {
          'employeeID': 'id_number',
      }

### Sessions

django-mama-cas relies on standard Django sessions to control session storage and expiration. To understand how sessions work within Django, read the session documentation. There are three particular settings that control where sessions are stored and when they expire:

> - SESSION_ENGINE
> - SESSION_COOKIE_AGE
> - SESSION_EXPIRE_AT_BROWSER_CLOSE

It is recommended that `SESSION_COOKIE_AGE` be set shorter than the default of two weeks. `SESSION_EXPIRE_AT_BROWSER_CLOSE` should be set to `True` to conform to the CAS specification. Both of these settings can be configured to meet your particular environment and security needs.

### URL paths

django-mama-cas includes a Django `URLconf` that provides the required CAS URIs (e.g. login, logout, validate, etc.). They are located in `mama_cas.urls` and can be included directly in your project’s root `URLconf`. For example:

    (r'', include('mama_cas.urls')),

This would make the CAS server available at the top level of your project’s URLs. If this is not the desired path, add a base to the included URLs. For example, if you wished the CAS server to be available under the `/cas/` root, use:

    (r'^cas/', include('mama_cas.urls')),

All CAS enabled services need to be configured according to the URL settings here. Changing the CAS URLs within `mama_cas.urls` is not recommended as that will likely break standard CAS behavior.

### Templates

django-mama-cas comes with a basic login template implementing standard username and password authentication. It will work as provided, but can also be extended or replaced according to your needs.

If you are returning custom user attributes, you may also need to change the validation XML template to return the attributes in the correct format.

Read the template documentation for more information on the included templates and customization.

## Authentication

django-mama-cas does not perform any authentication itself. It relies on the configured Django authentication backends for that task. The process of configuring authentication backends will change depending on the backend in use.

See also

- Django user authentication: the official documentation for the user authentication system in Django.
- django-ldap: an authentication backend that authenticates against an LDAP service.

### Navigation

- index
- modules |
- next |
- previous |
- django-mama-cas 0.2 documentation »