Quickstart as Django app

This guide provides instructions for running your own certificate authority as a Django app in your existing Django project. This setup allows you to integrate django-ca into an existing Django deployment.

In this guide we do not cover creating your own Django project, deployment strategies or regular Python or Django development.

Requirements

This guide assumes that you have moderate knowledge of running servers, installing software and how TLS certificates work.

The guide assumes you use a dedicated server to set up your certificate authority and does not account for potential conflicts with other software like ports, directories or container names.

A certificate authority needs plain HTTP for CRL and OCSP access and HTTPS for ACMEv2. Using standard ports are strongly recommended (clients might fail otherwise). If you do not need any of the mentioned features, you can use all other features from the command line and do not need a web server.

Setup DNS

Before you set up your certificate authority, you need a domain name that points to the server where you install django-ca. Since the domain is encoded in CA certificates, it cannot be easily changed later.

This guide assumes that ca.example.com is the name that points to the server where you are setting up your certificate authority.

Required software

You do not need any special software besides Python 3.7 or later and a recent version of pip.

It is strongly recommended that you run a Celery task queue. If you do, you need a message transport like RabbitMQ or Redis. Redis is used in the examples below, because it is easiest to set up and doubles as a cache.

Python libraries

If you’re using an older system, the table blow lists what versions of Python, Django and cryptography where tested with what release (changes to previous versions in bold):

django-ca

Python

Django

cryptography

idna

Celery

acme

1.21

3.7 - 3.10

3.2 - 4.0

35.0 - 36.0

n/a

5.0 - 5.2

1.23 - 1.25

1.20

3.7 - 3.10

2.2, 3.2 - 4.0

3.4 - 36.0

3.2, 3.3

5.0 - 5.2

1.22

1.19

3.6 - 3.10

2.2, 3.1, 3.2

3.3 - 35.0

2.10 - 3.2

5.0 - 5.1

1.20

1.18

3.6 - 3.9

2.2, 3.1, 3.2

3.0 - 3.4

2.10

5.0

1.17

3.6 - 3.9

2.2 - 3.1

2.8 - 3.3

2.9 - 2.10

4.3 - 4.4

1.16

3.5 - 3.8

2.2 - 3.1

2.7 - 3.0

2.8 - 2.10

4.2 - 4.4

Note that we don’t deliberately break support for older versions, we merely stop testing it. You can try your luck with older versions.

Starting with django-ca==1.21.0, we no longer test individual versions of idna.

Installation

For a minimal installation, you can install django-ca via pip:

user@host:~$ pip install django-ca

There are several extras available, acme and celery are strongly recommended:

Extra

Description

acme

Deprecated! Added ACMEv2 support, which is now always included.

redis

Adds Redis support (usable as both cache and Celery message transport).

celery

Adds Celery support.

mysql

Adds MySQL support.

postgres

Adds PostgreSQL support.

Deprecated since version 1.21.0: The acme extra is deprecated and will be removed in django-ca==1.23.0. The dependencies it installed are now mandatory.

To install django-ca with one or more extras, use the regular pip syntax:

user@host:~$ pip install django-ca[acme,celery,redis]

Initial configuration

Simply add django_ca to your INSTALLED_APPS (and if you don’t use it already, django_object_actions), as well as a few other required settings:

INSTALLED_APPS = [
   # ... your other apps...

   'django_object_actions',
   'django_ca',
]

# The hostname used by default for URLs in certificates. Your Django project should be available under this
# URL using HTTP (see below). If you use ACMEv2, you will also need HTTPS.
CA_DEFAULT_HOSTNAME = "ca.example.com"

# RECOMMENDED: Use Celery as an asynchronous task worker if configured
CELERY_BROKER_URL = "redis://127.0.0.1:6379/0"

# Enable ACMEv2 support (enabled by default starting 1.22.0). Set to False to completely disable ACMEv2
# support.
CA_ENABLE_ACME = True

Please check out Custom settings for settings specific to django-ca.

You also need to include the URLs in your main file:urls.py:

urlpatterns = [
   path("ca/", include("django_ca.urls")),
   ...
]

Finally, invoke the regular manage.py commands when you add new apps:

user@host:~$ python manage.py migrate
user@host:~$ python manage.py collectstatic

After that, django-ca should show up in your admin interface (see Web interface) and provide various manage.py commands (see Command-line interface).

Create admin user and set up CAs

All functionality is available as custom Djangos manage.py commands.

Custom management commands are documented in Command-line interface. You need to create a user (that can log into the admin interface) and create a root and intermediate CA:

root@host:~# python manage.py createsuperuser
...
root@host:~# python manage.py init_ca --pathlen=1 Root "/CN=Root"
root@host:~# python manage.py init_ca  --acme-enable --parent="Root" Intermediate \
>     "/CN=Intermediate"

There are a few things to break down in the above commands:

  • The subject (/CN=...) in the CA is only used by browsers to display the name of a CA. It can be any human readable value and does not have to be a domain name.

  • The first positional argument to init_ca, (“Root”, “Intermediate”) is just a human readable name used to identify the CA within the command-line interface and web interface. Unlike the CommonName, it must be unique.

  • The --pathlen=1 parameter for the root CA means that there is at most one level of intermediate CAs.

Use your CAs

After adding your Root CA to your system, you can use the admin interface at https://ca.example.com/admin/ with the credentials you created above to create new certificates or revoke certificates.

CRL and OCSP services are provided by default, so there is nothing you need to do to enable them.

You can use the Command-line interface for creating new CAs as well as issuing, renewing and revoking certificates.

Add CA to your system

To get the certificate for your Root CA, you can use the admin interface or the dump_ca command:

user@host:~$ manage.py dump_ca Root > root.pem

You can add this file directly to the list of known CAs in your browser.

Distributions usually provide instructions for how to add a CA to the whole system, see for example these instructions for Debian/Ubuntu.

Use ACME with certbot

If you enabled ACMEv2 support, all you need to do is enable ACMEv2 for the intermediate CA using the admin interface (or using manage.py edit_ca). After that, you can retrieve a certificate using a simple certbot command:

$ sudo certbot register --server https://ca.example.com/django_ca/acme/directory/
$ sudo certbot certonly --server https://ca.example.com/django_ca/acme/directory/ ...

Update

When updating, first check the ChangeLog for any breaking changes. Under Update you’ll also find notes on any manual steps you might need to take.

You can update django-ca like any other Django app:

user@host:~$ pip install -U django-ca
user@host:~$ python manage.py migrate
user@host:~$ python manage.py collectstatic