xivo-auth Developer’s Guide

Architecture

xivo-auth contains 4 major components, an HTTP interface, a celery worker, authentication backends and a consul client. All operations are made through the HTTP interface, tokens are stored by consul as well as the persistence for some of the data attached to tokens. 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 the xivo-user-uuid.

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 authentication
  • 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 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.

Internal services

To simplify authentication of internal services without renewing the Token we have added a command line tool xivo-auth-static-token-manager to manage static tokens. Currently you can get a static token, which is created automatically during the installation. The same tool can be used to create a new one if needed. The static token is created with default acl: confd.users.read.