Guwan
/
ldap-matter
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Standalone Demo - Add test LDAP server

This commit is contained in:
Denis CLAVIER 2021-01-18 20:29:32 +01:00
parent e01077849f
commit fee27cb47f
7 changed files with 461 additions and 250 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

152
BareMetal.md Normal file
View File

@ -0,0 +1,152 @@
Install on Bare Metal
=====================
This file describes the process to install Mattermost-LDAP on a Bare Metal server.
### Requirements
Mattermost-LDAP requires the following :
* PHP (minimum 5.3.9)
* php-ldap
* php-pdo
* php-pgsql or php-mysql
* httpd
* postgresql or mariadb (mysql)
* postgresql-server or mariadb-server
* git
Obviously, you must have a Mattermost Server installed and be administrator on it, and a LDAP server configured.
### Pre-install
Install required packages :
* For Centos 7, RHEL 7 and Fedora :
```bash
#For PostgreSQL
sudo yum -y --nogpgcheck install httpd php postgresql-server postgresql php-ldap php-pdo php-xml php-pgsql git
#For MySQL
sudo yum -y --nogpgcheck install httpd php mariadb-server mariadb php-ldap php-pdo php-xml php-mysql git
```
* For Debian, ubuntu, Mint :
```bash
#For PostgreSQL
sudo apt-get -y install httpd php postgresql-server postgresql php-ldap php-pdo php-dom php-pgsql git
#For MySQL
sudo apt-get -y install httpd php mariadb-server mariadb php-ldap php-pdo php-dom php-mysql git
```
Setup your SQL server with the following command :
```bash
#For PostgreSQL (create a new database cluster)
sudo postgresql-setup initdb
#For MySQL (optional configuration for a secure MySQL server)
sudo mysql_secure_installation
```
By default, PostgreSQL does not allow client authentication on the server or a database. So we need to enable it by editing pg_hba.conf file (in `/var/lib/pgsql`). Open this file and replace `ident` by `md5` on the first three lines (local, host 127.0.0.1 and host ::1/128). It's recommended to backup the original file before editing it.
Then, start and enable service for Apache and Database (for all distribution using systemd):
```bash
#For PostgreSQL
sudo systemctl start httpd
sudo systemctl start postgresql
sudo systemctl enable httpd
sudo systemctl enable postgresql
#For MySQL
sudo systemctl start httpd
sudo systemctl start mariadb
sudo systemctl enable httpd
sudo systemctl enable mariadb
```
Your system is ready to install and run Mattermost-LDAP module.
### Install
Clone (or download and extract) this repository and move `oauth` directory in `/var/www/html` (or your httpd root directory) :
```bash
cd ~
git clone https://github.com/crivaledaz/Mattermost-LDAP.git
cd Mattermost-LDAP
cp -r oauth/ /var/www/html/
```
You need to create a database for the Oauth server. For this purpose, you can use the script `init_postgres.sh` or `init_mysql.sh`, available in `db_init` directory.
These scripts try to configure your database automatically, by creating a new user and a new database associated for the Oauth server. Scripts also create all tables necessary for the module. If the script fail, please report here, and try to configure manually your database by adapting the commands in scripts.
Before running the script you can change the default settings by editing the `db_init/config_init.sh` file and modifying configuration variables.
For more information about available parameters, refer to the [configuration section](https://github.com/Crivaledaz/Mattermost-LDAP#configuration) of the repository README.
For PostgreSQL, you can copy and paste following lines :
```bash
cd db_init
vim config_init.sh
./init_postgres.sh
```
This script will automatically create and add a new client in the Oauth server, returning a client id and a client secret. You need to keep these two token to configure Mattermost. Please be sure the client secret remained secret.
The redirect uri in the script must comply with the hostname of your Mattermost server, or else Mattermost will not be able to get data from the Oauth server. If you update your hostname, you will need to update this value. Here is an example query:
```sql
UPDATE oauth_clients SET redirect_uri = 'https://mattermost.company.com/signup/gitlab/complete' WHERE client_id = '1234567890';
```
**Warning** : The `redirect_uri` parameter should be strictly the same as the one given by Mattermost to Oauth server during authentication. If your Mattermost server uses HTTPS, make sure the `redirect_uri` begin with `https`.
*Note* : Mattermost build the `redirect_url` from the parameter `SiteURL` in `config.json`. Thus, if you set this parameter to `https://mattermost.company.com`, Mattermost will use the following redirect URL : http**s**://mattermost.company.com/signup/gitlab/complete (`SiteURL` + '/signup/gitlab/complete').
### Configuration
To complete the installation process you need to configure the Oauth server, by editing the following files :
- `oauth/LDAP/config_ldap.php` : LDAP configuration to allow user authentication on the LDAP server.
- `oauth/config_db.php` : Database configuration to allow Oauth server to store data.
For more information about available parameters, refer to the [configuration section](https://github.com/Crivaledaz/Mattermost-LDAP#configuration) of the repository README.
### Configure Mattermost
Active Gitlab authentication in `System Console > Gitlab` (or `config.json`) and fill application id and secret with the two tokens got during install section. For the next fields use this :
```
User API Endpoint : http://HOSTNAME/oauth/resource.php
Auth Endpoint: http://HOSTNAME/oauth/authorize.php
Token Endpoint: http://HOSTNAME/oauth/token.php
```
Change `HOSTNAME` by hostname or ip of the server where you have installed Mattermost-LDAP module.
Since Mattermost 4.9, these fields are disabled in admin panel, so you need to edit directly section `GitLabSettings` in the Mattermost configuration file `config.json`.
In the `config.json` file, GitLab configuration is gathered in the section `GitLabSettings`. You have to enable it and to fill parameters with your values. Once completed, the section should look like :
```
"GitLabSettings": {
"Enable": true,
"Secret": "fedcba987654321fedcba987654321",
"Id": "123456789abcdef123456789abcdef",
"Scope": "",
"AuthEndpoint": "http://localhost/oauth/authorize.php",
"TokenEndpoint": "http://localhost/oauth/token.php",
"UserApiEndpoint": "http://localhost/oauth/resource.php"
},
```
*Note* : You need to restart the Mattermost server to take into account the change.
## Usage
If you have succeeded the previous step you only have to go to the login page of your Mattermost server and click on the Gitlab Button. You will be redirected to a form asking for your LDAP credentials. If your credentials are valid, you will be asked to authorize Oauth to give your information to Mattermost. After authorizing you should be redirected on Mattermost connected with your account.
Keep in mind this will create a new account on your Mattermost server with information from LDAP. The process will fail if an existing user already use your LDAP email. To bind an existing user to the LDAP authentication, sign in Mattermost with this user account, go in `account settings > security > sign-in method and "switch to using Gitlab SSO"`.

153
Container.md Normal file
View File

@ -0,0 +1,153 @@
Install using containers - Docker/Podman
========================================
The easiest way to setup Mattermost-LDAP is using the docker-compose implementation.
For production use, you must use the `docker-copose.yaml` file available at the root of this repository. Unlike the Demo, this docker-compose file only setup Mattermost-LDAP with an Apache server and a PostgreSQL database.
This implementation uses an embedded Oauth server, which can be configured by environment variables.
## Requirements
To use docker-compose implementation, you need to install Docker and Docker compose. For CentOS 8 and Fedora, it is recommended to use Podman and Podman compose instead of Docker and Docker compose.
For more information about Docker installation, see official guide : https://docs.docker.com/engine/install/
For more information about Podman installation, see official documentation : https://podman.io/getting-started/installation.html
## Preparation
First, you need to clone (or download and extract) this repository on your server :
```bash
git clone https://github.com/Crivaledaz/Mattermost-LDAP
cd Mattermost-LDAP
```
Then, before running the docker-compose file, you need to adapt LDAP and DB parameters. All parameters are gathered in the `env.example` file and they are passed to Postgres and Oauth server by environment variables.
Copy the `env.example` file to `.env` and edit it to change with your values.
**Warning** : Postgres root password and database Oauth password must be changed. Client and secret tokens must be generated randomly, using `openssl rand -hex 32`.
For more information about available parameters, refer to the [configuration section](https://github.com/Crivaledaz/Mattermost-LDAP#configuration) of the repository README.
Otherwise, for production, you need to create a directory to store PostgreSQL data. This directory will contain the Oauth database and allows data persistence, even if containers are stopped or restarted. By default, this Mattermost-LDAP implementation uses folder `data/` next to the `docker-compose.yaml` file to store data. This folder need to be created before running Docker compose :
```bash
mkdir data
```
To use Mattermost-LDAP with your own Mattermost server, you need to configure your Mattermost instance as described in section "Configure Mattermost".
## Configure Mattermost
Active Gitlab authentication in `System Console > Gitlab` (or `config.json`) and fill application id and secret with the two tokens got during install section. For the next fields use this :
```
User API Endpoint : http://HOSTNAME/oauth/resource.php
Auth Endpoint: http://HOSTNAME/oauth/authorize.php
Token Endpoint: http://HOSTNAME/oauth/token.php
```
Change `HOSTNAME` by hostname or ip of the server where you have installed Mattermost-LDAP module.
Since Mattermost 4.9, these fields are disabled in admin panel, so you need to edit directly section `GitLabSettings` in the Mattermost configuration file `config.json`.
In the `config.json` file, GitLab configuration is gathered in the section `GitLabSettings`. You have to enable it and to fill parameters with your values. Once completed, the section should look like :
```
"GitLabSettings": {
"Enable": true,
"Secret": "fedcba987654321fedcba987654321",
"Id": "123456789abcdef123456789abcdef",
"Scope": "",
"AuthEndpoint": "http://localhost/oauth/authorize.php",
"TokenEndpoint": "http://localhost/oauth/token.php",
"UserApiEndpoint": "http://localhost/oauth/resource.php"
},
```
*Note* : You need to restart the Mattermost server to take into account the change.
## Usage
Once the `.env` file have been adapted, you can run the docker-compose file with the following commands :
```bash
# With Docker
docker-compose build
docker-compose up -d
# With Podman
podman-compose build
podman-compose up -d
```
The build command allows Docker compose to build necessary image. Images use are available in the [Docker/](Docker) directory of this repository. The up command starts all services described in the Docker compose file.
Once all services are started, go to Mattermost server and click on GitLab button to login with LDAP credential on Mattermost-LDAP. Then, if you login successfully and authorize Mattermost-LDAP to transmit your data to Mattermost, you should be log on Mattermost.
To stop Mattermost server and Mattermost-LDAP, use the following command :
```bash
# With Docker
docker-compose down
# With Podman
podman-compose down
```
## Extension
### Additional information for usage with nginx-proxy, nginx-proxy-letsencrypt
In case you want to use `nginx-proxy`, `nginx-proxy-letsencrypt`, and (for example) `openldap`, it is possible to use subdomains for your services. Following this approach you could have mattermost running on on `https://chat.example.com` and authenticate via this container from `https://oauth.example.com`. This container will then have its own letsencypt certificate.
You can add the following settings to your configuration files for this type of setup.
In `docker-compose.yaml` :
```yaml
version: '3'
[...]
services:
mattermost-ldap:
[...]
expose:
- 80
- 443
environment:
[...]
- VIRTUAL_HOST=oauth.example.com,www.oauth.example.com
- LETSENCRYPT_HOST=oauth.example.com,www.oauth.example.com
[...]
```
In `.env`:
```bash
[...]
redirect_uri = "https://chat.example.com/signup/gitlab/complete"
ldap_filter = "(&(objectClass=inetOrgPerson)(memberof=cn=chat,ou=groups,dc=example,dc=com))"
[...]
```
This filter will additionally allow you to filter based on group affiliation within your LDAP server.
Finally, add the following to your mattermost `config.json` to ensure the correct redirect.
```json
"GitLabSettings": {
"Enable": true,
"Secret": "XXX",
"Id": "YYY",
"Scope": "",
"AuthEndpoint": "https://oauth.example.com/oauth/authorize.php",
"TokenEndpoint": "https://oauth.example.com/oauth/token.php",
"UserApiEndpoint": "https://oauth.example.com/oauth/resource.php"
},
```

17
Demo/bootstrap.ldif Normal file
View File

@ -0,0 +1,17 @@
# Define OU for people
dn: ou=People,dc=example,dc=com
description: Company Employees
objectclass: organizationalUnit
objectclass: top
ou: People
# Entry 1: John DOE
dn: uid=jdoe,ou=People,dc=example,dc=com
uid: jdoe
cn: John DOE
sn: DOE
gn: John
mail: john.doe@example.com
objectClass: inetOrgPerson
# Password : test1234
userPassword: {SSHA}GFR6gX9RlEj/AaP5mxpdCh1J1FM/pyn3

33
Demo/config.json
View File

@ -20,6 +20,7 @@
], ],
"ReadTimeout": 300, "ReadTimeout": 300,
"WriteTimeout": 300, "WriteTimeout": 300,
"IdleTimeout": 60,
"MaximumLoginAttempts": 10, "MaximumLoginAttempts": 10,
"GoroutineHealthThreshold": -1, "GoroutineHealthThreshold": -1,
"GoogleDeveloperKey": "", "GoogleDeveloperKey": "",
@ -33,6 +34,7 @@
"EnableLinkPreviews": false, "EnableLinkPreviews": false,
"EnableTesting": false, "EnableTesting": false,
"EnableDeveloper": false, "EnableDeveloper": false,
"EnableOpenTracing": false,
"EnableSecurityFixAlert": true, "EnableSecurityFixAlert": true,
"EnableInsecureOutgoingConnections": false, "EnableInsecureOutgoingConnections": false,
"AllowedUntrustedInternalConnections": "", "AllowedUntrustedInternalConnections": "",
@ -75,6 +77,7 @@
"ExperimentalEnableDefaultChannelLeaveJoinMessages": true, "ExperimentalEnableDefaultChannelLeaveJoinMessages": true,
"ExperimentalGroupUnreadChannels": "disabled", "ExperimentalGroupUnreadChannels": "disabled",
"ExperimentalChannelOrganization": false, "ExperimentalChannelOrganization": false,
"ExperimentalChannelSidebarOrganization": "disabled",
"ImageProxyType": "", "ImageProxyType": "",
"ImageProxyURL": "", "ImageProxyURL": "",
"ImageProxyOptions": "", "ImageProxyOptions": "",
@ -153,6 +156,22 @@
"EnableWebhookDebugging": true, "EnableWebhookDebugging": true,
"EnableDiagnostics": true "EnableDiagnostics": true
}, },
"ExperimentalAuditSettings": {
"SysLogEnabled": false,
"SysLogIP": "localhost",
"SysLogPort": 6514,
"SysLogTag": "",
"SysLogCert": "",
"SysLogInsecure": false,
"SysLogMaxQueueSize": 1000,
"FileEnabled": false,
"FileName": "",
"FileMaxSizeMB": 100,
"FileMaxAgeDays": 0,
"FileMaxBackups": 0,
"FileCompress": false,
"FileMaxQueueSize": 1000
},
"NotificationLogSettings": { "NotificationLogSettings": {
"EnableConsole": true, "EnableConsole": true,
"ConsoleLevel": "DEBUG", "ConsoleLevel": "DEBUG",
@ -205,6 +224,7 @@
"SMTPPassword": "", "SMTPPassword": "",
"SMTPServer": "localhost", "SMTPServer": "localhost",
"SMTPPort": "10025", "SMTPPort": "10025",
"SMTPServerTimeout": 10,
"ConnectionSecurity": "", "ConnectionSecurity": "",
"SendPushNotifications": false, "SendPushNotifications": false,
"PushNotificationServer": "", "PushNotificationServer": "",
@ -280,7 +300,8 @@
"Scope": "User.Read", "Scope": "User.Read",
"AuthEndpoint": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize", "AuthEndpoint": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
"TokenEndpoint": "https://login.microsoftonline.com/common/oauth2/v2.0/token", "TokenEndpoint": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
"UserApiEndpoint": "https://graph.microsoft.com/v1.0/me" "UserApiEndpoint": "https://graph.microsoft.com/v1.0/me",
"DirectoryId": ""
}, },
"LdapSettings": { "LdapSettings": {
"Enable": false, "Enable": false,
@ -294,6 +315,8 @@
"UserFilter": "", "UserFilter": "",
"GroupFilter": "", "GroupFilter": "",
"GuestFilter": "", "GuestFilter": "",
"EnableAdminFilter": false,
"AdminFilter": "",
"GroupDisplayNameAttribute": "", "GroupDisplayNameAttribute": "",
"GroupIdAttribute": "", "GroupIdAttribute": "",
"FirstNameAttribute": "", "FirstNameAttribute": "",
@ -333,6 +356,7 @@
"SignRequest": false, "SignRequest": false,
"IdpUrl": "", "IdpUrl": "",
"IdpDescriptorUrl": "", "IdpDescriptorUrl": "",
"IdpMetadataUrl": "",
"AssertionConsumerServiceURL": "", "AssertionConsumerServiceURL": "",
"SignatureAlgorithm": "RSAwithSHA1", "SignatureAlgorithm": "RSAwithSHA1",
"CanonicalAlgorithm": "Canonical1.0", "CanonicalAlgorithm": "Canonical1.0",
@ -343,6 +367,8 @@
"PrivateKeyFile": "", "PrivateKeyFile": "",
"IdAttribute": "", "IdAttribute": "",
"GuestAttribute": "", "GuestAttribute": "",
"EnableAdminAttribute": false,
"AdminAttribute": "",
"FirstNameAttribute": "", "FirstNameAttribute": "",
"LastNameAttribute": "", "LastNameAttribute": "",
"EmailAttribute": "", "EmailAttribute": "",
@ -386,7 +412,8 @@
"ClientSideCertCheck": "secondary", "ClientSideCertCheck": "secondary",
"EnableClickToReply": false, "EnableClickToReply": false,
"LinkMetadataTimeoutMilliseconds": 5000, "LinkMetadataTimeoutMilliseconds": 5000,
"RestrictSystemAdmin": false "RestrictSystemAdmin": false,
"UseNewSAMLLibrary": false
}, },
"AnalyticsSettings": { "AnalyticsSettings": {
"MaxUsersForStatistics": 2500 "MaxUsersForStatistics": 2500
@ -452,6 +479,8 @@
} }
}, },
"EnableMarketplace": true, "EnableMarketplace": true,
"EnableRemoteMarketplace": true,
"AutomaticPrepackagedPlugins": true,
"RequirePluginSignature": false, "RequirePluginSignature": false,
"MarketplaceUrl": "https://api.integrations.mattermost.com", "MarketplaceUrl": "https://api.integrations.mattermost.com",
"SignaturePublicKeyFiles": [] "SignaturePublicKeyFiles": []

