Server Authentication Design

The Iodide authentication system is designed to support two use cases: an internal system for use by organizations (e.g. Mozilla) and a public web site. In either case, it is chiefly designed to delegate authentication and identity access for users to trusted third parties -- Iodide does not hold or manage any credentials itself.

In the case of a public facing system, no permissions or authentication are required to view any resource provided the API. This currently includes lists of notebooks, notebooks themselves (and their revisions), and files. Write access is currently limited to the user which created the resource.

On an internal system, read access is also limited to those users with an authenticated session and/or authentication token.

There are three ways a user may identify themselves to the Iodide system:

  • Session-based authentication
  • JWT-token based authentication
  • AuthToken-based authentication

Session-based authentication

This is based on Django's authentication system. Currently there are two options for this system of authentication: Github authentication (via the django social authentication system) and OpenIDC (via an internal set of openidc middleware).

GitHub authentication

GitHub authentication is fairly straightforward, simply using the existing facilities provided by python social auth. Configuration on the server may be accomplished simply by specifying environment variables corresponding to a GitHub key and secret.


If using OpenIDC, it is assumed that a web server fronting the Django system will authenticate any request coming in and provide an HTTP header to identify the user (HTTP_X_FORWARDED_USER).

By default, Mozilla's OpenIDC service will expire a user's session after a short period of inactivity. To allow an Iodide notebook to continue to access the API (e.g. to allow the user to continue saving their changes), as well as allowing headless services to access the iodide server, if OpenIDC is configured you may specify a set of regular expressions (via the OPENIDC_AUTH_WHITELIST configuration variable) where this checking is skipped, and we fall back to the jwt and/or authtoken middleware (which has its own expiry and renewal policy). By default just /api/ is included.

It is critical that you do not leave any endpoints open without authentication and specification in the OPENIDC_AUTH_WHITELIST, as this will allow any client to arbitrarily create any number of users on the system.

JWT-token based authentication

JWT-based authentication is based on the Django Rest Framework simple jwt plugin. The basic model is to allow a client to get a JWT token via session authentication (via the /token/ endpoint) and thereafter use JWT to identify to any endpoint server under /api/.

AuthToken-based authentication

This is yet another alternative, currently designed to support the use case of a 3rd party service being able to create iodide notebooks. This allows authentication using a unique key (secret) generated by an administrator on the Iodide server. Internally, this is implemented through Django Rest Framework's TokenAuthentication class. Usage is documented in the common server tasks section.