From eca0e103015fc0917d0c0cc6a1c0cdf1f09df475 Mon Sep 17 00:00:00 2001 From: "s.naidenov" Date: Fri, 6 Dec 2024 17:42:59 +0700 Subject: [PATCH] DEV-416 --- README.md | 289 +++---------------------------------------- README.ru.md | 338 ++------------------------------------------------- 2 files changed, 28 insertions(+), 599 deletions(-) diff --git a/README.md b/README.md index cf7491c..863b091 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,28 @@ + + [![License](https://img.shields.io/badge/license-view-orange)](LICENSE.md) -# multifactor-ldap-adapter +# Multifactor LDAP adapter _Also available in other languages: [Русский](README.ru.md)_ +## What is MultiFactor Ldap Adapter? + **MultiFactor Ldap Adapter** is a LDAP proxy server for Linux. It allows you to quickly add multifactor authentication to your applications with LDAP authentication. The component is a part of MultiFactor 2FA hybrid solution. It is available with the source code and distributed for free. - * Source code -* Build - -Windows version of the component is available in MultiFactor.Ldap.Adapter repository. - -See knowledge base for additional guidance on integrating 2FA through LDAP into your infrastructure. +* Releases ## Table of Contents -- [Overview](#overview) - - [Component Features](#component-features) - - [Use Cases](#use-cases) -- [Prerequisites](#prerequisites) -- [Installation](#installation) - - [Dependencies Installation](#dependencies-installation) - - [CentOS 7](#centos-7) - - [CentOS 8](#centos-8) - - [Ubuntu 18.04](#ubuntu-1804) - - [Debian 10](#debian-10) - - [Component Installation](#component-installation) -- [Configuration](#configuration) - - [General Parameters](#general-parameters) -- [Start-Up](#start-up) -- [Logs](#logs) -- [Certificate for TLS encryption](#certificate-for-tls-encryption) -- [Uninstallation](#uninstallation) - - [Uninstall .NET Core](#uninstall-net-core) - - [CentOS 7](#centos-7-1) - - [CentOS 8](#centos-8-1) - - [Ubuntu 18.04](#ubuntu-1804-1) - - [Debian 10](#debian-10-1) - - [Uninstall Component](#uninstall-component) +- [What is MultiFactor Ldap Adapter](#what-is-multiFactor-ldap-adapter) +- [Component Features](#component-features) +- [Use Cases](#use-cases) +- [Installation and configuration](#installation-and-configuration) - [License](#license) -## Overview - -### Component Features +## Component Features Key functionality: @@ -58,253 +36,16 @@ Key features: - Bypassing requests from service accounts (Bind DN) without the second factor; - Logging to Syslog server or SIEM system. -### Use Cases +## Use Cases Use LDAP Adapter Component to implement the following scenarios: * Add a second authentication factor to applications connected to Active Directory or other LDAP directories; * Enable traffic encryption for applications that do not support encrypted TLS connection. -## Prerequisites - -- Component is installed on a Linux server, tested on CentOS, Ubuntu, Debian; -- Minimum server requirements: 1 CPU, 2 GB RAM, 8 GB HDD (to run the OS and adapter for 100 simultaneous connections — approximately 1500 users); -- TCP ports 389 (LDAP) and 636 (LDAPS) must be open on the server to receive requests from clients; -- The server with the component installed needs access to ```api.multifactor.ru``` via TCP port 443 (TLS) directly or via HTTP proxy; -- To interact with Active Directory, the component needs access to the domain server via TCP port 389 (LDAP) or 636 (LDAPS); - -## Installation - -### Dependencies Installation - -The component uses the .NET 8 runtime environment, which is free, open-source, developed by Microsoft and the open-source community. The runtime environment does not impose any restrictions on its use. - -To install, run the commands: - -#### CentOS 7 - -```shell -$ sudo rpm -Uvh https://packages.microsoft.com/config/centos/7/packages-microsoft-prod.rpm -$ sudo yum install aspnetcore-runtime-8.0 -``` -https://docs.microsoft.com/ru-ru/dotnet/core/install/linux-centos - - -#### CentOS 8 - -> ⚠️ **Warning** -> CentOS Linux 8 reached an early End Of Life (EOL) on December 31st, 2021. -> For more information, see the official CentOS Linux EOL page. -> Because of this, .NET isn't supported on CentOS Linux 8. - -For more information see this page. -See also: install the .NET on CentOS Stream. - -#### Ubuntu 18.04 - -```shell -$ wget https://packages.microsoft.com/config/ubuntu/18.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb -$ sudo dpkg -i packages-microsoft-prod.deb - -$ sudo apt-get update; \ - sudo apt-get install -y apt-transport-https && \ - sudo apt-get update && \ - sudo apt-get install -y aspnetcore-runtime-8.0 -``` - -https://docs.microsoft.com/ru-ru/dotnet/core/install/linux-ubuntu - -#### Debian 10 - -```shell -$ wget https://packages.microsoft.com/config/debian/10/packages-microsoft-prod.deb -O packages-microsoft-prod.deb -$ sudo dpkg -i packages-microsoft-prod.deb - -$ sudo apt-get update; \ - sudo apt-get install -y apt-transport-https && \ - sudo apt-get update && \ - sudo apt-get install -y aspnetcore-runtime-8.0 -``` - -https://docs.microsoft.com/ru-ru/dotnet/core/install/linux-debian - -### Component Installation - -Create a folder, download and unzip the current version of the component from GitHub: - -```shell -$ sudo mkdir /opt/multifactor /opt/multifactor/ldap /opt/multifactor/ldap/tls /opt/multifactor/ldap/logs -$ sudo wget https://github.com/MultifactorLab/multifactor-ldap-adapter/releases/latest/download/release_linux_x64.zip -$ sudo unzip release_linux_x64.zip -d /opt/multifactor/ldap -``` - -Create a system user mfa and give it rights to the application: -```shell -$ sudo useradd -r mfa -$ sudo chown -R mfa: /opt/multifactor/ldap/ -$ sudo chmod -R 700 /opt/multifactor/ldap/ -``` -Create a service -```shell -$ sudo vi /etc/systemd/system/multifactor-ldap.service -``` - -```shell -[Unit] -Description=Multifactor Ldap Adapter - -[Service] -WorkingDirectory=/opt/multifactor/ldap/ -ExecStart=/usr/bin/dotnet /opt/multifactor/ldap/multifactor-ldap-adapter.dll -Restart=always -# Restart service after 10 seconds if the service crashes: -RestartSec=10 -KillSignal=SIGINT -SyslogIdentifier=multifactor-ldap -User=mfa -Environment=ASPNETCORE_ENVIRONMENT=Production -Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false - -# How many seconds to wait for the app to shut down after it receives the initial interrupt signal. -# If the app doesn't shut down in this period, SIGKILL is issued to terminate the app. -# The default timeout for most distributions is 90 seconds. -TimeoutStopSec=30 - -# give the executed process the CAP_NET_BIND_SERVICE capability. This capability allows the process to bind to well known ports. -AmbientCapabilities=CAP_NET_BIND_SERVICE - -[Install] -WantedBy=multi-user.target -``` - -Enable autorun: -```shell -$ sudo systemctl enable multifactor-ldap -``` -## Configuration - -The component's parameters are stored in ```/opt/multifactor/ldap/multifactor-ldap-adapter.dll.config``` in XML format. - -### General Parameters - -```xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -``` - -## Start-Up - -After configuring the configuration, run the component: -```shell -$ sudo systemctl start multifactor-ldap -``` -You can check the status with the command: - -```shell -$ sudo systemctl status multifactor-ldap -``` - -## Logs - -The logs of the component are located in the ```/opt/multifactor/ldap/logs``` folder as well as in the system log. - -## Certificate for TLS Encryption - -If the LDAPS scheme is enabled, the adapter creates a self-signed SSL certificate the first time it starts up, and saves it in the /tls folder in pfx format without a password. -This certificate will be used for server authentication and traffic encryption. You can replace it with your own certificate if necessary. - -## Uninstallation - -### Uninstall .NET Core - -To view a list of SDK versions and the .NET Core runtimes installed on your machine use the command: - -```shell -dotnet --info -``` - -Next, run the commands: - -#### CentOS 7 - -```shell -$ sudo yum remove aspnetcore-runtime-8.0 -``` - -#### CentOS 8 - -```shell -$ sudo dnf remove aspnetcore-runtime-8.0 -``` - -#### Ubuntu 18.04 - -```shell -$ sudo apt-get remove aspnetcore-runtime-8.0 -``` - -#### Debian 10 - -```shell -$ sudo apt-get remove aspnetcore-runtime-8.0 -``` - -### Uninstall Component - -Stop the ``multifactor-ldap`` service, remove it from the autorun and delete the unit configuration file: - -```shell -$ sudo systemctl stop multifactor-ldap -$ sudo systemctl disable multifactor-ldap -$ sudo rm /etc/systemd/system/multifactor-ldap.service -``` - -Reload the systemd settings by scanning the system for changed units: - -```shell -$ sudo systemctl daemon-reload -``` - -Delete the adapter files and system user ```mfa```: - -```shell -$ sudo rm -rf /opt/multifactor/ldap/ -$ sudo userdel -r mfa -``` +## Installation and configuration +See [knowledge base](https://multifactor.pro/docs/ldap-adapter/linux/) for information about configuration, launch and an additional guidance. ## License -Please note, the [license](LICENSE.md) does not entitle you to modify the source code of the Component or create derivative products based on it. The source code is provided as-is for evaluation purposes. +Please note, the [license](LICENSE.md) does not entitle you to modify the source code of the Component or create derivative products based on it. The source code is provided as-is for evaluation purposes. \ No newline at end of file diff --git a/README.ru.md b/README.ru.md index ca8cf51..87aed44 100644 --- a/README.ru.md +++ b/README.ru.md @@ -1,54 +1,27 @@ + [![Лицензия](https://img.shields.io/badge/license-view-orange)](LICENSE.ru.md) -# multifactor-ldap-adapter +# MultiFactor LDAP Adapter _Also available in other languages: [English](README.md)_ +## Что такое MultiFactor LDAP Adapter? **MultiFactor Ldap Adapter** — программный компонент, LDAP proxy сервер для Linux. Используется для двухфакторной аутентификации пользователей в приложениях с LDAP аутентификацией. Компонент является частью гибридного 2FA решения сервиса MultiFactor. Компонент доступен вместе с исходным кодом, распространяется бесплатно. * Исходный код -* Сборка - -Windows-версия компонента доступна в репозитории MultiFactor.Ldap.Adapter. - -Дополнительные инструкции по интеграции 2FA в инфраструктуру доступны в документации. +* Релизы ## Содержание - -- [Общие сведения](#общие-сведения) - - [Функции компонента](#функции-компонента) - - [Сценарии использования](#сценарии-использования) -- [Требования для установки компонента](#требования-для-установки-компонента) -- [Установка](#установка) - - [Установка зависимостей](#установка-зависимостей) - - [CentOS 7](#centos-7) - - [CentOS 8](#centos-8) - - [Ubuntu 18.04](#ubuntu-1804) - - [Debian 10](#debian-10) - - [Astra Linux Орёл](#astra-linux-орёл) - - [Astra Linux Смоленск](#astra-linux-смоленск) - - [Установка компонента](#установка-компонента) -- [Конфигурация](#конфигурация) - - [Общие параметры](#общие-параметры) -- [Запуск компонента](#запуск-компонента) -- [Журналы](#журналы) -- [Сертификат для TLS шифрования](#сертификат-для-tls-шифрования) -- [Удаление компонента](#удаление-компонента) - - [Удаление .NET Core](#удаление-net-core) - - [CentOS 7](#centos-7-1) - - [CentOS 8](#centos-8-1) - - [Ubuntu 18.04](#ubuntu-1804-1) - - [Debian 10](#debian-10-1) - - [Astra Linux Орёл](#astra-linux-орёл-1) - - [Astra Linux Смоленск](#astra-linux-смоленск-1) - - [Удаление адаптера](#удаление-адаптера) +- [Что такое MultiFactor LDAP Adapter?](#что-такое-multiFactor-ldap-adapter) +- [Функции компонента](#функции-компонента) +- [Сценарии использования](#сценарии-использования) +- [Установка и конфигурация](#установка-и-конфигурация) - [Лицензия](#лицензия) -## Общие сведения -### Функции компонента +## Функции компонента Ключевые функции: @@ -62,301 +35,16 @@ Windows-версия компонента доступна в репозитор - пропуск запросов от сервисных учетных записей (Bind DN) без второго фактора; - запись журналов в Syslog сервер или SIEM систему. -### Сценарии использования +## Сценарии использования С помощью компонента можно реализовать следующие сценарии: * Добавить второй фактор аутентификации в приложения, подключенные к Active Directory или другим LDAP каталогам; * Включить шифрование трафика для приложений, которые не поддерживают подключение по TLS протоколу. -## Требования для установки компонента - -- Компонент устанавливается на Linux сервер, протестирован на CentOS, Ubuntu, Debian, Astra Linux; -- Минимальные требования для сервера: 1 CPU, 2 GB RAM, 8 GB HDD (обеспечивают работу ОС и адаптера для 100 одновременных подключений — примерно 1500 пользователей); -- На сервере должны быть открыты TCP порты 389 (LDAP) и 636 (LDAPS) для приема запросов от клиентов; -- Серверу с установленным компонентом необходим доступ к хосту api.multifactor.ru по TCP порту 443 (TLS) напрямую или через HTTP proxy; -- Для взаимодействия с Active Directory, компоненту нужен доступ к серверу домена по TCP порту 389 (LDAP) или 636 (LDAPS); - -## Установка - -### Установка зависимостей - -Компонент использует среду выполнения .NET 8 runtime, которая является бесплатной, открытой, разрабатывается компанией Microsoft и Open-Source сообществом. Среда выполнения не накладывает никаких ограничений на использование. - -Для установки выполните команды: - -#### CentOS 7 - -```shell -$ sudo rpm -Uvh https://packages.microsoft.com/config/centos/7/packages-microsoft-prod.rpm -$ sudo yum install aspnetcore-runtime-8.0 -``` -https://docs.microsoft.com/ru-ru/dotnet/core/install/linux-centos - -#### CentOS 8 - -> ⚠️ **Warning** -> CentOS Linux 8 достигла раннего окончания жизни (EOL) 31 декабря 2021 года. -> Дополнительные сведения см. на официальной странице EOL Для CentOS Linux. -> Из-за этого .NET не поддерживается в CentOS Linux 8. - -Дополнительную информацию см. на странице. -См. также: установка .NET на CentOS Stream. - -#### Ubuntu 18.04 - -```shell -$ wget https://packages.microsoft.com/config/ubuntu/18.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb -$ sudo dpkg -i packages-microsoft-prod.deb - -$ sudo apt-get update; \ - sudo apt-get install -y apt-transport-https && \ - sudo apt-get update && \ - sudo apt-get install -y aspnetcore-runtime-8.0 -``` -https://docs.microsoft.com/ru-ru/dotnet/core/install/linux-ubuntu - -#### Debian 10 - -```shell -$ wget https://packages.microsoft.com/config/debian/10/packages-microsoft-prod.deb -O packages-microsoft-prod.deb -$ sudo dpkg -i packages-microsoft-prod.deb - -$ sudo apt-get update; \ - sudo apt-get install -y apt-transport-https && \ - sudo apt-get update && \ - sudo apt-get install -y aspnetcore-runtime-8.0 -``` -https://docs.microsoft.com/ru-ru/dotnet/core/install/linux-debian - -#### Astra Linux Орёл - -```shell -$ sudo apt install ca-certificates - -$ wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.asc.gpg -$ sudo mv microsoft.asc.gpg /etc/apt/trusted.gpg.d/ -$ wget -q https://packages.microsoft.com/config/debian/9/prod.list -$ sudo mv prod.list /etc/apt/sources.list.d/microsoft-prod.list -$ sudo chown root:root /etc/apt/trusted.gpg.d/microsoft.asc.gpg -$ sudo chown root:root /etc/apt/sources.list.d/microsoft-prod.list - -$ echo deb https://download.astralinux.ru/astra/current/orel/repository/ orel non-free main contrib | sudo tee -a /etc/apt/sources.list - -$ sudo apt-get update -$ sudo apt-get install dotnet-sdk-8.0 -``` -Инструкция применима к Astra Linux Common Edition (релиз Орёл) и Special Edition (релиз Смоленск) с выключенным режимом замкнутой программной среды (ЗПС). -https://wiki.astralinux.ru/pages/viewpage.action?pageId=41192241#id-Смоленск1.6:УстановкаMS.NetCoreиMSVisualStudioCode-Загрузкаиустановкапакетов.NetCore - -#### Astra Linux Смоленск - -```shell -$ sudo apt install ca-certificates -$ wget https://multifactor.ru/repo/dotnet+aspnetcore_amd64_signed.tar.gz && \ - wget https://multifactor.ru/repo/multifactor_pub.key -$ sudo cp multifactor_pub.key /etc/digisg/keys/ && \ - sudo cp multifactor_pub.key /etc/digsig/xattr_keys/ && \ - sudo rm multifactor_pub.key -$ sudo update-initramfs -u -k all -$ tar -xf dotnet+aspnetcore_amd64_signed.tar.gz -$ cd dotnet+aspnetcore_amd64_signed -$ sudo dpkg -i *.deb -``` -Инструкция применима к Astra Linux Special Edition (релиз Смоленск) в режиме замкнутой программной среды (ЗПС). - -### Установка компонента - -Создайте папку, скачайте и распакуйте актуальную версию компонента из GitHub: - -```shell -$ sudo mkdir /opt/multifactor /opt/multifactor/ldap /opt/multifactor/ldap/tls /opt/multifactor/ldap/logs -$ sudo wget https://github.com/MultifactorLab/multifactor-ldap-adapter/releases/latest/download/release_linux_x64.zip -$ sudo unzip release_linux_x64.zip -d /opt/multifactor/ldap -``` - -Создайте системного пользователя mfa и дайте ему права на приложение: -```shell -$ sudo useradd -r mfa -$ sudo chown -R mfa: /opt/multifactor/ldap/ -$ sudo chmod -R 700 /opt/multifactor/ldap/ -``` -Создайте службу -```shell -$ sudo vi /etc/systemd/system/multifactor-ldap.service -``` - -```shell -[Unit] -Description=Multifactor Ldap Adapter - -[Service] -WorkingDirectory=/opt/multifactor/ldap/ -ExecStart=/usr/bin/dotnet /opt/multifactor/ldap/multifactor-ldap-adapter.dll -Restart=always -# Restart service after 10 seconds if the service crashes: -RestartSec=10 -KillSignal=SIGINT -SyslogIdentifier=multifactor-ldap -User=mfa -Environment=ASPNETCORE_ENVIRONMENT=Production -Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false - -# How many seconds to wait for the app to shut down after it receives the initial interrupt signal. -# If the app doesn't shut down in this period, SIGKILL is issued to terminate the app. -# The default timeout for most distributions is 90 seconds. -TimeoutStopSec=30 - -# give the executed process the CAP_NET_BIND_SERVICE capability. This capability allows the process to bind to well known ports. -AmbientCapabilities=CAP_NET_BIND_SERVICE - -[Install] -WantedBy=multi-user.target -``` - -Включите автозапуск: -```shell -$ sudo systemctl enable multifactor-ldap -``` - -## Конфигурация - -Параметры работы компонента хранятся в файле ```/opt/multifactor/ldap/multifactor-ldap-adapter.dll.config``` в формате XML. - -### Общие параметры - -```xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -``` - -## Запуск компонента - -После настройки конфигурации запустите компонент: -```shell -$ sudo systemctl start multifactor-ldap -``` -Статус можно проверить командой: - -```shell -$ sudo systemctl status multifactor-ldap -``` - -## Журналы - -Журналы работы компонента находятся в папке ```/opt/multifactor/ldap/logs```, а также в системном журнале. - -## Сертификат для TLS шифрования - -Если включена схема LDAPS, адаптер при первом запуске создаст самоподписанный SSL сертификат и сохранит его в папке /tls в формате pfx без пароля. -Этот сертификат будет использоваться для аутентификации сервера и шифрования трафика. Вы можете заменить его на ваш сертификат при необходимости. - -## Удаление компонента - -### Удаление .NET Core - -Для просмотра списка установленных на вашей машине версий SDK и сред выполнения .NET Core используйте команду: - -```shell -dotnet --info -``` - -Далее, выполните команды: - -#### CentOS 7 - -```shell -$ sudo yum remove aspnetcore-runtime-8.0 -``` - -#### CentOS 8 - -```shell -$ sudo dnf remove aspnetcore-runtime-8.0 -``` - -#### Ubuntu 18.04 - -```shell -$ sudo apt-get remove aspnetcore-runtime-8.0 -``` - -#### Debian 10 - -```shell -$ sudo apt-get remove aspnetcore-runtime-8.0 -``` - -#### Astra Linux Орёл - -```shell -$ sudo apt-get remove dotnet-sdk-8.0 -``` - -#### Astra Linux Смоленск - -```shell -$ sudo apt purge dotnet-* aspnetcore-* -``` - -### Удаление адаптера - -Остановите службу ```multifactor-ldap```, удалите её из автозапуска и удалите конфигурационный файл юнита: - -```shell -$ sudo systemctl stop multifactor-ldap -$ sudo systemctl disable multifactor-ldap -$ sudo rm /etc/systemd/system/multifactor-ldap.service -``` - -Перезагрузите настройки systemd, просканировав систему на наличие изменённых юнитов: - -```shell -$ sudo systemctl daemon-reload -``` - -Удалите файлы адаптера и системного пользователя ```mfa```: - -```shell -$ sudo rm -rf /opt/multifactor/ldap/ -$ sudo userdel -r mfa -``` +## Установка и конфигурация +Информацию о настройке, запуске и дополнительные рекомендации смотрите в [документации](https://multifactor.ru/docs/ldap-adapter/linux/). ## Лицензия -Обратите внимание на [лицензию](LICENSE.ru.md). Она не дает вам право вносить изменения в исходный код Компонента и создавать производные продукты на его основе. Исходный код предоставляется в ознакомительных целях. +Обратите внимание на [лицензию](LICENSE.ru.md). Она не дает вам право вносить изменения в исходный код Компонента и создавать производные продукты на его основе. Исходный код предоставляется в ознакомительных целях. \ No newline at end of file