Портал документации Рутокен

Page tree

Для работы серверных компонентов Rutoken KeyBox на ОС Linux настройте веб-сервер Nginx в качестве обратного прокси-сервера:

  1. Установите веб-сервер.
  2. Установите SSL/TLS-сертификат.
  3. Настройте конфигурационный файл.

RHEL-based

Установка веб-сервера

Для установки Nginx должен быть подключен и настроен репозиторий пакетов nginx. Если это не было сделано автоматически, добавьте репозиторий вручную.

  1. Установите пакеты, необходимые для подключения yum-репозитория:

    sudo yum install yum-utils
     

  2. Для подключения yum-репозитория создайте файл с именем/etc/yum.repos.d/nginx.repoсо следующим содержимым:

    [nginx-stable]
name=nginx stable repo
baseurl=http://nginx.org/packages/centos/$releasever/$basearch/
gpgcheck=1
enabled=1
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true

[nginx-mainline]
name=nginx mainline repo
baseurl=http://nginx.org/packages/mainline/centos/$releasever/$basearch/
gpgcheck=1
enabled=0
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true
     

  3. Выполните следующую команду:

    sudo yum install nginx
     

В случае запроса подтверждения GPG-ключа проверьте, что отпечаток ключа совпадает с 573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62.

Документация по установке на прочие ОС доступна на портале NGINX.

Установка TLS-сертификата

Установите TLS-сертификат на веб-сервер. 

  1. Скопируйте файлы сертификата и ключа в папку, которая указана в файле конфигурации nginx:

    sudo cp ./SSL.crt /etc/ssl/certs/
sudo cp ./SSL.key /etc/ssl/private/
     

  2. Добавьте сертификат корневого УЦ в доверенные на рабочей станции с установленным nginx.

    sudo cp ./ca.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust extract
     
  3. Сделайте сертификат доверенным в домене, например, с помощью групповых политик.
  4. Выдайте учетной записи nginx права на чтение файлов сертификата.

Настройка конфигурационного файла

Для работы Rutoken KeyBox настройте nginx, чтобы веб-сервер обслуживал запросы и отправлял их на проксируемый адрес – сервис RutokenKeyBox.

Работа nginx и его модулей определяется в конфигурационном файле nginx.conf. В зависимости от операционной системы он расположен в каталоге /usr/local/nginx/conf, /etc/nginx или /usr/local/etc/nginx.

КонтекстДирективаЗначение по умолчаниюРекомендуемое значениеКомментарий
httpproxy_buffer_size4k|8k16kУвеличивается размер прокси буферов для передачи необходимой информации в http-запросах

proxy_buffers8 4k | 8 8k4 16kУвеличивается размер прокси буферов для передачи необходимой информации в http-запросах

types_hash_max_size10244096Увеличивается размер хэш-таблиц для хранения информации в виду большого количества проксируемых сервисов

client_max_body_size1m10mУвеличивается допустимый размер загружаемых в систему файлов
serverlisten80443 sslИзменяется порт прослушивания на протокол HTTPS, по умолчанию nginx настроен на HTTP



3003 sslПорт 3003 указывается для дополнительного контекста server в случае использования агентского функционала Rutoken KeyBox

ssl_certificate—/etc/ssl/private/SSL.crtДля работы по HTTPS указывается путь к файлу с цепочкой сертификатов (SSL сертификат, сертификаты промежуточного и корневого УЦ)

ssl_certificate_key—/etc/ssl/private/SSL.keyДля работы по HTTPS указывается путь к закрытому ключу SSL сертификата

ssl_verify_clientoffoptional_no_caДобавляется в случае авторизации по сертификату (используется клиентскими агентами)
locationproxy_pass—*Один экземпляр контекста location направляет запросы на один адрес — сервис Rutoken KeyBox. Таким образом, контекстов location должно быть столько, сколько есть сервисов Rutoken KeyBox.

Точка проксирования указывается в формате:
http://localhost:PORT/cm/SERVICENAME
http://localhost:PORT/AGENTSERVICENAME*
Где необходимо указать PORT — порт, на котором запущен сервис Rutoken KeyBox, а также SERVICENAME и AGENTSERVICENAME — имя запущенного сервиса

include—/etc/nginx/conf.d/proxy.confНекоторые директивы описываются для каждого location, и для компактности конфигурационного файла рекомендуется создать файл с часто используемым набором директив и подключать его в каждый location вместо описывания набора целиком

proxy_http_version1.01.1Версия 1.1 рекомендуется для keepalive подключений и NTLM аутентификации

proxy_cache_bypass—$http_upgradeОпределяет условия, при которых ответ не будет браться из кэша

proxy_set_header—Upgrade $http_upgradeОпределяет переход с HTTP/1.1 на веб-socket после установления соединения



