bam/README.md

# bam - Blinkenbunt Account Manager

## Installation

Currently, this repository does only contain a plain _Django_ app without a
project. The app is not (yet) packaged. Therfore, the following steps are
necessary to initialize a development environment:

  1. Initialize _Django_ project:

     ```
django-admin startproject PROJECT_NAME
```

  2. Clone this repository to a location outside the project directory.

  3. Below the project directory, create a symlink called `bam` to the `bam`
     folder of this repository, e.g.:

     ```
ln -sr bam PROJECT_DIRECTORY/bam
```

  4. Add `bam.apps.BamConfig` to `INSTALLED_APPS` in the project's
     `settings.py`.

  5. Set `bam.hashers.LDAPPBKDF2PasswordHasher` as the first item of the
     `PASSWORD_HASHERS` array in the project's `settings.py`.

  6. Insert the configuration values described below according to your setup
     into the project's `settings.py`.

  7. Append `path('', include('bam.urls')),` to the project's `urls.py`.

  8. Initialize database:

     ```
./manage.py migrate
```

  9. Create a superuser account:

     ```
./manage.py createsuperuser
```

  10. Download _Pure.css_ and extract it to `bam/static/pure.css/`.

  11. Start the development server:

     ```
./manage.py runserver
```

## Configuration Options

  * `BAM_LDAP_URI`: URI of the LDAP server to connect to. For a server on the
    same system, `ldapi:///` usually can be used.

  * `BAM_LDAP_BIND_DN`: The DN to bind to. It requires permissions to create
    and change entries in the relevant base DNs.

  * `BAM_LDAP_SECRET`: The secret corresponding to the bind DN.

  * `BAM_LDAP_BASE_DN_MAP`: A dict from base DNs to arrays of Django groups.

    User entries are maintained in the given base DN for all active members of
    at least one of the assigned groups. They get deleted if the corresponding
    user is deactivated or no longer in any of these groups.

    Example:

    ```
    BAM_LDAP_BASE_DN_MAP = {
        'ou=test,dc=blinkenbunt,dc=org': [
            'jabber',
            'git',
        ],
        'ou=admins,dc=blinkenbunt,dc=org': [
            'admin',
        ],
    }
```

  * `BAM_LDAP_SYNCHRONOUS_SYNC_ENABLED`: If `True`, changes are immediately
    propagated to LDAP when they are made through the web frontend. If `False`,
    the `sync_users` management command has to be used to perform this task for
    all users. (Optional, default: `True`)

## ToDo

### Planned

  * service-based logins
  * self-service registration
  * form to edit own profile
  * package this app as a _Python_ module