bam/README.md

# bam - Blinkenbunt Account Manager

## Installation

Currently, this repository does only contain a plain _Django_ app without a
project. The following steps are necessary to initialize a development
environment:

  1. Initialize a _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_NAME/bam
```
     Alternatively, if you're using a virtual environment, you can install _bam_
     by calling `pip install -e .` from within this repo's base directory.

  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. Set `LOGIN_URL` to `/login/` and `LOGIN_REDIRECT_URL` to `/` in the
     project's `settings.py`.

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

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

  9. Initialize database:

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

  10. Create a superuser account:

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

  11. Download _Pure.css_  to `bam/static/pure-min.css`.

  12. 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