User Management

Sphinxy allows to create and maintain user profiles, which can be used to login to the documentation site and to manage access to certain elements like pages and secured content parts.

Directives for securing information:

To see the Sphinxy secure mechanisms in action, please visit one of the following example pages:

• Authorization examples
  • Per page
  • Per area

Note

How secure is it?

Sphinxy can grant access to pages and specific areas of a page.

If a secured area contains an image, this image is not shown to the user, if the user does not have the needed permissions. However, this image may still be available in the _static/ folder or at some other places, which are not secured by Sphinxy and can be browsed by the user without any restrictions.

User handling

User objects are stored in a database and contain information like email, password and roles.

They can be configured in the conf.py file of the project or via an interface on the running documentation website.

Warning

The user configuration in the conf.py only creates new objects . If a user or role already exists in the database, it does not get updated. Use the web interface for updating existing users and roles.

via conf.py

Users can be created in the conf.py file like:

ubtrace_users = [
    {
        "email": "me@example.com",
        "username": "me",
        "password": "secret",
        "active": True,
        "roles": ["user", "admin"]
    },
    {
        "email": "max.who@customer.com",
        "username": "max_who",
        "password": "123-123",
        "active": True,
        "roles": ["user", "customer"]
    }
]

Supported user entries are:

• email

• username

• password

• active

• roles

Roles & Permissions

Roles and Permissions are used to grant access for an authenticated user to certain elements of the documentation.

A role can contain one or multiple permissions. Roles and permissions are just strings and a user can have multiple roles, which may have some permission in common.

via conf.py

Roles and permissions can be defined in the conf.py file:

ubtrace_roles = {
    "user": ['user-read', 'user-write'],
    "admin": ['admin', 'all-read', 'all-write'],
    "employee": ['all-read', 'internal'],
    "customer_a": ['customer_a-read', 'customer', 'external'],
    "customer_b": ['customer_b-read', 'customer', 'external'],
    "supplier": ['supplier', 'external'],
}

Roles are assigned to the user in the ubtrace_users config option.

Names and amount of permissions is totally free, there is no requirement to use a configured permission somewhere in the documentation.

Securing content

There are certain ways to secure the content and manage the access to it.

Short example:

:secure: user

Welcome
=======

The following content is only for internal employees.

.. secure:: internal

   All internal data can be found here: http://internal.example.com

For details see Content Protection .

Customizing Authentication

Sphinxy does not support the customization of Authentication or Authorization directly.

So following use cases are currently not supported:

• Add a new element to the user object, like address .

• Replace the Authentication mechanism with something different.

• Define own template files, without using Sphinxy API.

However, it is planned to give direct access to the Flask app in the future.