28
Demo/docker-compose.yaml
View File

@ -1,5 +1,24 @@
version: '3' version: '3'
services: services:
ldap:
image: osixia/openldap:1.4.0
restart: always
domainname: "example.com"
hostname: "ldap"
command: --copy-service
ports:
- 389:389
- 636:636
volumes:
- ./bootstrap.ldif:/container/service/slapd/assets/config/bootstrap/ldif/50-bootstrap.ldif
environment:
LDAP_ORGANISATION: "Example Corp"
LDAP_DOMAIN: "example.com"
LDAP_ADMIN_PASSWORD: "changeMe-Pl34$e"
LDAP_READONLY_USER: "true"
LDAP_READONLY_USER_USERNAME: "butler"
LDAP_READONLY_USER_PASSWORD: "readonly"
nginx: nginx:
image: nginx image: nginx
restart: always restart: always
@ -18,15 +37,14 @@ services:
volumes: volumes:
- ../oauth:/var/www/html/oauth - ../oauth:/var/www/html/oauth
environment: environment:
ldap_host: ldap://ldap.company.com:389/ ldap_host: ldap://localhost:389/
ldap_port: 389 ldap_port: 389
ldap_version: 3 ldap_version: 3
ldap_start_tls: false
ldap_search_attribute: uid ldap_search_attribute: uid
ldap_base_dn: "ou=People,o=Company" ldap_base_dn: "dc=example,dc=com"
ldap_filter: "(objectClass=*)" ldap_filter: "(objectClass=*)"
ldap_bind_dn: "" ldap_bind_dn: "cn=butler,dc=example,dc=com"
ldap_bind_pass: "" ldap_bind_pass: "readonly"
db_host: "127.0.0.1" db_host: "127.0.0.1"
db_port: "5432" db_port: "5432"
db_type: "pgsql" db_type: "pgsql"

