Installation On-Premises : prérequis et configuration

Cette documentation présente les étapes pour installer et mettre à jour la solution LockSelf On-Premises.

Pour les mises à jour, reportez-vous directement au point 9. Update.

____________________________________________________________________________________

Pré-requis

  • Connaître l'environnement Linux.
  • Savoir manipuler un environnement Docker et être à l'aise avec docker-compose.
  • Maitriser les commandes "docker ps", "docker exec", "docker logs", "docker images", "docker load" et toutes les commandes basiques de docker.
  • Avoir déjà déployé et maintenu des environnements MySQL/MariaDB.

1. Préambule

L’application LockSelf utilise deux composants :

  • Une API REST PHP (PHP version 7.4)
  • Une base de données MariaDB (MariaDB version 10.6)

La base de données et l’API LockSelf sont déployées via Docker en utilisant respectivement les images officielles MariaDB (https://hub.docker.com/_/mariadb) et php:7-4-fpm-alpine (https://hub.docker.com/_/php).

L’image MariaDB est utilisée sans modification particulière.

L’image PHP (base Alpine) est quant à elle optimisée :

  • Compilation et configuration de Nginx
  • Configuration de PHP-FPM
  • Installation et configuration de Supervisord

Tous les processus à l’intérieur du conteneur applicatif s’exécutent avec l’utilisateur ‘nobody’. En ce qui concerne le conteneur MariaDB, l’utilisateur utilisé est ‘mysql’.

Nous conseillons de ne pas mettre les deux parties (bdd et applicatif) sur le même serveur et nous préconisons l’utilisation l’un des OS suivants :

  • Ubuntu 20.04 LTS (Focal Fossa) ou ultérieur
  • Debian 10 (Buster) ou ultérieur
  • CentOS 7 / 8

Les deux serveurs (bdd et applicatif) doivent avoir le package docker d’installé. Nous n’expliquerons pas comment fonctionne docker dans cette procédure, vous devez être initié à cet outil afin de correctement faire l’installation.

💡Nous préconisons un passage via Ansible du playbook hardening, qui permet de mettre en place une sécurité supplémentaire au sein du host (https://github.com/openstack/ansible-hardening).

 

2. Pré-requis

Avant de commencer l’installation du service, assurez-vous d’avoir les éléments suivants :

  • Le nom de domaine que vous souhaitez utiliser. (ex : lockself.company.com)
  • Le certificat SSL et la clé privée associés à ce nom de domaine
  • Les informations d’authentification et de connexion à votre SMTP (qui servira à envoyer les emails systèmes relatif à l’utilisation de l’application)

Si vous souhaitez mettre en place une interconnexion sur un annuaire d’entreprise, nous utilisons le protocole SAMLv2. Il faut donc vous assurez d’avoir à disposition un module de type ADFS pour Active Directory, OpenID pour OpenLDAP ou les modules SAMLv2 inclus dans Azure ou Office 365.

 

3. Description de l’infrastructure simplifiée

mceclip0.png

💡L’installation de LockSelf peut également se faire en mode cluster, pour la partie applicative et pour la partie base de données.

 

4. Matrice de flux de réseaux

Les flux à mettre en place pour les différents serveurs sont :

Serveur Entrant Sortant
Applicatif 443 depuis l'extérieur 25, 465 ou 587 vers votre serveur SMTP
Base de données 3306 depuis le subnet des serveurs applicatifs  

 

5. Installation du premier composant : La base de données MariaDB

5.1. Action à réaliser sur le serveur de base de données – Étape 1

Pour le déploiement du conteneur de base de données, trois possibilités. À vous de choisir laquelle vous souhaitez utiliser suivant les préconisations de l’entreprise.

5.1.1. Lancement manuel

docker run \
--name mariadb \
-v /var/lib/mysql:/var/lib/mysql \
-e MYSQL_ROOT_PASSWORD=my-secret-pwd \
-e MYSQL_DATABASE=lockself \
-p 3306:3306 \
-d mariadb:10.6.X
 
  • --name : correspond au nom du conteneur une fois créé
  • -v : correspond au volume monté permettant la persistance des données
  • -e : MYSQL_ROOT_PASSWORD – remplacer « my-secret-pwd » par le mot de passe qui sera associé à l’utilisateur root au premier lancement du conteneur
  • -e : MYSQL_DATABASE – « lockself » correspond au nom de la base de données créée au premier lancement du conteneur
  • -p : permet au serveur host de forward les requêtes sur le port 3306 au conteneur
  • -d : permet au conteneur de se lancer en background
  • mariadb:10.6.X : correspond à la version de l’image MariaDB utilisée

Les variables d’environnements option -e sont prises en compte uniquement lors du premier démarrage du conteneur. Si des datas sont présentes dans /var/lib/mysql, ces valeurs ne seront pas prises en compte et n’auront aucun effet.

⚠️ Attention, la version de l’image est à adapter suivant la version 10.6 en cours de MariaDB.

5.1.2. Lancement via docker-composer

Si vous souhaitez utiliser docker-compose pour démarrer le conteneur de base de données, vous pouvez utiliser le fichier de configuration docker-compose.yml ci-dessous :

version : '3.8'
services:
mariadb:
image: mariadb:10.6.X
restart: always
volumes:
- "/var/lib/mysql:/var/lib/mysql"
ports :
- "3306:3306"
environment:
MYSQL_ROOT_PASSWORD: my-secret-pwd
MYSQL_DATABASE: lockself

Une fois le fichier de configuration récupéré sur le serveur host, vous pourrez démarrer le conteneur via la commande suivante :

docker-compose up -d --build
⚠️ Attention, la version de l’image est à adapter suivant la version 10.6 en cours de MariaDB.

 5.1.3. Lancement via docker-swarm

Si vous souhaitez utiliser docker-swarm pour démarrer le conteneur de base de données, vous pouvez utiliser le fichier de configuration yaml ci-dessous :

version: '3.7'

services:
mariadb:
image: mariadb:10.6.X
ports:
- target: 3306
published: 3306
protocol: tcp
mode: host
environment:
MYSQL_ROOT_PASSWORD: my-secret-pwd
MYSQL_DATABASE: lockself
volumes:
- "/var/lib/mysql:/var/lib/mysql"

Swarm peut s’utiliser de plusieurs façons que nous ne détaillerons pas dans cette procédure. Vous pourrez retrouver tous les détails concernant son fonctionnement sur son site officiel : https://docs.docker.com/engine/swarm/

⚠️ Attention, la version de l’image est à adapter suivant la version 10.6 en cours de MariaDB. Afin de pouvoir déployer via ce mécanisme, vous pouvez être amené à rajouter des options, tels que le network, le deploy etc.

5.2. Explications relatives à l'étape 5.1

5.2.1. Point obligatoire pour le bon fonctionnement de l'application

Afin d’obtenir une persistance des données, le montage d’un volume est nécessaire afin de partager le dossier /var/lib/mysql du conteneur (qui contient les datas de la db) avec le host.

Ce point de montage se fait via l’option -v ou volumes suivant le mode de lancement choisi.

A l’étape 5.1, nous utilisons le point de montage suivant : /var/lib/mysql:/var/lib/mysql

Optionnel : Dans le cas où le SELinux est activé sur les serveurs host, une modification des droits doit être effectuée sur les différents fichiers :

chcon -Rt svirt_sandbox_file_t /var/lib/mysql

Dans cet exemple, les données MariaDB qui sont stockées dans le conteneur dans le dossier /var/lib/mysql seront également stockées sur le host dans le dossier /var/lib/mysql.

5.2.2. Point facultatif

Vous pouvez si vous le souhaitez ajouter des volumes supplémentaires entre le serveur host et le conteneur. Deux points spécifiques ont été identifiés :

5.2.2.1. Ajout du support TLS

Vous avez la possibilité d’ajouter le support TLS sur le serveur de base de données (https://mariadb.com/kb/en/securing-connections-for-client-and-server/). Pour se faire, vous devrez monter un volume contenant les certificats utilisés par MariaDB, par exemple :

/home/user/lockself/certs:/etc/mysql/certificates

Dans cet exemple, les certificats contenus sur le host dans le dossier /home/user/certs seront disponibles dans le conteneur dans le dossier /etc/mysql/certificates. Il faudra adapter la configuration de MariaDB, comme nous allons l’évoquer dans le prochain point (5.2.2.2).

En activant ce support TLS, attention à ce que les serveurs applicatifs puissent truster le certificat.

5.2.2.2. Configuration spécifique de MariaDB

Vous avez également la possibilité de customiser la configuration de MariaDB, notamment si vous souhaitez activer le support TLS. Pour ajouter cette configuration, vous devrez monter un volume contenant le fichier de configuration custom, par exemple :

/home/user/lockself/mariadb-customer.cnf:/etc/mysql/conf.d/mariadb-customer.cnf

5.2.3. Pour en savoir plus sur les volumes

https://docs.docker.com/storage/volumes/

5.3. Action à réaliser sur le serveur de base de données – Étape 2

Cette étape est à réaliser sur le serveur de base de données une fois le conteneur MariaDB démarré, fin de préparer le script d’ajout d’utilisateur.

Pour cela, récupérez le script ci-dessous et modifier les valeurs suivantes :

  • PASSWORD – A remplacer par les mots de passe que vous souhaitez associer aux users.
  • IP – A remplacer par l’IP/Range des serveurs applicatifs. Attention à être sûr de l’IP de sortie qui sera utilisée. Suivant les architectures, les serveurs applicatifs peuvent sortir depuis l’IP du conteneur (généralement en 172.X) ou depuis l’IP du serveur host.
-- Create user www. It used by the application to read the db.
-- IP has to be modified with the IP/Range of the application servers.
-- PASSWORD has to be modified with the password you want to give to this user.
CREATE USER 'www'@'IP' IDENTIFIED BY 'PASSWORD';

-- Grant rights to the www user.
-- Replace IP with the IP/Range of the application servers.
GRANT SELECT,INSERT,UPDATE,DELETE ON lockself.* TO 'www'@'IP';

-- Create user lockself_migration. It used by the application to migrate the db.
-- IP has to be modified with the IP/Range of the application servers.
-- PASSWORD has to be modified with the password you want to give to this user.
CREATE USER 'lockself_migration'@'IP' IDENTIFIED BY 'PASSWORD';

-- Grant rights to the lockself_migration user.
-- Replace IP with the IP/Range of the application servers.
GRANT SELECT,INSERT,UPDATE,DELETE,ALTER,CREATE,DROP,INDEX ON lockself.* TO 'lockself_migration'@'IP';

Pour rappel, l’utilisateur root et la création de la base de données sont réalisés par les variables d’environnements lors du premier lancement du conteneur.

💡 Vous pouvez si vous le souhaitez créer d’autres utilisateurs pour vos besoins de backup, monitoring etc.

5.4. Action à réaliser sur le serveur de base de données – Étape 3

Une fois le script ci-dessus modifié et adapté à vos besoins, exécuter la commande ci-dessous afin de créer les utilisateurs dans la base de données :

docker exec -i mariadb sh -c 'exec mysql -uroot -pmy-secret-pwd' < create_user.sql

  • mariadb est à modifier avec le nom du conteneur choisi (nom choisi à l’étape 5.1)
  • my-secret-pwd est à modifier avec le mot de passe root
  • create_user.sql est à modifier par rapport au nom du fichier contenant le script SQL ci-dessus

6. Installation du second composant : L’application LockSelf

6.1. Préambule

Tout d’abord, il faut récupérer le package fourni par les équipes LockSelf et vérifier son intégrité. Ce package comprend :

  • L’image du conteneur : lockself-api-X.X.X.tar.gz
  • La signature de l’image du conteneur : lockself-api-X.X.X.tar.gz.sig
⚠️ Avant toutes opérations, vous devez vérifier la signature apposée sur l’image du conteneur.

6.2. Action à réaliser sur le serveur applicatif – Étape 1

La première étape consiste à créer une paire de clé RSA. Celle-ci sera utilisée par l’application LockSelf. Ces clés sont à stocker sur le serveur, nous nous en servirons en étape 6.5.

openssl genpkey -out private.pem -aes256 -algorithm rsa -pkeyopt rsa_keygen_bits:4096

Pour la passphrase demandée pendant l'execution de cette commande, nous préconisons une passphrase aléatoire de 32 caractères alphanumériques avec caractères spéciaux. Cette passphrase vous sera demandée en étape 6.3.

openssl pkey -in private.pem -out public.pem -pubout

La première commande permet la création de la clé privée RSA (4096 bits) et la chiffre en AES256 avec la passphrase spécifiée.

La seconde permet d’extraire la clé public associée.

6.3. Action à réaliser sur le serveur applicatif – Étape 2

Récupérez le script install_lockself.sh en annexe de document (13.1) sur le serveur et exécuter le. Plusieurs informations vous seront demandées. A la fin d’exécution du script, vous récupérerez un fichier nommé env qui nous servira à l’étape 6.5.

Le fichier d’environnement généré env contient notamment les salts de chiffrement et les variables relatives à votre infrastructure on-premises.

6.4. Avant le déploiement du conteneur

Avant le déploiement du conteneur, vérifiez que vous avez les informations suivantes disponibles sur le serveur web :

  • Le fichier env (par exemple dans : /home/user/lockself/env) généré par le script install_lockself.sh (Étape 6.3)

  • Dans un dossier (par exemple : /home/user/lockself/ssl/), les certificats SSL :

    • Le certificat suivi de la chaine de certification sous le nom : ssl-certificate.crt
    • La clé privée non chiffrée sous le nom : ssl-certificate.key
    • Seulement dans le cadre d'une connexion SSO :
      • Le certificat SANS la chaine de certification sous le nom : sp.crt
  • Dans un dossier (par exemple : /home/user/lockself/jwt/) la paire de clé RSA générée à l’étape 6.2 :

    • La clé privée sous le nom : private.pem
    • La clé publique sous le nom : public.pem
  • Un dossier qui servira à stocker les fichiers et qui les rendra permanent en cas de redémarrage du conteneur (par exemple : /home/user/lockself/files).

  • Optionnel : Dans le cas où le SELinux est activé sur les serveurs host, une modification des droits doit être effectuée sur les différents fichiers :
    • chcon -Rt svirt_sandbox_file_t /home/user/lockself/jwt
    • chcon -Rt svirt_sandbox_file_t /home/user/lockself/ssl
    • chcon -Rt svirt_sandbox_file_t /home/user/lockself/env
    • chcon -Rt svirt_sandbox_file_t /home/user/lockself/files

6.5. Action à réaliser sur le serveur applicatif – Étape 3

Charger l’image LockSelf sur le serveur web :

docker load --input lockself-api-X.X.X.tar.gz

Pour le déploiement du conteneur applicatif, trois possibilités. À vous de choisir laquelle vous souhaitez utiliser suivant les préconisations de l’entreprise.

6.5.1. Lancement manuel

docker run \
--name lockself-api-3 \
-v /home/user/lockself/jwt:/usr/local/var/www/html/config/jwt \
-v /home/user/lockself/ssl:/usr/local/etc/nginx/ssl \
-v /home/user/lockself/env:/usr/local/var/www/html/.env \
-v /home/user/lockself/files:/usr/local/var/www/html/var/glutton \
-v /home/user/lockself/ssl/sp.crt:/usr/local/var/www/html/vendor/onelogin/php-saml/certs/sp.crt \
-v /home/user/lockself/ssl/ssl-certificate.key:/usr/local/var/www/html/vendor/onelogin/php-saml/certs/sp.key \
-p 80:8080 \
-p 443:4443 \
-d lockself-api-v3:X.X.X
  • --name : correspond au nom du conteneur une fois créé
  • -v : correspond aux volumes montés
  • -p : permet à l’host de forward les requêtes sur le port 80 et 443 au conteneur
  • -d : permet au conteneur de se lancer en background
  • lockself-api-v3:X.X.X : correspond à la version de l'image LockSelf utilisée
⚠️ Attention à correctement adapter le tag de l’image, ainsi que les paths relatifs aux volumes. Les deux derniers points de montage sont à effectuer uniquement pour faire fonctionner une connexion SSO.

6.5.2. Lancement via docker-compose

Si vous souhaitez utiliser docker-compose pour démarrer le conteneur applicatif, vous pouvez utiliser le fichier de configuration docker-compose.yml ci-dessous :

version: '3.8'

services:
lockself-api-3:
image: lockself-api-v3:X.X.X
restart: always
volumes:
- "/home/user/lockself/jwt:/usr/local/var/www/html/config/jwt"
- "/home/user/lockself/ssl:/usr/local/etc/nginx/ssl"
- "/home/user/lockself/env:/usr/local/var/www/html/.env"
- "/home/user/lockself/files:/usr/local/var/www/html/var/glutton"
- "/home/user/lockself/ssl/sp.crt:/usr/local/var/www/html/vendor/onelogin/php-saml/certs/sp.crt"
- "/home/user/lockself/ssl/ssl-certificate.key:/usr/local/var/www/html/vendor/onelogin/php-saml/certs/sp.key"
ports :
- "80:8080"
- "443:4443"

Une fois le fichier de configuration récupéré sur le serveur host, vous pourrez démarrer le conteneur via la commande suivante :

docker-compose up -d --build
⚠️ Attention à correctement adapter le tag de l’image, ainsi que les paths relatifs aux volumes. Les deux derniers points de montage sont à effectuer uniquement pour faire fonctionner une connexion SSO.

6.5.3. Lancement via docker-swarm

Si vous souhaitez utiliser docker-swarm pour démarrer le conteneur de base de données, vous pouvez utiliser le fichier de configuration yaml ci-dessous :

version: '3.7'

services:
lockself-api-3:
image: lockself-api-v3:X.X.X
ports:
- target: 8080
published: 80
protocol: tcp
mode: host
- target: 4443
published: 443
protocol: tcp
mode: host
volumes:
- "/home/user/lockself/jwt:/usr/local/var/www/html/config/jwt"
- "/home/user/lockself/ssl:/usr/local/etc/nginx/ssl"
- "/home/user/lockself/env:/usr/local/var/www/html/.env"
- "/home/user/lockself/files:/usr/local/var/www/html/var/glutton"
- "/home/user/lockself/ssl/sp.crt:/usr/local/var/www/html/vendor/onelogin/php-saml/certs/sp.crt"
- "/home/user/lockself/ssl/ssl-certificate.key:/usr/local/var/www/html/vendor/onelogin/php-saml/certs/sp.key"

Swarm peut s’utiliser de plusieurs façons que nous ne détaillerons pas dans cette procédure. Vous pourrez retrouver tous les détails concernant son fonctionnement sur son site officiel : https://docs.docker.com/engine/swarm/

⚠️ Attention à correctement adapter le tag de l’image, ainsi que les paths relatifs aux volumes. Les deux derniers points de montage sont à effectuer uniquement pour faire fonctionner une connexion SSO. Vous pouvez également être amené à rajouter des options, tels que le network, le deploy etc.

Les migrations de base de données (incluant la création de la structure) seront faites automatiquement au lancement du conteneur. Vérifiez que ce dernier soit bien démarré en exécutant la commande : 

  • docker logs -f CONTAINER_ID

 

7. Créer le compte administrateur

Une fois l'infrastructure en place, vous aurez la possibilité de créer votre compte administrateur. Pour ce faire, rendez-vous sur l'URL ci-dessous et remplissez les informations demandées :

https://FQDN/external/users/validate-account/index.html?firstCo

Où FQDN est le nom de domaine que vous exploitez

Demandez la clé de licence à votre Responsable de Comptes.

 

8. Backup

Deux éléments sont importants à sauvegarder en lieu sûr une fois l’installation terminée :

  • Le fichier env généré à l'étape 6.3.
    • Ce fichier comporte les fichiers de configuration indispensable au bon fonctionnement de votre installation. Ces fichiers une fois générés ne pourront pas être régénérés à l’identique. Si vous veniez à perdre ceux-ci, les informations contenues dans la base de données deviendraient indéchiffrables.
  • La base de données

Nous recommandons d’appliquer un chiffrement (symétrique ou asymétrique) pour le backup de ces deux composants.

 

9. Update

Les updates vous sont communiquées par les équipes LockSelf et sont prévues à l’avance. Les mises à jour se font via l’envoi d’une nouvelle image Docker.

Comme pour le déploiement initial, les équipes LockSelf enverront le package de mise à jour. Ce package comprendra :

  • L’image du conteneur : lockself-api-X.X.X.tar.gz
  • La signature de l’image du conteneur : lockself-api-X.X.X.tar.gz.sig
⚠️ Avant toutes opérations, vous devez vérifier la signature apposée sur l’image du conteneur.

Le downtime sera de quelques minutes, le temps de reconstruire le conteneur (sauf dans le cas d’un environnement clusterisé).

Pour charger l’image LockSelf sur le serveur web : docker load --input lockself-api-X.X.X.tar.gz

Suivant le mode de lancement utilisé, adaptez la version de l’image par rapport à la version reçue et relancez la procédure.

Les migrations de base de données seront faites automatiquement au lancement du conteneur. Vérifiez que ce dernier soit bien redémarré en exécutant la commande : 

  • docker logs -f CONTAINER_ID

 

10. Optimiser l'espace disque

Après chaque mise à jour des conteneurs, vous pouvez si vous le souhaiter supprimer les anciennes images au fur et à mesure.

 

11. Mettre à jour le certificat SSL

Deux étapes sont nécessaires afin de mettre à jour le certificat SSL (pour la connexion HTTPS) sur votre installation :

  • Changer les certificats sur les serveurs applicatifs. Pour notre exemple, dans le dossier /home/user/lockself/ssl/), charger les nouvelles informations :

    • Le certificat suivi de la chaine de certification sous le nom : ssl-certificate.crt
    • La clé privée sous le nom : ssl-certificate.key
    • Seulement dans le cadre d'une connexion SSO :
      • Le certificat SANS la chaine de certification sous le nom : sp.crt
  • Relancer le conteneur suivant la méthode utilisée.

 

12. Interconnecter l'application en SSO

L'interconnexion de l'application LockSelf à une federation d'identité se fait via le protocol SAMLv2, par exemple avec des outils tels que ADFS, Azure SSO, Google et OpenId.

💡Consultez les articles correspondant pour connaître les étapes de création du connecteur avec les outils suivants :

Avant d'établir cette interconnexion, il faudra vérifier que l'IDP peut négocier des requêtes HTTPS en TLS 1.2 minimum. Les versions inférieures à TLS 1.2 ou les versions SSL sont désactivées sur le serveur web LockSelf pour raison de sécurité.

12.1. Traitement du fichier XML de metadata de l'IDP

Cette première étape consiste à récupérer le fichier de metadata issus de votre IDP et à l'insérer en base de données. Deux méthodes sont possibles :

12.1.1. En récupérant l'URL de votre fichier metadata

Traiter l'URL en appelant la méthode ci-dessous. Cette méthode renverra une chaine de caractère. Chaine de caractère qu'il faudra ajouter en base de données.

curl --location --request POST 'https://FQDN/saml2/xmls/remotes' \
--header 'Content-Type: application/json' \
--data-raw '{
"xmlMetadata": "URL/FederationMetadata.xml"
}'
  • Remplacer FQDN par le nom de domaine que vous exploitez.
  • Remplacer URL par l'URL correspondant au fichier XML metadata.

12.1.2. En récupérant directement le fichier metadata

Traiter l'URL en appelant la méthode ci-dessous. Cette méthode renverra une chaine de caractère. Chaine de caractère qu'il faudra ajouter en base de données.

curl --location --request POST 'https://FQDN/saml2/xmls' \
--form 'file=@/PATH_TO_THE_XML_FILE.xml'
  • Remplacer FQDN par le nom de domaine que vous exploitez.
  • Remplacer /PATH_TO_THE_XML_FILE par le path de votre device menant au fichier XML metadata.

12.2. Vérifier la sortie de l'étape 11.1.

Peu importe la méthode utilisée, vérifier que le retour de la requête est semblable à l'exemple suivant :

"{\"idp\":{\"entityId\":\"http:\/\/URL\",\"singleSignOnService\":{\"url\":\"https:\/\/URL\/\",\"binding\":\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\"},\"singleLogoutService\":{\"url\":\"https:\/\/URL\/\",\"binding\":\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\"},\"x509certMulti\":{\"signing\":[\"MIIC7DCCAdSgAwIBAgIQIhDWbDy5yotXXX7l0DANBgkqhkiG9w0BAQsFADAyMTAwLgYDVQQDEydBREZTIFNpZ25pbmcgLSBmcy5vdXRzY2FsZS5sb2Nrc2VsZi5jb20wHhcNMjAwNzEzMTMwNjI1WhcNMXXXXXzMTMwNjI1WjAyMTAwLgYDVQQDEydBREZTIFNpZ25pbmcgLSBmcy5vdXRzY2FsZS5sb2Nrc2VsZi5jb20wggEiMA0GCSqGSIb3DQEBXXXXAA4IBDwAwggEKAoIBAQCyOyLenWdnKT1pDihg32gmAVzy4YERZ+tM1049NCOyqGYlsRt1YWy5RB9jrkTuqXCUZbw7sqDFTQRLg5dU2Z5+gRn2TjPUcAyOtIq3XUN6ix7ktBGoW5axB\/Yst38MSUFpWhVLdi2klqK94kUR4ROHqTGX1OkIi3MnNkdGH\/3TJ9eA366XXXXXsaAJUPfklV4KIRrbS7XNVQJuPxapAeWlebh7BhAjgTfpMFqEX9DsHg3lQL3elv2860OuHAMp9Xvv1iGdZ1YEw4vUaoSKO8RWfovQERhn6genrzLpg6qb\/1G8o2lHUOm0xYBtGJXXXXXNBjdpB0glTwVkJxVqqBAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAFXyfnc4jfDXLhTRpNwmYOyDwiA+HwxKI7oByf18Tvi4Jm1c\/Q9\/uD7VbtmregX7rc5\/TCTSf4+MnWSqqbiRZ2vqY7hnKEywjP7cLJ9QC1DswhaYGttK8FM8ZmGkBFPWZlT8YvyGSUcPPcoNOb23xS+cY1cTaqf571s1n\/lyG371RkAyMeczIL+E87yHNoWD12KItx9aAeLDO3PK74nHHO8DQhj2IDRxu2IxUxUd2F0xFnLZdMNGl77Rjp\/xO6O23bdt773w0swp9jA++6ldPNf21+Cp9rlMe\/JmyW8\/58LyERvM7sL2C6MHlZVgo4Ye1yFBVz7jWiNBr930ACytCOs=\"],\"encryption\":[\"MIIC8jCCAdqgAwIBAgIQN50KWGirXXXXXasi41PDANBgkqhkiG9w0BAQsFADA1MTMwMQYDVQQDEypBREZTIEVuY3J5cHRpb24gLSBmcy5vdXRzY2FsZS5sb2Nrc2VsZi5jb20XXXXXXjAwNzEzMTMwNjI0WhcNMjEwNzEzMTMwNjI0WjA1MTMwMQYDVQQDEypBREZTIEVuY3J5cHRpb24gLSBmcy5vdXRzY2FsZS5sb2Nrc2VsZi5jb20XXXXXGCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCqiViZzgs+Lh7jSWbwMFgSrjTe3s7YeFP+U4qZkFg+Xlt07DgTAbwY\/k0pDitjKiPXaGjJxmYXvgf6sLdS2KvWy1nyOwEPvhr\/vRsUWuWynY4XXXXXy5XAbS9u\/Ppn0f3pwvo7SbsU0RlUqztSZU+\/hfK3R8QmHSFSUSphDmWSq7rh0+74c+wrK6nlcCvKP5XgFrrNHzmqRvpKMW1mQy1OHdfgIqlEa3oDNaIyEDgwqJ+uD9ZLBYaWbrg2FXcAMDQbxqf+d2vkWFx6dTDXdM4vQb6AuVLUXXXXXXXYYAqOqUFAXRGACDWJDME1itTKAC8BNJ9dYy09nxwW0FAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAGidNL50lv\/6wzYLvt0LubgRFpmhlXOVdNFehk8tOtZKbsIAJefRYrNrOjegGuzlcFrFe\/3JSGtu2m\/OpOYSCu3EL7mewB1ui59UdJlzOS5YPTA3uFEReS5hyAzHzjTYBaOdu+SRVX6ffV1pjUhY0SGfrptZCAkwPtJyP4iBJEbw1kupjbExWl8wEuvmwVN2\/PiP+erYoLHLAUnowO4oyLpMGXyB0KKvYIL6cHNGYX2AXiHpfDJTrrYTSQECrXlWs\/VfYTZTePnKxHZ2oHBFiQSwNznlSpDhduMkuIMPzOtqRHtJLzZ5anSrkfkw4RXyjgF3C6SpGf19uVEWw4ZQDwo=\"]}},\"sp\":{\"NameIDFormat\":\"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress\"}}"

Une fois la vérification faite, vous pouvez copier dans votre presse-papier la réponse.

12.3. Insérer la réponse en base de données

Connectez-vous sur votre base de données et executez la requête suivante :

INSERT INTO saml_configuration VALUES (1, 1, RESPONSE);

Avec notre exemple :

INSERT INTO saml_configuration VALUES (1, 1, "{\"idp\":{\"entityId\":\"http:\/\/URL\",\"singleSignOnService\":{\"url\":\"https:\/\/URL\/\",\"binding\":\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\"},\"singleLogoutService\":{\"url\":\"https:\/\/URL\/\",\"binding\":\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\"},\"x509certMulti\":{\"signing\":[\"MIIC7DCCAdSgAwIBAgIQIhDWbDy5yotXXX7l0DANBgkqhkiG9w0BAQsFADAyMTAwLgYDVQQDEydBREZTIFNpZ25pbmcgLSBmcy5vdXRzY2FsZS5sb2Nrc2VsZi5jb20wHhcNMjAwNzEzMTMwNjI1WhcNMXXXXXzMTMwNjI1WjAyMTAwLgYDVQQDEydBREZTIFNpZ25pbmcgLSBmcy5vdXRzY2FsZS5sb2Nrc2VsZi5jb20wggEiMA0GCSqGSIb3DQEBXXXXAA4IBDwAwggEKAoIBAQCyOyLenWdnKT1pDihg32gmAVzy4YERZ+tM1049NCOyqGYlsRt1YWy5RB9jrkTuqXCUZbw7sqDFTQRLg5dU2Z5+gRn2TjPUcAyOtIq3XUN6ix7ktBGoW5axB\/Yst38MSUFpWhVLdi2klqK94kUR4ROHqTGX1OkIi3MnNkdGH\/3TJ9eA366XXXXXsaAJUPfklV4KIRrbS7XNVQJuPxapAeWlebh7BhAjgTfpMFqEX9DsHg3lQL3elv2860OuHAMp9Xvv1iGdZ1YEw4vUaoSKO8RWfovQERhn6genrzLpg6qb\/1G8o2lHUOm0xYBtGJXXXXXNBjdpB0glTwVkJxVqqBAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAFXyfnc4jfDXLhTRpNwmYOyDwiA+HwxKI7oByf18Tvi4Jm1c\/Q9\/uD7VbtmregX7rc5\/TCTSf4+MnWSqqbiRZ2vqY7hnKEywjP7cLJ9QC1DswhaYGttK8FM8ZmGkBFPWZlT8YvyGSUcPPcoNOb23xS+cY1cTaqf571s1n\/lyG371RkAyMeczIL+E87yHNoWD12KItx9aAeLDO3PK74nHHO8DQhj2IDRxu2IxUxUd2F0xFnLZdMNGl77Rjp\/xO6O23bdt773w0swp9jA++6ldPNf21+Cp9rlMe\/JmyW8\/58LyERvM7sL2C6MHlZVgo4Ye1yFBVz7jWiNBr930ACytCOs=\"],\"encryption\":[\"MIIC8jCCAdqgAwIBAgIQN50KWGirXXXXXasi41PDANBgkqhkiG9w0BAQsFADA1MTMwMQYDVQQDEypBREZTIEVuY3J5cHRpb24gLSBmcy5vdXRzY2FsZS5sb2Nrc2VsZi5jb20XXXXXXjAwNzEzMTMwNjI0WhcNMjEwNzEzMTMwNjI0WjA1MTMwMQYDVQQDEypBREZTIEVuY3J5cHRpb24gLSBmcy5vdXRzY2FsZS5sb2Nrc2VsZi5jb20XXXXXGCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCqiViZzgs+Lh7jSWbwMFgSrjTe3s7YeFP+U4qZkFg+Xlt07DgTAbwY\/k0pDitjKiPXaGjJxmYXvgf6sLdS2KvWy1nyOwEPvhr\/vRsUWuWynY4XXXXXy5XAbS9u\/Ppn0f3pwvo7SbsU0RlUqztSZU+\/hfK3R8QmHSFSUSphDmWSq7rh0+74c+wrK6nlcCvKP5XgFrrNHzmqRvpKMW1mQy1OHdfgIqlEa3oDNaIyEDgwqJ+uD9ZLBYaWbrg2FXcAMDQbxqf+d2vkWFx6dTDXdM4vQb6AuVLUXXXXXXXYYAqOqUFAXRGACDWJDME1itTKAC8BNJ9dYy09nxwW0FAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAGidNL50lv\/6wzYLvt0LubgRFpmhlXOVdNFehk8tOtZKbsIAJefRYrNrOjegGuzlcFrFe\/3JSGtu2m\/OpOYSCu3EL7mewB1ui59UdJlzOS5YPTA3uFEReS5hyAzHzjTYBaOdu+SRVX6ffV1pjUhY0SGfrptZCAkwPtJyP4iBJEbw1kupjbExWl8wEuvmwVN2\/PiP+erYoLHLAUnowO4oyLpMGXyB0KKvYIL6cHNGYX2AXiHpfDJTrrYTSQECrXlWs\/VfYTZTePnKxHZ2oHBFiQSwNznlSpDhduMkuIMPzOtqRHtJLzZ5anSrkfkw4RXyjgF3C6SpGf19uVEWw4ZQDwo=\"]}},\"sp\":{\"NameIDFormat\":\"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress\"}}");

Vous pouvez vérifier le bon insert de la ligne avec la requête :

SELECT * FROM saml_configuration;

12.4. Récupérer les metadatas de l'application

Maintenant que tout est en place sur l'application, vous allez être en mesure de récupérer les metadatas de l'application. Ces metadatas contiennent toutes les informations relatives à la création du connecteur.

L'URL permettant la récupération des metadatas de l'application est : https://FQDN/saml2/metadata

12.5. Renvoi des claims

Une fois le connecteur créé côté IDP, vous allez devoir paramétrer l'envoi des claims suivantes : Seules les lignes sufixées par une * sont obligatoires. Les autres informations sont à préciser seulement dans des cas spécifiques (si vous souhaitez synchroniser les organisations et les groupes par exemple). 

  • L’email de l’utilisateur sous le nom: “mail” *
  • Le prénom de l’utilisateur sous le nom “firstname” *
  • Le nom de l’utilisateur sous le nom “lastname” *
  • Le uid (id unique) de l'utilisateur sous le nom "nni"
  • Les groupes de l'utilisateur sous le nom "groups"
  • L'id de l'organisation de l'utilisateur sous le nom "organizationId"
  • Le type de l'utilisateur sous le nom "type" : 0 si c'est un utilisateur interne - 1 si c'est un utilisateur externe
  • La date d'expiration de l'utilisateur sous le nom "expirationDate" avec la forme YYYYMMDD

Pour plus d'informations, vous pouvez vous référer à votre account manager.

12.5.1. Synchronisation des groupes

Si vous envoyez via la Fédération les groupes des utilisateurs et que vous voulez que ceux-ci soient synchronisés dans LockSelf, il vous faudra changer dans le fichier env le paramètre suivant : (attention à ce que la claim groups soit bien envoyée par la Fédération) :

intercoAd=0 par intercoAd=1

Si vous souhaitez ne pas récupérer l'entièreté des groupes de votre annuaire, vous pouvez choisir un prefix où seul les groupes ayant ce prefix seront récupérés par LockSelf. La variable suivante sera à remplacer dans le fichier env :

intercoAdPrefix='' par intercoAdPrefix='MY_PREFIX'

12.5.2. Import des organisations

Si vous souhaitez accéder au module d'import d'organisation, vous devrez modifier dans le fichier env la variable suivante :

importOrganization=0 par importOrganization=1

La fonctionnalité d'import d'organisation a la possibilité d'envoyer des emails aux administrateurs importés. Pour activer cette fonctionnalité d'envoi d'email automatique, vous pourrez adapter dans le fichier env la variable suivante :

importOrganizationSendEmail=0 par importOrganizationSendEmail=1

Avant d'utiliser cette fonctionnalité, renseignez-vous auprès de votre account manager.

12.5.3. Synchronisation des organisations

Si vous voulez que vos utilisateurs soient directement attachés aux bonnes organisations, vous devrez modifier dans le fichier env la variable suivante : (attention à ce que les claims organizationId et nni soient bien envoyées par la Fédération)

intercoAdOrganizations=0 par intercoAdOrganizations=1

Avant d'utiliser cette fonctionnalité, renseignez-vous auprès de votre account manager.

12.6. Vérifier la connexion

Si toutes les étapes ont été correctement effectuées, vous aurez la possibilité de faire une connexion depuis l'onglet SSO de l'application.

 

13. Annexes

Annexe 1 - install_lockself.sh

#!/bin/bash
# This script will configure your LockSelf installation
# It will create a env file. This file will be mount in your container.
# Maintener: LockSelf SAS <contact@lockself.com>

if [ -f $PWD/env ]
then
printf "You already have a LockSelf installation. Be careful to dont lose the '~/env' file. Without it, it will be impossible to access your datas. If you're sure to would reinstall LockSelf, delete the ~/env file and relaunch this script."
exit 1
fi

printf " _ _ _____ _ __ \n"
printf "| | | | / ____| | |/ _|\n"
printf "| | ___ ___| | _| (___ ___| | |_ \n"
printf "| | / _ \ / __| |/ /\___ \ / _ \ | _|\n"
printf "| |___| (_) | (__| < ____) | __/ | | \n"
printf "|______\___/ \___|_|\_\_____/ \___|_|_| \n\n"

printf "Welcome to the LockSelf's on-premises installation program\n"
printf "First, we will configure the database informations (applicative account - step 5.3):\n\n"

while [[ $dbHost == "" ]]
do
printf "DB Host: > " && read dbHost
done
while [[ $dbName == "" ]]
do
printf "DB Name: > " && read dbName
done
while [[ $dbUser == "" ]]
do
printf "DB User (applicative account): > " && read dbUser
done
while [[ $dbPassword == "" ]]
do
printf "DB Password (applicative account): > " && read -s dbPassword
done
while [[ $dbPassword2 == "" ]]
do
printf "\nVerify your DB Password (applicative account): > " && read -s dbPassword2
done
if [[ $dbPassword != $dbPassword2 ]]
then
printf "\nThe two passwords are not corresponding. Please relaunch the installation."
exit 1
fi
printf "\n\nNow, lets configure the database informations for the user lockself_migration: (step 5.3)\n"
while [[ $dbPasswordPhinx == "" ]]
do
printf "DB Password lockself_migration: > " && read -s dbPasswordPhinx
done
while [[ $dbPassword2Phinx == "" ]]
do
printf "\nVerify your DB Password lockself_migration: > " && read -s dbPassword2Phinx
done
if [[ $dbPasswordPhinx != $dbPassword2Phinx ]]
then
printf "\nThe two passwords are not corresponding. Please relaunch the installation."
exit 1
fi
printf "\n\nPlease now enter the passphrase choosen for the JWT: (step 6.2)\n"
while [[ $jwtPassphrase == "" ]]
do
printf "Write your JWT Passphrase: > " && read -s jwtPassphrase
done
while [[ $jwtPassphrase2 == "" ]]
do
printf "\nVerify your JWT Passphrase: > " && read -s jwtPassphrase2
done
if [[ $jwtPassphrase != $jwtPassphrase2 ]]
then
printf "The two passwords are not corresponding. Please relaunch the installation."
exit 1
fi
printf "\n\nLet's configure the SMTP connexion (it will be used to send the system email):\n"
while [[ $smtpHost == "" ]]
do
printf "SMTP Host: > " && read smtpHost
done
while [[ $smtpPort == "" ]]
do
printf "SMTP Port: > " && read smtpPort
done
while [[ $smtpAuth == "" ]]
do
printf "SMTP Auth: (true or false) > " && read smtpAuth
done
if [ $smtpAuth == "true" ]
then
while [[ $smtpUsername == "" ]]
do
printf "SMTP Username: > " && read smtpUsername
done
while [[ $smtpPassword == "" ]]
do
printf "SMTP Password: > " && read smtpPassword
done
else
smtpUsername=""
smtpPassword=""
fi
while [[ $smtpSsl == "" ]]
do
printf "SMTP SSL: (ssl or tls or null) > " && read smtpSsl
done
if [ $smtpSsl == "null" ]
then
smtpSsl=""
fi
while [[ $smtpNoReply == "" ]]
do
printf "No-reply address: (ex: no-reply@company.com) > " && read smtpNoReply
done
printf `date`
printf "\nSMTP configuration terminated\n"
printf "\n\nLast thing, specify the domain you want to use:"
while [[ $domain == "" ]]
do
printf "\nDomain: (ex: lockself.company.com) > " && read domain
done

/bin/cat <<EOF > $PWD/env
###> symfony/framework-bundle ###
APP_ENV=prod
APP_DEBUG=0
APP_SECRET=62ab7ba420f13ef7f912d270c2a40ee0
###< symfony/framework-bundle ###

###> lexik/jwt-authentication-bundle ###
JWT_SECRET_KEY=%kernel.project_dir%/config/jwt/private.pem
JWT_PUBLIC_KEY=%kernel.project_dir%/config/jwt/public.pem
JWT_PASSPHRASE="$jwtPassphrase"
JWT_TTL=604800
###< lexik/jwt-authentication-bundle ###

###> doctrine/doctrine-bundle ###
DATABASE_URL='mysql://$dbUser:$dbPassword@$dbHost:3306/$dbName'
###< doctrine/doctrine-bundle ###

###> robmorgan/phinx ###
PHINX_USER='lockself_migration'
PHINX_PASSWORD='$dbPasswordPhinx'
PHINX_HOST='$dbHost'
PHINX_PORT='3306'
PHINX_DB_NAME='$dbName'
###< robmorgan/phinx ###

###> LockSelf ###
debug=0
domain=$domain
saltPassword1="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltPassword2="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltPin1="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltPin2="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
keyPin="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 32 ; echo)"
ivPin="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltApiHash1="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltApiHash2="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
sampleHash="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
blockConnexionInSecond=900
pinLength=6
saltTransfer1="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltTransfer2="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltTransferProtectedEmail1="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltTransferProtectedEmail2="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltDeposit1="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltDeposit2="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltMail1="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltMail2="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
bucket=
providerAccessKey=
providerSecretKey=
providerRegion=
providerEndpoint=
provider=LOCAL
depositTokenTime=15
noReplyEmail='$smtpNoReply'
colorBtn='#39499b'
companyName="LockSelf"
nameDepositBox="Access to a deposit box"
newFileDeposit="New file uploaded"
newTransfer="New protected file received"
apiVersion=3
intercoAd=0
intercoAdPrefix=''
importOrganization=0
importOrganizationSendEmail=0
intercoAdOrganizations=0
###< LockSelf ###

###> symfony/swiftmailer-bundle ###
MAILER_URL=smtp://$smtpHost:$smtpPort?encryption=$smtpSsl&username=$smtpUsername&password=$smtpPassword
###< symfony/swiftmailer-bundle ###

###> ovh/ovh ###
smsApplicationKey=
smsApplicationSecret=
smsConsumerKey=
smsEndpoint=
###< ovh/ovh ###

###> knplabs/knp-snappy-bundle ###
WKHTMLTOPDF_PATH=/usr/local/bin/wkhtmltopdf
WKHTMLTOIMAGE_PATH=/usr/local/bin/wkhtmltoimage
###< knplabs/knp-snappy-bundle ###

EOF

printf "\n\nStep 6.3 terminated. If you want to review your config file, like your smtp or database configuration, you can check the 'env' file which is created by this script or you can continue the deployment guide."

 

14. Troubleshooting

Pour tout problème, il va falloir vous diriger vers les logs systèmes et applicatifs qui vous aiguillerons pour trouver les solutions.
Concernant les logs systèmes, ils sont accessibles via la commande :
docker logs -f CONTAINER_ID
En ce qui concerne les logs applicatifs, vous pourrez les trouver via les commandes :
1. docker exec -it CONTAINER_ID sh
2. cat var/log/prod.error-YYYY-MM-DD
Pour toutes questions envoyées au support LockSelf, merci de nous faire parvenir le résultat de ces logs en amont.
 

15. Changer le nom de domaine

Si vous souhaitez changer le nom de domaine de votre installation LockSelf, vous devrez suivre la procédure suivante : 

  • Relier le nouveau nom de domaine à l'IP de votre serveur applicatif
  • Dans le fichier "env", modifier la variable "domain" par le nouveau domaine que vous souhaitez exploiter
  • Dans le dossier comportant les certificats SSL (par exemple : /home/user/lockself/ssl/) :

    • Modifier le certificat suivi de la chaine de certification sous le nom : ssl-certificate.crt
    • Modifier la clé privée non chiffrée sous le nom : ssl-certificate.key
    • Seulement dans le cadre d'une connexion SSO :
      • Modifier le certificat SANS la chaine de certification sous le nom : sp.crt
  • Redémarrer le conteneur applicatif

Mise à jour