ldap-matter/Docker/README.md

Mattermost-LDAP - Docker module
===============================

## Summary

This repository provides necessary ressources to build the Docker image for Mattermost-LDAP module. This Docker image is usefull to try Mattermost-LDAP in a PoC or a demo, and is production ready.

## Description

The Mattermost-LDAP module can be use with Nginx or Apache/httpd. Both implementation are available in this repository. Images in this directory are used by Docker compose implementation, for more information, see section "Docker Compose setup" in the main README.md.

Mattermost-LDAP use a database to store tokens and users id. The Mattermost-LDAP Docker implementation is based on the official PostgreSQL server image automatically configured with the init script `init_postgres.sh` mounted in the `init.db` folder. The script is available in [init_db](../init_db/) folder.

## Architecture

![Docker Architecture of Mattermost-LDAP and interraction with Mattermost](https://github.com/Crivaledaz/Mattermost-LDAP/blob/master/Docker/mattermostldap-docker.png)

The Oauth container exposes port 80 and PostgreSQL container exposes port 5432. The user interacts with the Oauth server and the tokens generated by it are stored in the database. In addition, when a user logs in, his ID is stored with a unique ID. This behavior is necessary for authentication with Mattermost. The figure above illustrates interraction between Oauth server, Postgres database and Mattermost.

## Image Build

You can build docker images by hand or directly use the Docker compose, which will build image automiatically. See section "Docker Compose setup" in the main README.md, for more information. To build images by hand, follow instructions below.

First, install `docker-ce` on your host server :
- For CentOS/RHEL : https://docs.docker.com/install/linux/docker-ce/centos/
- For Fedora : https://docs.docker.com/install/linux/docker-ce/fedora/
- For Debian : https://docs.docker.com/install/linux/docker-ce/debian/
- For Ubuntu : https://docs.docker.com/install/linux/docker-ce/ubuntu/


Then, clone this repository on your host and go in `Docker` directory :
```
git clone
cd Mattermost-LDAP/Docker
```

Mattermost-LDAP is available in an embedded version which uses an Apache server image (`mattermostldap`), and in a lightweight version for Nginx (`php-ldap-pgsql`) which is only an PHP image configured to enable necessary modules.

To build mattermostldap image use the `docker build` command :
```
docker build -t mattermostldap mattermostldap/
```

Once built, the image is available in the Docker daemon and be used to create container with `docker run`. To view available images you can use :
```
docker images list
```

*Note* : It is recommended to use Podman on CentOS 8 and Fedora. For more information about Podman, see official documentation : https://podman.io/getting-started/

## Configuration

Some image parameters can be changed, by specifying the desired parameters in container's environment variable, when you create a container to adapt it to your configuration. To apply custom parameters, they must be added to the container execution line with the --env (or -e) option followed by the parameter name and the desired value (-e <parameter> = <value> ). For more details, refer to the examples in the Usage section.

### LDAP
| Parameter             | Description                                                         | Default value              |
| --------------------- | ------------------------------------------------------------------- | -------------------------- |
| ldap_host             | URL or IP to connect LDAP server                                    | `ldap://ldap.company.com/` |
| ldap_port             | Port used to connect LDAP server                                    | `389`                      |
| ldap_version          | LDAP version or protocol version used by LDAP server                | `3`                        |
| ldap_start_tls        | LDAP over STARTTLS                                                  | `false`                    |
| ldap_search_attribute | Attribute used to identify a user on the LDAP                       | `uid`                      |
| ldap_filter           | Additional filter for LDAP search                                   | `objectClass=*`            |
| ldap_base_dn          | The base directory name of your LDAP server                         | ` ou=People,o=Company`     |
| ldap_bind_dn          | The LDAP Directory Name of an service account to allow LDAP search  |                            |
| ldap_bind_pass        | The password associated to the service account to allow LDAP search |                            |


### Database
| Parameter | Description                                                        | Default value       |
| --------- | ------------------------------------------------------------------ | ------------------- |
| db_host   | Hostname or IP address of the Postgres container (database)        | `127.0.0.1`         |
| db_port   | The port of your database to connect                               | `5432`              |
| db_type   | Database type to adapt PDO. Should be pgsql for Postgres container | `pgsql`             |
| db_user   | User who manages oauth database                                    | `oauth`             |
| db_pass   | User's password to manage oauth database                           | `oauth_secure-pass` |
| db_name   | Database name for oauth server                                     | `oauth_db`          |


### Client
| Parameter     | Description                                                        | Default value                                          |
| ------------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
| client_id     | Token client ID shared with mattermost                             | `123456789`                                            |
| client_secret | Token client Secret shared with mattermost                         | `987654321`                                            |
| redirect_uri  | The callback address where oauth will send tokens to Mattermost    | `http://mattermost.company.com/signup/gitlab/complete` |
| grant_types   | The type of authentification use by Mattermost                     | `authorization_code`                                   |
| scope         | The scope of authentification use by Mattermost                    | `api`                                                  |
| user_id       | The username of the user who create the Mattermost client in Oauth |                                                        |

*Note* : Configuration is more detailed in the main README.md.

## Usage

The easiest way to use these images is to use the associated Docker compose file, located in the root of this repository. Alternatively, you can run only Mattermost-LDAP image, but you need an external database.

Once built, the mattermostldap image can be used to build a container running the oauth server of the Mattermost-LDAP module. The image contains a default configuration specified in the configuration section. To run a container from the mattermostldap image:
```
docker run -d mattermostldap --name oauth
```

To adapt the parameters of the image, you just need to specify custom parameters in environment variables of the container at its start. For example, to configure the LDAP server, use the following command:
```
docker run -d mattermostldap --name oauth -e ldap_host="ldap.company.com" -e ldap_port=389
```

To delete the oauth container, you can use :
```
docker rm oauth
```

## Improvement

In order to allow a dynamic configuration of the Mattermost-LDAP module, the choice has been made to pass the parameters by environmental variables to the container. However, this method exposes all user-defined settings to all processes in the container. As a result, passwords and security tokens are exposed throughout the container and can easily be recovered by any process running in the container, including a user shell.

Unfortunately, this is the simplest method to avoid defining static parameters in the image, forcing a recompilation of the image each time a value is changed. While waiting for a more secure solution, it is highly recommended to secure access to the container.