Connection keep-aliveДля использования keepalive подключений



Host $hostДля сохранения в заголовках имени nginx сервера при их передаче сервисам Rutoken KeyBox



X-Real-IP $remote_addrПо умолчанию работа в режиме обратного прокси использует нестандартные заголовки о пользовательском IP адресе, что требует задания данной директивы



X-Forwarded-For $proxy_add_x_forwarded_forПодобно X-Real-IP $remote_addr, определяет формирование заголовка для корректного проксирования. Если поле X-Forwarded-For не присутствовало в изначальном заголовке, то $proxy_add_x_forwarded_for = $remote_addr



X-Forwarded-Proto $schemeВеб-сервер принимает запросы по HTTPS и проксирует их к HTTP сервисам Rutoken KeyBox для корректной подмены протокола

fastcgi_buffers8 4k|8k16 16kОпределяет количество и размер буферов для чтения ответов от FastCGI сервера, на одно подключение

fastcgi_buffer_size4k|8k32kОпределяет размер буфера для чтения первой части ответа от FastCGI сервера

proxy_set_header—x-ssl-client-cert $ssl_client_escaped_certДиректива передавать клиентский сертификат при проксировании. Используется клиентскими агентами для авторизации по сертификату

Вследствие использования в конфигурации многократного описания контекстовlocation, определенный набор директив будет повторяться.

Для удобства конфигурации вынесите данный набор директив в отдельный файл, а в описании контекста включите директивы из данного файла (директива include).

  1. Создайте файл с многократно используемыми директивами. Можно разместить такой файл с расширением CONF в каталоге /etc/nginx/conf.d/.

    Рекомендуемое содержимое файла proxy.conf для работы с Rutoken KeyBox
    proxy_http_version 1.1;
proxy_set_header   Upgrade $http_upgrade;
proxy_set_header   Connection keep-alive;
proxy_set_header   Host $host;
proxy_cache_bypass $http_upgrade;
proxy_set_header   X-Real-IP $remote_addr;
proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header   X-Forwarded-Proto $scheme;
fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
     

  2. Сконфигурируйте основной файл конфигурации nginx. Имена контекстовlocationдолжны совпадать с путем к проксируемому сервису.

    Пример файла nginx.conf для работы с Rutoken KeyBox
    user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log notice;
events {    worker_connections 1024;    }

