guichet/README.md

# Guichet

[![status-badge](https://woodpecker.deuxfleurs.fr/api/badges/37/status.svg)](https://woodpecker.deuxfleurs.fr/repos/37)

Guichet is a simple LDAP web interface for the following tasks:

- self-service password change
- administration of the LDAP directory
- inviting new users to create accounts

Guichet works well with the [Bottin](https://git.deuxfleurs.fr/deuxfleurs/bottin) LDAP server.
Currently, Guichet's templates are only in French as it has been created for
the [Deuxfleurs](https://deuxfleurs.fr) collective.
We would gladly merge a pull request with an English translation !

A Docker image is provided on the [Docker hub](https://hub.docker.com/r/lxpz/guichet_amd64).
An example for running Guichet on a Nomad cluster can be found in `guichet.hcl.example`.

Guichet takes a single command line argument, `-config <filename>`, which is the
path to its config file (defaults to `./config.json`).
The configuration file is a JSON file whose contents is described in the following section.

Guichet is licensed under the terms of the GPLv3.


## Building Guichet

Guichet requires go 1.13 or later.

Development build:

```
go build
```

Production build:

```
nix build
```

Production container:

```
docker run .#docker
```

## Configuration of Guichet

Guichet is configured using a simple JSON config file which is a dictionnary whose keys
are described below. An example is provided in a further section.

### HTTP listen address

- `http_bind_addr`: which IP and port to bind on for the HTTP web interface. Guichet does not support HTTPS, use a reverse proxy for that.

### LDAP server configuration

- `ldap_server_addr`: the address of the LDAP server to use
- `ldap_tls` (boolean): whether to attempt STARTTLS on the LDAP connection
- `base_dn`: the base LDAP object under which we are allowed to view and modify objects

### User and group configuration

- `user_base_dn`: the base LDAP object that contains user accounts
- `user_name_attr`: the search attribute for user identifiers (usually `uid` or `cn`)
- `group_base_dn` and `group_name_attr`: same for groups

### Administration configuration

- `admin_account`: DN of an LDAP account that has administrative privilege. If such an account is set, the admin can log in by entering the full DN in the login form.
- `group_can_admin`: DN of a LDAP group whose members are given administrative privilege

### Invitation configuration

Guichet supports a mechanism where users can send invitations by email to other users.
The ability to send such invitations can be configured to be restricted to a certain group of users.
Invitation codes are created as temporary LDAP objects in a special folder.

- `group_can_invite`: the LDAP DN of a group whose members are allowed to send invitations to new users
- `invitation_base_dn`: the LDAP folder in which invitation codes are stored
- `invitation_name_attr`: just use `cn`
- `invited_mail_format`: automatically set the invited user's email to this string, where `{}` is replaced by the created username (ex: `{}@deuxfleurs.fr`)
- `invited_auto_groups` (list of strings): a list of DNs of LDAP groups

#### Email configuration

Guichet can send an invitation link by email. To do so, an SMTP server must be configured:

- `smtp_server`: the host and port of the mail server
- `smtp_username` and `smtp_password`: the username and password to log in with on the mail server
- `mail_from`: the sender email address for the invitation message
- `web_address`: the base web address of the Guichet service (used for building the invitation link)

## Example configuration

This is a subset of the configuration we use on Deuxfleurs:

```
{
  "http_bind_addr": ":9991",
  "ldap_server_addr": "ldap://bottin2.service.2.cluster.deuxfleurs.fr:389",

  "base_dn": "dc=deuxfleurs,dc=fr",
  "user_base_dn": "ou=users,dc=deuxfleurs,dc=fr",
  "user_name_attr": "cn",
  "group_base_dn": "ou=groups,dc=deuxfleurs,dc=fr",
  "group_name_attr": "cn",

  "admin_account": "cn=admin,dc=deuxfleurs,dc=fr",
  "group_can_admin": "cn=admin,ou=groups,dc=deuxfleurs,dc=fr",
  "group_can_invite": "cn=asso_deuxfleurs,ou=groups,dc=deuxfleurs,dc=fr"
}
```

Here is an example of Bottin ACLs that may be used to support Guichet invitations:

```
  "acl": [
		"*,dc=deuxfleurs,dc=fr::read:*:* !userpassword",
		"*::read modify:SELF:*",
		"ANONYMOUS::bind:*,ou=users,dc=deuxfleurs,dc=fr:",
		"ANONYMOUS::bind:cn=admin,dc=deuxfleurs,dc=fr:",
		"*,ou=services,ou=users,dc=deuxfleurs,dc=fr::bind:*,ou=users,dc=deuxfleurs,dc=fr:*",
		"*,ou=services,ou=users,dc=deuxfleurs,dc=fr::read:*:*",

		"*:cn=asso_deuxfleurs,ou=groups,dc=deuxfleurs,dc=fr:add:*,ou=invitations,dc=deuxfleurs,dc=fr:*",
		"ANONYMOUS::bind:*,ou=invitations,dc=deuxfleurs,dc=fr:",
		"*,ou=invitations,dc=deuxfleurs,dc=fr::delete:SELF:*",

		"*:cn=asso_deuxfleurs,ou=groups,dc=deuxfleurs,dc=fr:add:*,ou=users,dc=deuxfleurs,dc=fr:*",
		"*,ou=invitations,dc=deuxfleurs,dc=fr::add:*,ou=users,dc=deuxfleurs,dc=fr:*",

		"*:cn=asso_deuxfleurs,ou=groups,dc=deuxfleurs,dc=fr:modifyAdd:cn=email,ou=groups,dc=deuxfleurs,dc=fr:*",
		"*,ou=invitations,dc=deuxfleurs,dc=fr::modifyAdd:cn=email,ou=groups,dc=deuxfleurs,dc=fr:*",
		"*:cn=asso_deuxfleurs,ou=groups,dc=deuxfleurs,dc=fr:modifyAdd:cn=seafile,ou=groups,dc=deuxfleurs,dc=fr:*",
		"*,ou=invitations,dc=deuxfleurs,dc=fr::modifyAdd:cn=seafile,ou=groups,dc=deuxfleurs,dc=fr:*",

		"cn=admin,dc=deuxfleurs,dc=fr::read add modify delete:*:*",
		"*:cn=admin,ou=groups,dc=deuxfleurs,dc=fr:read add modify delete:*:*"
  ]
```

Consult [this directory](https://git.deuxfleurs.fr/Deuxfleurs/infrastructure/src/branch/main/app/directory/config)
to view the full configuration in use on Deuxfleurs.

## Contribute & local development

Guichet needs a few components to work :
- A Bottin server
- that needs a consul server
- And a Garage cluster (of at least one node)
A basic consul / bottin stack is available through the docker compose file you can find in `integration` subdirectory:

```sh
cd integration
docker compose up -d
```

You can then run Guichet locally :
```sh
# First, copy a sample config file
copy config.json.example config.json

# Run the go development server
go run .
```

It will be available on http://localhost:9991.

### First run

#### How to get my admin password

On first Bottin's run, it is displayed in the logs.  
You can easily find it by reading the container logs :
```sh
docker compose logs bottin | grep password:
```

- The **username** is provided in the log, and should look like this: `cn=admin,dc=bottin,dc=eu`.
- The **password** is right after in the same log line. 


#### Garage
⚠️ Be aware at this stage that your local Guichet installation is not 100% working, especially the websites features.   
You need to initialise Garage. It can be done in a few commands, coming from [the official Garage's documentation](https://garagehq.deuxfleurs.fr/documentation/quick-start/):

```sh
# Find your Garage node ID
docker compose exec garage /garage

# Your id is eb820c8da5605f78 in the output below
ID                Hostname      Address         Tags  Zone  Capacity          DataAvail
eb820c8da5605f78  9bd710b31be0  127.0.0.1:3901              NO ROLE ASSIGNED

# Then create a cluster layout with this id
docker compose exec garage /garage layout assign -z dc1 -c 1G eb820c8da5605f78

# Finally, apply the layout
docker compose exec garage /garage layout apply
```

🎉 You now can go to http://localhost:9991/website without getting 503 errors.