Setting Up External Authentication

Currently the edx-platform supports Shibboleth, CAS, and SSL certificates as external authentication sources, but the documentation for the setting them is quite light (i.e. read the code), here is how to use CAS and SSL certificates.

Central Authentication Service (CAS) integration

CAS is one of the simplest and easiest ways to enable external authentication on the platform. All that is required is one feature flag and one configuration item. The feature flag to enable in your EDXAPP_FEATURES yaml hash for ansible (or in any of the settings files) is AUTH_USE_CAS set to true. That flag turns on the django-cas (https://bitbucket.org/cpcc/django-cas/overview) middleware and installed_app. From there only one additional setting is required. and that is CAS_SERVER_URL which needs to be pointed at your CAS server (and is available as $EDXAPP_CAS_SERVER_URL in the edxapp ansible role variables. There is also an optional CAS_EXTRA_LOGIN_PARAMS that can be used to pass additional get attributes to your CAS server to identify where the login is coming from, setting a allowed key, or specifying which authentication provider to use as examples. That setting can be overridden with $EDXAPP_CAS_EXTRA_LOGIN_PARAMS. Additional documentation can be found at the django-cas project page.

We recently added the ability to specify a custom attribute handler so that the attributes returned by your CAS server can be parsed and mapped to the local user model inside the platform. To set that up you need to specify some options in the lms.env.json file and provide a python package and function to do the parsing. Here is an example of the CAS config for the ansible role:

EDXAPP_CAS_ATTRIBUTE_PACKAGE: "git+https://github.com/mitocw/mitx_cas_mapper"
EDXAPP_CAS_ATTRIBUTE_CALLBACK:
  module: "mitx_cas_mapper"
  function: "populate_user"

This will cause the edxapp role to install the specified package and properly populate the json configuration file. The example repo is a real working package that can be easily forked and modified to map your own CAS attributes.

SSL Client Certificates

This is another fairly simple mechanism (configuration wise) that enables using SSL certificates to authenticate and register users from an external source. This just requires adding the feature flag AUTH_USE_CERTIFICATES. Once enabled all that is required to do is have your front end Web server (most likely nginx here) setup to validate client certificates and set the SSL_CLIENT_S_DN header with the clients DN. This can be setup by adding the folling lines to your nginx server config:

ssl_client_certificate /path/to/my/client/cacert
ssl_verify_client on;

The verify client can also be optional if you want to allow ssl auth, but also support another authentication method (like CAS for example), and then adding the header to the proxy location section of your nginx config that looks like:

proxy_set_header SSL_CLIENT_S_DN $ssl_client_s_dn;

That should cause authentication to automatically occur in studio and lms whenever a protected page is accessed. An additional feature flag, AUTH_USE_CERTIFICATES_IMMEDIATE_SIGNUP if set to true will also enable automatic registration to occur for user's so they won't even have to fill out profile information.