http {
 proxy_buffer_size   64k;
 proxy_buffers   4 64k;
 types_hash_max_size     4096;
 add_header X-Frame-Options sameorigin always;
 add_header X-Content-Type-Options nosniff;

 log_format  main  '[$time_local] $remote_addr VIA $scheme --- $status --- $request \n $ssl_client_fingerprint';
 access_log  /var/log/nginx/access.log  main;
 sendfile                on;
 tcp_nopush              on;
 include                 /etc/nginx/mime.types;
 default_type            application/octet-stream;

 server {
     listen              443 ssl;
     server_name         $hostname;

     ssl_certificate     "/etc/ssl/certs/SSL.crt";
     ssl_certificate_key "/etc/ssl/private/SSL.key";

     location /cm/mc
     {   include /etc/nginx/conf.d/proxy.conf;   proxy_pass http://localhost:5001/cm/mc;    }
     location /cm/ss
     {   include /etc/nginx/conf.d/proxy.conf;   proxy_pass http://localhost:5002/cm/ss;    }
     location /cm/rss
     {   include /etc/nginx/conf.d/proxy.conf;   proxy_pass http://localhost:5003/cm/rss;   }
     location /cm/api
     {   include /etc/nginx/conf.d/proxy.conf;   proxy_pass http://localhost:5004/cm/api;   }
     location /cm/credprovapi
     {   include /etc/nginx/conf.d/proxy.conf;   proxy_pass http://localhost:5005/cm/credprovapi;   }
     location /cm/oidc
     {   include /etc/nginx/conf.d/proxy.conf;   proxy_pass http://localhost:5008/cm/oidc;  }
     location /cm/wizard
     {   proxy_pass http://localhost:5009;  }
     #location /api   
     #{  include /etc/nginx/conf.d/proxy.conf;   proxy_pass http://localhost:5010/api;  }
 }

 server {
     listen              3003 ssl;
     server_name         $hostname;

     ssl_certificate     "/etc/ssl/certs/SSL.crt";
     ssl_certificate_key "/etc/ssl/private/SSL.key";
     ssl_verify_client   optional_no_ca;
    
     location /agentregistrationapi 
     { include /etc/nginx/conf.d/proxy.conf;   proxy_pass http://localhost:5006/agentregistrationapi;  }
     location /agentserviceapi      
     { include /etc/nginx/conf.d/proxy.conf;   proxy_pass http://localhost:5007/agentserviceapi;
                                           proxy_set_header   x-ssl-client-cert $ssl_client_escaped_cert;  }
 }
}
     

  3. Примените изменения в конфигурационном файле. Для этого перезагрузите конфигурацию или перезапустите nginx. Для перезагрузки конфигурации выполните команду:

    sudo nginx -s reload

Debian-based

Установка веб-сервера


  1. Установите пакеты, необходимые для подключения apt-репозитория:

    Ubuntu:

    sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring

    Debian:

    sudo apt install curl gnupg2 ca-certificates lsb-release debian-archive-keyring
     

  2. Импортируйте официальный ключ, используемый apt для проверки подлинности пакетов:

    curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null
     

  3. Для подключения apt-репозитория выполните следующую команду:

    echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" | sudo tee /etc/apt/sources.list.d/nginx.list
     

  4. Выполните следующую команду:

    sudo apt update
sudo apt install nginx
     

Документация по установке на прочие ОС доступна на портале NGINX.


Установка TLS-сертификата

Установите TLS-сертификат на веб-сервер. 

  1. Скопируйте файлы сертификата и ключа в папку, которая указана в файле конфигурации nginx.

    sudo cp ./SSL.crt /etc/ssl/certs/
sudo cp ./SSL.key /etc/ssl/private/
     

  2. Добавьте сертификат корневого УЦ в доверенные на рабочей станции с установленным nginx.

    sudo cp ./ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates -f
     
  3. Сделайте сертификат доверенным в домене, например, с помощью групповых политик.
  4. Выдайте учетной записи www-data права на чтение файлов сертификата.

Настройка конфигурационного файла

Для работы Рутокен KeyBox требуется настроить nginx, чтобы он обслуживал запросы и отправлял их на проксируемый адрес – сервис RutokenKeyBox.

Работа nginx и его модулей определяется в конфигурационном файлеnginx.conf. В зависимости от операционной системы он расположен в каталоге/usr/local/nginx/conf,/etc/nginxили/usr/local/etc/nginx.

КонтекстДирективаЗначение по умолчаниюРекомендуемое значениеКомментарий
httpproxy_buffer_size4k|8k16kУвеличивается размер прокси буферов для передачи необходимой информации в http-запросах

proxy_buffers8 4k | 8 8k4 16kУвеличивается размер прокси буферов для передачи необходимой информации в http-запросах

types_hash_max_size10244096Увеличивается размер хэш-таблиц для хранения информации в виду большого количества проксируемых сервисов.

client_max_body_size1m10mУвеличивается допустимый размер загружаемых в систему файлов
serverlisten80443 sslИзменяется порт прослушивания на протокол HTTPS, по умолчанию nginx настроен на HTTP



3003 sslПорт 3003 указывается для дополнительного контекста server в случае использования агентского функционала Rutoken KeyBox

ssl_certificate—/etc/ssl/private/SSL.crtДля работы по HTTPS указывается путь к файлу с цепочкой сертификатов (SSL сертификат, сертификаты промежуточного и корневого УЦ)

ssl_certificate_key—/etc/ssl/private/SSL.keyДля работы по HTTPS указывается путь к закрытому ключу SSL сертификата

ssl_verify_clientoffoptional_no_caДобавляется в случае авторизации по сертификату (используется клиентскими агентами)
locationproxy_pass—*Один экземпляр контекста location направляет запросы на один адрес — сервис Rutoken KeyBox. Таким образом, контекстов location должно быть столько, сколько есть сервисов Rutoken KeyBox.

Точка проксирования указывается в формате:
http://localhost:PORT/cm/SERVICENAME
http://localhost:PORT/AGENTSERVICENAME*
Где необходимо указать PORT — порт, на котором запущен сервис Rutoken KeyBox, а также SERVICENAME и AGENTSERVICENAME — имя запущенного сервиса

include—/etc/nginx/conf.d/proxy.confНекоторые директивы описываются для каждого location, и для компактности конфигурационного файла рекомендуется создать файл с часто используемым набором директив и подключать его в каждый location вместо описывания набора целиком

proxy_http_version1.01.1Версия 1.1 рекомендуется для keepalive подключений и NTLM аутентификации

proxy_cache_bypass—$http_upgradeОпределяет условия, при которых ответ не будет браться из кэша

proxy_set_header—Upgrade $http_upgradeОпределяет переход с HTTP/1.1 на веб-socket после установления соединения



Connection keep-aliveДля использования keepalive подключений



Host $hostДля сохранения в заголовках имени nginx сервера при их передаче сервисам Rutoken KeyBox



X-Real-IP $remote_addrПо умолчанию работа в режиме обратного прокси использует нестандартные заголовки о пользовательском IP адресе, что требует задания данной директивы



X-Forwarded-For $proxy_add_x_forwarded_forПодобно X-Real-IP $remote_addr, определяет формирование заголовка для корректного проксирования. Если поле X-Forwarded-For не присутствовало в изначальном заголовке, то $proxy_add_x_forwarded_for = $remote_addr



X-Forwarded-Proto $schemeВеб-сервер принимает запросы по HTTPS и проксирует их к HTTP сервисам Rutoken KeyBox для корректной подмены протокола

fastcgi_buffers8 4k|8k16 16kОпределяет количество и размер буферов для чтения ответов от FastCGI сервера, на одно подключение

fastcgi_buffer_size4k|8k32kОпределяет размер буфера для чтения первой части ответа от FastCGI сервера

proxy_set_header—x-ssl-client-cert $ssl_client_escaped_certДиректива передавать клиентский сертификат при проксировании. Используется клиентскими агентами для авторизации по сертификату

Из-за использования в конфигурации многократного описания контекстов location, определенный набор директив будет повторяться.


Для удобства конфигурации вынесите данный набор директив в отдельный файл, а в описании контекста включите директивы из данного файла (директива include).


  1. Создайте файл с многократно используемыми директивами. Можно разместить такой файл с расширением CONF в каталоге /etc/nginx/conf.d/.

    Рекомендуемое содержимое файла proxy.conf для работы с Rutoken KeyBox
    proxy_http_version 1.1;
proxy_set_header   Upgrade $http_upgrade;
proxy_set_header   Connection keep-alive;
proxy_set_header   Host $host;
proxy_cache_bypass $http_upgrade;
proxy_set_header   X-Real-IP $remote_addr;
proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header   X-Forwarded-Proto $scheme;
fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
     

  2. Сконфигурируйте основной файл конфигурации nginx. Имена контекстов location должны совпадать с путем к проксируемому сервису.

    Пример файла nginx.conf для работы с Rutoken KeyBox 
    user www-data;
worker_processes auto;
error_log /var/log/nginx/error.log notice;
events {    worker_connections 1024;    }

http {
 proxy_buffer_size   64k;
 proxy_buffers   4 64k;
 types_hash_max_size     4096;
 add_header X-Frame-Options sameorigin always;
      add_header X-Content-Type-Options nosniff;

 log_format  main  '[$time_local] $remote_addr VIA $scheme --- $status --- $request \n $ssl_client_fingerprint';
 access_log  /var/log/nginx/access.log  main;
 sendfile                on;
 tcp_nopush              on;
 include                 /etc/nginx/mime.types;
 default_type            application/octet-stream;

 server {
      listen              443 ssl;
      server_name         $hostname;

      ssl_certificate     "/etc/ssl/certs/SSL.crt";
      ssl_certificate_key "/etc/ssl/private/SSL.key";

     location /cm/mc
     {   include /etc/nginx/conf.d/proxy.conf;   proxy_pass http://localhost:5001/cm/mc;    }
     location /cm/ss
     {   include /etc/nginx/conf.d/proxy.conf;   proxy_pass http://localhost:5002/cm/ss;    }
     location /cm/rss
     {   include /etc/nginx/conf.d/proxy.conf;   proxy_pass http://localhost:5003/cm/rss;   }
     location /cm/api
     {   include /etc/nginx/conf.d/proxy.conf;   proxy_pass http://localhost:5004/cm/api;   }
     location /cm/credprovapi
     {   include /etc/nginx/conf.d/proxy.conf;   proxy_pass http://localhost:5005/cm/credprovapi;   }
     location /cm/oidc
     {   include /etc/nginx/conf.d/proxy.conf;   proxy_pass http://localhost:5008/cm/oidc;  }
     location /cm/wizard
     {   proxy_pass http://localhost:5009;  }
     #location /api   
     #{  include /etc/nginx/conf.d/proxy.conf;   proxy_pass http://localhost:5010/api;  }
 }

 server {
      listen              3003 ssl;
      server_name         $hostname;

      ssl_certificate     "/etc/ssl/certs/SSL.crt";
      ssl_certificate_key "/etc/ssl/private/SSL.key";
      ssl_verify_client   optional_no_ca;
    
      location /agentregistrationapi 
      { include /etc/nginx/conf.d/proxy.conf;   proxy_pass http://localhost:5006/agentregistrationapi;  }
      location /agentserviceapi      
      { include /etc/nginx/conf.d/proxy.conf;   proxy_pass http://localhost:5007/agentserviceapi;
                                          proxy_set_header   x-ssl-client-cert $ssl_client_escaped_cert;  }
 }
}
     

  3. Примените изменения в конфигурационном файле. Для этого перезагрузите конфигурацию или перезапустите nginx. Для перезагрузки конфигурации выполните команду:

    sudo nginx -s reload

  • No labels