XiVO auth developer’s guide

Architecture

xivo-auth contains 4 major components, an HTTP interface, a celery worker, authentification backends and a consul client. All operations are made through the HTTP interface, tokens are generated by consul as well as the persistence for some of the data attached to tokens. xivo-auth is only a thin layer of logic above consul. The celery worker is used to schedule tasks that outlive the lifetime of the xivo-auth process. Backends are used to test if a supplied username/password combination is valid and provide a unique identifier.

xivo-auth is made of the following modules and packages.

plugins

the plugin package contains the xivo-auth backends that are packaged with xivo-auth.

http

The http module is the implementation of the HTTP interface.

  • Validate parameters
  • Calls the backend the check the user authentification
  • Forward instructions to the token_manager
  • Handle exceptions and return the appropriate status_code

controller

The controller is the plumbin of xivo-auth, it has no business logic.

  • Start the HTTP application
  • Start the celery worker
  • Load all enabled plugins
  • Instanciate the token_manager

token

The token modules contains the business logic of xivo-auth.

  • Creates and delete tokens
  • Creates consul ACLs for the key/value store
  • Creates ACLs for XiVO
  • Schedule token expiration
  • Read/write token data to consul

tasks

The tasks module contains implementation of celery tasks that are executed by the worker.

  • Called by the celery worker
  • Forwards instructions to the token manager

extension

This is a place holder for a global variable for the celery app. It will be removed and should not be used.

Other modules that should not need documentation are helpers, config, interfaces

Plugins

xivo-auth is meant to be easy to extend. This section describes how to add features to xivo-auth.

Backends

xivo-auth allows its administrator to configure one or many sources of authentication. Implementing a new kind of authentication is quite simple.

  1. Create a python module implementing the backend interface.
  2. Install the python module with an entry point xivo_auth.backends

An example backend implementation is available here.