249
README.md
View File

@ -17,15 +17,19 @@ This module provides an Oauth2 server designed for PHP, an LDAP connector for PH
See Limitation section for more information. See Limitation section for more information.
## Docker-Compose setup ## Quick Start - Demonstration
The easiest way to setup Mattermost-LDAP is using the docker-compose implementation. Two docker-compose files are available in this repository : To test and try Mattermost-LDAP, you can use the demonstration available in the `Demo/` folder. This demonstration is based on a docker-compose implementation describe in the `Demo/docker-compose.yaml` file.
- `Demo/docker-compose.yaml` : To test and try Mattermost-LDAP. This docker-compose file instantiate a Mattermost Server from the official preview image provides by Mattermost and a Mattemrost-LDAP pre-configured server with a PostgreSQL database.
- `docker-compose.yaml` : For production use. This docker-compose file only setup Mattermost-LDAP with an Apache server and a PostgreSQL database. This implementation uses an embedded Oauth server, which can be configured by environment variables. This docker-compose file instantiate a Mattermost Server from the official preview image provides by Mattermost, a Mattemrost-LDAP pre-configured server with a PostgreSQL database and an OpenLDAP server with a test user : John DOE.
To try Mattermost-LDAP, please read the following instructions.
### Requirements ### Requirements
To use docker-compose implementation, you need to install Docker and Docker compose. For CentOS 8 and Fedora, it is recommended to use Podman and Podman compose instead of Docker and Docker compose. Firstly, to use docker-compose, you need to install Docker and Docker compose.
*Note* : For CentOS 8 and Fedora, it is recommended to use Podman and Podman compose instead of Docker and Docker compose.
For more information about Docker installation, see official guide : https://docs.docker.com/engine/install/ For more information about Docker installation, see official guide : https://docs.docker.com/engine/install/
@ -36,158 +40,71 @@ For more information about Podman installation, see official documentation : htt
First, you need to clone (or download and extract) this repository on your server : First, you need to clone (or download and extract) this repository on your server :
```bash ```bash
git clone https://github.com/Crivaledaz/Mattermost-LDAP git clone https://github.com/Crivaledaz/Mattermost-LDAP
cd Mattermost-LDAP cd Mattermost-LDAP/Demo
# For Demo (optional)
cd Demo
``` ```
Then, before running the docker-compose file, you need to adapt LDAP and DB parameters. All parameters are gathered in the `env.example` file and they are passed to Postgres and Oauth server by environment variables. Then, you have to rename example configuration file without the example extension.
Copy the `env.example` file to `.env` and edit it to change with your values. For demo, parameters are directly in the `docker-compose.yaml` file, so you need to edit this file instead of `.env`.
**Warning** : Postgres root password and database Oauth password must be changed. Client and secret tokens must be generated randomly, using `openssl rand -hex 32`.
For more information about parameters, see beelow the configuration section of this documentation.
Otherwise, for production, you need to create a directory to store PostgreSQL data. This directory will contain the Oauth database and allows data persistence, even if containers are stopped or restarted. By dafault, this Mattermost-LDAP implementation uses folder `data/` next to the `docker-compose.yaml` file to store data. This folder need to be created before running Docker compose :
```bash ```bash
mkdir data cp -p ../oauth/config_db.php.example ../oauth/config_db.php
cp -p ../oauth/LDAP/config_ldap.php.example ../oauth/LDAP/config_ldap.php
``` ```
For demo, you need to rename example configuration file without the example extension. Optionnally, you can adapt deployment parameters by editing the `Demo/docker-compose.yaml` file, before running it. Parameters are passed to Postgres database, Oauth server and LDAP server by environment variables. They are gathered in the `environment` section for each container.
```bash
cd Mattermost-LDAP/
cp -p oauth/config_db.php.example oauth/config_db.php
cp -p oauth/LDAP/config_ldap.php.example oauth/LDAP/config_ldap.php
```
To use Mattermost-LDAP with you own Mattermost server, you need to configure your Mattermost instance as described in subsection "Mattermost" in section "Configuration" For more information about available parameters, see the configuration section of this documentation.
### Usage ### Usage
Once the `.env` file have been adapted, you can run the docker-compose file with the following commands : To run the docker-compose file use the following command :
```bash ```bash
docker-compose build # With Docker
docker-compose up -d docker-compose up -d
# With Podman
podman-compose up -d
``` ```
The build command allows Docker compose to build necessary image. Images use are available in the [Docker/](Docker) directory of this repository. The up command starts all services described in the Docker compose file. The up command starts all services described in the Docker compose file. The `-d` argument allow to start all container in background, in a detach mode.
Once all services are started, go to Mattermost server. For the demo, Mattermost should be available on localhost : http://localhost. Click on GitLab button to login with LDAP credential on Mattermost-LDAP. Then, if you login successfully and authorize Mattermost-LDAP to transmit your data to Mattermost, you should be log on Mattermost. Once all services are started, go to Mattermost server. Mattermost should be available after a few seconds on localhost : http://localhost.
*Note* : In demo, Mattermost server is available after few seconds. On the Mattermost login page, click on GitLab button to login with LDAP credential on Mattermost-LDAP. Complete the login form with following credentials :
```
username: jdoe
password: test1234
```
Once you are logged in, you should authorize Mattermost-LDAP to transmit LDAP data to Mattermost. Then, you should be log on Mattermost with the John DOE user account and create a new team.
That's all, you are logged into Mattermost with an LDAP account !
To stop Mattermost server and Mattermost-LDAP, use the following command : To stop Mattermost server and Mattermost-LDAP, use the following command :
```bash ```bash
# With Docker # With Docker
docker-compose down docker-compose.yaml docker-compose down
# With Podman # With Podman
podman-compose down docker-compose.yaml podman-compose down
``` ```
*Note* : Docker compose setup replaces Bare-Metal setup, but configuration remains necessary. ## Installation
## Bare-Metal setup Mattermost-LDAP can be installed using containers or directly on a bare metal server, depending on your environment. Note that the installation process is easier with containers.
### Requirements To install Mattermost-LDAP using containers use this documentation - [Container.md](Container.md).
Mattermost-LDAP requires the following : To install Mattermost-LDAP on Bare Metal use the following documentation - [BareMetal.md](BareMetal.md).
* PHP (minimum 5.3.9) Both installations allow to set up Mattermost-LDAP for a production use.
* php-ldap
* php-pdo
* php-pgsql or php-mysql
* httpd
* postgresql or mariadb (mysql)
* postgresql-server or mariadb-server
* git
Obviously, you must have a Mattermost Server installed and be administrator on it, and a LDAP server configured.
### Pre-install
Install required packages :
* For Centos 7, RHEL 7 and Fedora :
```bash
#For PostgreSQL
sudo yum -y --nogpgcheck install httpd php postgresql-server postgresql php-ldap php-pdo php-xml php-pgsql git
#For MySQL
sudo yum -y --nogpgcheck install httpd php mariadb-server mariadb php-ldap php-pdo php-xml php-mysql git
```
* For Debian, ubuntu, Mint :
```bash
#For PostgreSQL
sudo apt-get -y install httpd php postgresql-server postgresql php-ldap php-pdo php-dom php-pgsql git
#For MySQL
sudo apt-get -y install httpd php mariadb-server mariadb php-ldap php-pdo php-dom php-mysql git
```
Setup your SQL server with the following command :
```bash
#For PostgreSQL (create a new database cluster)
sudo postgresql-setup initdb
#For MySQL (optional configuration for a secure MySQL server)
sudo mysql_secure_installation
```
By default, PostgreSQL does not allow client authentication on the server or a database. So we need to enable it by editing pg_hba.conf file (in `/var/lib/pgsql`). Open this file and replace `ident` by `md5` on the first three lines (local, host 127.0.0.1 and host ::1/128). It's recommended to backup the original file before editing it.
Then, start and enable service for Apache and Database (for all distribution using systemd):
```bash
#For PostgreSQL
sudo systemctl start httpd
sudo systemctl start postgresql
sudo systemctl enable httpd
sudo systemctl enable postgresql
#For MySQL
sudo systemctl start httpd
sudo systemctl start mariadb
sudo systemctl enable httpd
sudo systemctl enable mariadb
```
Your system is ready to install and run Mattermost-LDAP module.
### Install
Clone (or download and extract) this repository and move `oauth` directory in `/var/www/html` (or your httpd root directory) :
```bash
cd ~
git clone https://github.com/crivaledaz/Mattermost-LDAP.git
cd Mattermost-LDAP
cp -r oauth/ /var/www/html/
```
You need to create a database for the Oauth server. For this purpose, you can use the script `init_postgres.sh` or `init_mysql.sh`, available in `db_init` directory. These scripts try to configure your database automatically, by creating a new user and a new database associated for the Oauth server. Scripts also create all tables necessary for the module. If script failed, please report here, and try to configure manually your database by adapting command in scripts. Before running the script you can change the default settings by editing the `db_init/config_init.sh` file and modifying configuration variables. For PostgreSQL, you can copy and paste following lines :
```bash
cd db_init
vim config_init.sh
./init_postgres.sh
```
This script will automatically create and add a new client in the Oauth server, returning a client id and a client secret. You need to keep these two token to configure Mattermost. Please be sure the client secret remained secret.
The redirect uri in the script must comply with the hostname of your Mattermost server, or else Mattermost will not be able to get data from the Oauth server. If you update your hostname, you will need to update this value. Here is an example query:
```sql
UPDATE oauth_clients SET redirect_uri = 'https://mattermost.company.com/signup/gitlab/complete' WHERE client_id = '1234567890';
```
**Warning** : The `redirect_uri` parameter should be strictly the same as the one given by Mattermost to Oauth server during authentication. If your Mattermost server uses HTTPS, make sure the `redirect_uri` begin with `https`.
*Note* : Mattermost build the `redirect_url` from the parameter `SiteURL` in `config.json`. Thus, if you set this parameter to `https://mattermost.company.com`, Mattermost will use the following redirect URL : http**s**://mattermost.company.com/signup/gitlab/complete (`SiteURL` + '/signup/gitlab/complete').
## Configuration ## Configuration
Configuration files are provided with examples and default values. Each config file has an `example` extension, so you need to copy and to rename them without this extension. You can find a detailed description of each parameters available below. Configuration files are provided with examples and default values. Each config file has an `example` extension, so you need to copy and to rename them without this extension.
You can find a detailed description of each parameters available below.
**Note** : For container, these variables are overload by environment variables define in `.env` file or `docker-compose.yaml` file.
### Init script parameters ### Init script parameters
@ -211,18 +128,6 @@ The `client_id` and `client_secret` should be different and random tokens. You c
The var `user_id` has no impact, and could be used as a commentary field. By default this field is empty. The var `user_id` has no impact, and could be used as a commentary field. By default this field is empty.
### Mattermost
Active Gitlab authentication in `System Console > Gitlab` (or `config.json`) and fill application id and secret with the two tokens got during install section. For the next fields use this :
```
User API Endpoint : http://HOSTNAME/oauth/resource.php
Auth Endpoint: http://HOSTNAME/oauth/authorize.php
Token Endpoint: http://HOSTNAME/oauth/token.php
```
Change `HOSTNAME` by hostname or ip of the server where you have installed Mattermost-LDAP module.
Since Mattermost 4.9, these fields are disabled in admin panel, so you need to edit directly section `GitLabSettings` in the Mattermost configuration file `config.json`.
### Database credentials ### Database credentials
Edit `oauth/config_db.php` and adapt, with your settings, to set up database in PHP. Edit `oauth/config_db.php` and adapt, with your settings, to set up database in PHP.
@ -266,62 +171,6 @@ Parameters 'ldap_bind_dn' and 'ldap_bind_pass' are required if your LDAP is rest
To try your configuration you can use `ldap.php` available at the root of this project which use the LDAP library for PHP or you can use `ldapsearch` command in a shell. To try your configuration you can use `ldap.php` available at the root of this project which use the LDAP library for PHP or you can use `ldapsearch` command in a shell.
### Additional information for usage with nginx-proxy, nginx-proxy-letsencrypt
In case you want to use `nginx-proxy`, `nginx-proxy-letsencrypt`, and (for example) `openldap`, it is possible to use subdomains for your services. Following this approach you could have mattermost running on on `https://chat.example.com` and authenticate via this container from `https://oauth.example.com`. This container will then have its own letsencypt certificate.
You can add the following settings to your configuration files for this type of setup.
docker-compose.yaml
```yaml
version: '3'
[...]
services:
mattermost-ldap:
[...]
expose:
- 80
- 443
environment:
[...]
- VIRTUAL_HOST=oauth.example.com,www.oauth.example.com
- LETSENCRYPT_HOST=oauth.example.com,www.oauth.example.com
[...]
```
.env
```bash
[...]
redirect_uri = "https://chat.example.com/signup/gitlab/complete"
ldap_filter = "(&(objectClass=inetOrgPerson)(memberof=cn=chat,ou=groups,dc=example,dc=com))"
[...]
```
This filter will additionally allow you to filter based on group affiliation within your LDAP server.
Finally, add the following to your mattermost config.json to ensure the correct redirect.
```json
"GitLabSettings": {
"Enable": true,
"Secret": "XXX",
"Id": "YYY",
"Scope": "",
"AuthEndpoint": "https://oauth.example.com/oauth/authorize.php",
"TokenEndpoint": "https://oauth.example.com/oauth/token.php",
"UserApiEndpoint": "https://oauth.example.com/oauth/resource.php"
},
```
## Usage ## Usage
If you have succeeded previous step you only have to go to the login page of your Mattermost server and click on the Gitlab Button. You will be redirected to a form asking for your LDAP credentials. If your credentials are valid, you will be asked to authorize Oauth to give your information to Mattermost. After authorizing you should be redirected on Mattermost connected with your account. If you have succeeded previous step you only have to go to the login page of your Mattermost server and click on the Gitlab Button. You will be redirected to a form asking for your LDAP credentials. If your credentials are valid, you will be asked to authorize Oauth to give your information to Mattermost. After authorizing you should be redirected on Mattermost connected with your account.
@ -334,17 +183,17 @@ This module has been tested on Centos 7, Fedora and Ubuntu with PostgreSQL and M
Others operating systems has not been tested yet but should work fine. Others operating systems has not been tested yet but should work fine.
MySQL has not really been tested so it is possible there is some bugs with. MySQL has not really been tested so it is possible there is some bugs.
## To do list ## To do list
* HTTPS support
* Add CSS to make a beautiful interface for Oauth server * Support multi-branch LDAP [issue #74](https://github.com/Crivaledaz/Mattermost-LDAP/issues/74)
* Change Gitlab button * Change Gitlab button [issue #46](https://github.com/Crivaledaz/Mattermost-LDAP/issues/46)
* Security audit * Security audit
## Thanks ## Thanks
I wish to thank CS SI and my colleagues for their help and support. Also, I thank Brent Shaffer for his [Oauth-server-php](https://github.com/bshaffer/oauth2-server-php) project and its [documentation](https://bshaffer.github.io/oauth2-server-php-docs/). I wish to thank CS GROUP and my colleagues for their help and support. Also, I thank Brent Shaffer for his [Oauth-server-php](https://github.com/bshaffer/oauth2-server-php) project and its [documentation](https://bshaffer.github.io/oauth2-server-php-docs/).
## Known issues ## Known issues

33
ldap.php
View File

@ -5,26 +5,22 @@ error_reporting(E_ALL);
###################################---Configuration---################################ ###################################---Configuration---################################
// Ldap adress and port // Ldap adress and port
$hostname = "ldap://company.com:389"; $hostname = "ldap://localhost:389";
// LDAP version // LDAP version
$ldap_version = 3; $ldap_version = 3;
//LDAP STARTTLS // User identifier - UID
$ldap_start_tls = false; $uid = "jdoe";
//Unique identifier of user on LDAP // Bind directory name
$uid = "username"; $bind_dn = "cn=butler,dc=example,dc=com";
$email = "username@company.com";
//directory name (dn) // Bind password
$dn = "uid=username,ou=People,o=Company"; $bind_pass = "readonly";
//Password (Only for test, we give the password in clear text)
$pass = "user_pass";
// Base directory name // Base directory name
$base = "ou=People,o=Company"; $base = "ou=People,dc=example,dc=com";
###################################################################################### ######################################################################################
@ -35,21 +31,19 @@ ldap_set_option($ldap, LDAP_OPT_PROTOCOL_VERSION, $ldap_version);
if ($ldap) { if ($ldap) {
echo "Successful connection ! <br />"; echo "Successful connection ! <br />";
echo "Checking LDAP credentials ... <br />"; echo "Authenticating with bind credentials ... <br />";
$is_valid=ldap_bind($ldap,$dn,$pass); $is_valid=ldap_bind($ldap,$bind_dn,$bind_pass);
if ($is_valid) { if ($is_valid) {
echo "Successful authentication ! <br />"; echo "Successful authentication ! <br />";
echo "Getting user informations ...<br />"; echo "Getting user informations ...<br />";
$user_data=ldap_search($ldap, $base, "mail=" . $email); $user_data=ldap_search($ldap, $base, "uid=" . $uid);
if ($user_data) if ($user_data) {
{
echo "Data recovered with success ! <br />"; echo "Data recovered with success ! <br />";
echo "Extracting useful data : <br /><br />"; echo "Extracting useful data : <br /><br />";
$info_user = ldap_get_entries($ldap, $user_data); $info_user = ldap_get_entries($ldap, $user_data);
for ($i=0; $i<$info_user["count"]; $i++) { for ($i=0; $i<$info_user["count"]; $i++) {
echo "dn: " . $info_user[$i]["dn"] . "<br />"; echo "dn: " . $info_user[$i]["dn"] . "<br />";
echo "cn: " . $info_user[$i]["cn"][0] . "<br />"; echo "cn: " . $info_user[$i]["cn"][0] . "<br />";
echo "uid: " . $info_user[$i]["uid"][0] . "<br />"; echo "uid: " . $info_user[$i]["uid"][0] . "<br />";
@ -59,9 +53,8 @@ if ($ldap) {
echo "No data recovered ! <br /><br />"; echo "No data recovered ! <br /><br />";
} }
} else { } else {
echo "Identification has failed ... Check your credentials<br /><br />"; echo "Identification has failed ... Check bind credentials<br /><br />";
} }
echo "Closing LDAP connection."; echo "Closing LDAP connection.";
ldap_close($ldap); ldap_close($ldap);
} else { } else {