Описание

Eltex Documentation > v1.37_Doors > Selection_071.png

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

Eltex-doors формирует токен JWT на основе переданного POST-запроса содержащий логин, пароль, а также метаданные.

JWT(JSON Web Token) - JSON-объект, определен в RFC 7519

Сгенерированные токены хранятся в БД eltex-doors, таблица auth_token. По истечению, заданного в конфигурационном файле, времени (token.expire.timeout), выполняется очистка устаревших токенов из БД. БД eltex-doors в MariaDB разворачивается при первом запуске сервиса eltex-doors в соответствии с данными указанными в конфигурации сервиса.

Параметры "срок действия токена{iat}" и "время создания токена{exp}" указаны в payload токена. Их можно узнать выполнив декодирование токена.

С версии 1.15 появилась возможность валидировать токены без дополнительного обращения к doors. При установке или обновлении генерируются открытый и закрытый ключ, которые по умолчанию размещаются в каталоге /etc/eltex-doors/keys/.

Для того, чтобы к приватному ключу имели доступ только доверенные сервисы, ключам назначаются права 440 и принадлежность группе eltex:

-r--r----- 1 root eltex 1704 Sep 19 10:44 private.pem
-r--r----- 1 root eltex  451 Sep 19 10:44 public.pem

private.pem - ключ необходимый для подписи JWT-токенов.

public.pem - ключ необходимый сервисам для валидации JWT-токенов.

Если по какой-либо причине необходимо пересоздать ключи, то можно запустить скрипт, который находится в каталоге /usr/share/eltex-doors/gen_keys.sh

После генерации новых ключей, необходимо ключ public.pem заново передать сервисам

При первом обращении за JWT к Doors, сервис выдаёт два токена: access и refresh. Access token имеет короткий срок жизни и используется непосредственно для доступа к сервисам. Refresh token же живёт значительно дольше и используется только для получения нового access token. Такая схема позволяет быстро прекратить доступ к ресурсам в случае утечки access token.

Срок жизни токенов определяется в файле конфигурации сервиса Eltex Doors и по умолчанию составляет 15 минут для access и 30 дней для refresh.

По истечении срока жизни access token внешний сервис должен будет обратиться к Eltex Doors за новым access token, предъявив при этом refresh token.

Управление сервисом

Способы запуска/остановки

Действие

Команда

Ответ

Проверка состояния

service eltex-doors status

Сервис запущен

Active: active (running)

Cервис не запущен

Active: failed

Запуск сервиса

service eltex-doors start

Сервис успешно запущен

Active: active (running)

Остановка сервиса

service eltex-doors stop

Сервис успешно остановлен

Active: failed

Перезапуск сервиса

service eltex-doors restart

Сервис успешно перезапущен

Active: active (running)

Доступные методы AP

Eltex Doors предоставляет следующие методы:

Метод получения JWT (refresh token и access token) по логину и паролю.
Метод обновления access token по полученному ранее refresh token.
Метод инвалидации JWT.
Метод проверки JWT. Метод устарел и не рекомендуется к использованию.

`Получение токенов по логину и паролю`

Для получения access и refresh token требуется в Eltex Doors отправить POST-запрос в формате JSON на URL /api/signin со следующим содержимым:

 POST http://localhost:9097/api/signin HTTP/1.1
 Content-Type: application/json
 Accept: application/json
 {
    "username": "user",
    "password": "password",
    "metadata": {}
 }

В поле "username" указывается логин пользователя.
В поле "password" указывается пароль пользователя.
В поле "metadata" указываются любые данные, которые должны попасть в JWT.

Поле metadata становится опциональным с версии SoftWLC 1.17.

Пример запроса:

curl -XPOST -H "Content-type: application/json" -d '{"username": "user", "password": "password"}' 'http://localhost:9097/api/signin/'

В случае успеха, сервис ответит:

{
 "status": "OK",
 "accessToken": "eyJhbGc...",
 "refreshToken": "eyJhb..."
}

"status" - статус ответа;
"accessToken" - сгенерированный токен.

В случае ошибки, сервис ответит:

{"status":"FAIL","error":"Invalid username or password"}

"status" - статус ответа;
"error" - описание ошибки.

Отзыв токенов

Полученный ранее refresh token можно отозвать. Для этого нужно отправить запрос на URL /api/signout, добавив заголовок авторизации.

 POST http://localhost:9097/api/signout HTTP/1.1
 Accept: application/json
 Authorization: Bearer eyJhb...

Пример запроса:

curl -XPOST -H "Authorization: Bearer eyJhb..." 'http://localhost:9097/api/signout/'

В случае успеха, сервис ответит:

{
  "status": "OK",
  "accessToken": "Logged out",
  "refreshToken": null
}

В случае, если токен уже не валиден или неправильный:

{
  "status": "FAIL",
  "error":"Invalid JWT"
}

Обновление токена

Для обновления access token нужно отправить запрос на /api/signin/token с заголовком авторизации:

 POST http://localhost:9097/api/signin/token HTTP/1.1
 Accept: application/json
 Authorization: Bearer eyJhb...

Пример запроса:

curl -XPOST -H "Authorization: Bearer eyJhbGc..." 'http://100.110.1.222:9097/api/signin/token/'

В случае успеха, сервис ответит:

{
 "status": "OK",
 "accessToken": "eyJhbGc...",
 "refreshToken": "eyJhb..."
}

В случае, если токен уже не валиден или неправильный:

{
  "status": "FAIL",
  "error":"Invalid JWT"
}

Конфигурация

/etc/eltex-doors/application.conf

Основной конфигурационный файл.

# Mysql datasource properties
database {
  host = localhost
  port = 3306
  name = eltex_doors
  user = javauser
  password = javapassword

  pool {
    # Time to wait for a connection
    connectionTimeout = 10s
    # Time to wait for connection validation
    validationTimeout = 3s

    min = 1
    max = 5
  }
}

# Basic account credentials
auth {
  username = user
  password = password
}

# Authentification keys paths
keys {
  private = /etc/eltex-doors/keys/private.pem
  public = /etc/eltex-doors/keys/public.pem
}

# Tokens lifetime
tokens {
  clearTimeout = "*/60 * * * * *"

  lifetime {
    access = 15m
    refresh = 30d
  }
}

Основные данные для подключения к БД:

database {
  host = localhost
  port = 3306
  name = eltex_doors
  user = eltexdoors
  password = eltexpassword
...

Время ожидания подключения к БД:

connectionTimeout = 10s

Время ожидания валидации:

validationTimeout = 3s

Минимальное и максимальное количество подключений к БД:

    min = 1
    max = 5

Параметры подключения к auth-service:

auth {
  username = user
  password = password
}

Расположение ключей:

keys {
  private = /etc/eltex-doors/keys/private.pem
  public = /etc/eltex-doors/keys/public.pem
}

Время очистки БД от просроченных токенов:

clearTimeout = "*/60 * * * * *"

Время жизни токенов:

  lifetime {
    access = 15m
    refresh = 30d
  }

/etc/default/eltex-doors

Файл настройки инициализации сервиса.

# AP Monitoring service

# HTTP Port for use by Eltex Doors
PORT=9097

# Initial size of Java heap
JAVA_INIT_HEAP=32m
# Maximum size of Java heap
JAVA_MAX_HEAP=256m

# Additional arguments to pass to java
JAVA_OPTS="-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/eltex-doors"

Слушаемый сервисом порт.

# HTTP Port for use by Eltex Doors
PORT=9097

Количество памяти, выделяемое приложению при старте сервиса:

# Initial size of Java heap
JAVA_INIT_HEAP=32m

Максимальное количество памяти, которое может арендовать сервис:

# Maximum size of Java heap
JAVA_MAX_HEAP=256m

Дополнительные опции запуска java:

# Additional arguments to pass to java
JAVA_OPTS="-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/eltex-doors"

/etc/eltex-doors/log4j2.xml

Файл настройки логирования.

<?xml version="1.0" encoding="UTF-8"?>

<Configuration monitorInterval="600">
    <Properties>
        <Property name="rootLevel">DEBUG</Property>

        <Property name="baseDir">/var/log/eltex-doors</Property>
        <Property name="maxFileSize">5 MB</Property>
        <Property name="accumulatedFileSize">100 MB</Property>
        <Property name="lastModified">7d</Property>
        <Property name="maxCount">10</Property>
        <Property name="logPattern">%d{ISO8601} [%t] %-5p %logger{1} %C{1}.%M(line:%L). %m%n</Property>

        <Property name="consoleLevel">${env:CONSOLE_LEVEL:-OFF}</Property>

        <Property name="gelfLevel">${env:GELF_LEVEL:-OFF}</Property>
        <Property name="gelfHost">${env:GELF_HOST:-udp:lab3-test.eltex.loc}</Property>
        <Property name="gelfPort">${env:GELF_PORT:-12201}</Property>
    </Properties>

    <Appenders>

        <Console name="STDERR" target="System.err">
            <PatternLayout pattern="${logPattern}"/>
        </Console>

        <RollingFile name="RollingFile"
                     fileName="${baseDir}/doors.log"
                     filePattern="${baseDir}/log/doors-%i.log.gz">
            <PatternLayout pattern="${logPattern}"/>
            <Policies>
                <SizeBasedTriggeringPolicy size="${maxFileSize}"/>
                <OnStartupTriggeringPolicy/>
            </Policies>
            <DefaultRolloverStrategy max="${maxCount}">
                <Delete basePath="${baseDir}" maxDepth="3">
                    <IfFileName glob="*/doors-*.log.gz">
                        <IfAny>
                            <IfAccumulatedFileSize exceeds="${accumulatedFileSize}"/>
                            <IfLastModified age="${lastModified}"/>
                        </IfAny>
                    </IfFileName>
                </Delete>
            </DefaultRolloverStrategy>
        </RollingFile>

        <Gelf name="Gelf" host="${gelfHost}" port="${gelfPort}" version="1.1" facility="eltex-doors"
              extractStackTrace="true" originHost="%host{fqdn}" maximumMessageSize="8192">
            <Field name="thread" pattern="%t"/>
            <Field name="level" pattern="%level"/>
            <Field name="severity" pattern="%-5level"/>
            <Field name="logger" pattern="%logger{1}"/>
            <Field name="location" pattern="%C{1}.%M(line:%L)"/>
        </Gelf>
    </Appenders>

    <Loggers>
        <Root level="${rootLevel}">
            <AppenderRef ref="RollingFile"/>
            <AppenderRef ref="STDERR" level="${consoleLevel}"/>
            <AppenderRef ref="Gelf" level="${gelfLevel}"/>
        </Root>

        <Logger name="org.eltex.softwlc.doors"  level="INFO"/>
        <Logger name="org.springframework"      level="ERROR"/>
        <Logger name="org.eclipse.jetty"        level="ERROR"/>
        <Logger name="com.zaxxer"               level="ERROR"/>

    </Loggers>
</Configuration>

Интервал автоматического перечитывания конфигурации логгера:

<Configuration monitorInterval="600">

Базовая директория хранения логов:

<Property name="baseDir">/var/log/eltex-doors</Property>

Максимально допустимый размер файла (при его превышении создается новый файл, а старый архивируется):

<Property name="maxFileSize">5 MB</Property>

Суммарный размер логов (текущий файл + архивные). При его превышении наиболее старые файлы будут удаляться:

<Property name="accumulatedFileSize">100 MB</Property>

Срок хранения логов, файлы модифицированные раннее этого срока будут удаляться:

<Property name="lastModified">7d</Property>

Максимальное количество архивных файлов, при его превышении наиболее старые файлы будут перезаписываться:

<Property name="maxCount">10</Property>

Блок настройки перенаправления логов в Graylog (уровень логирования, адрес, порт):

<Property name="gelfLevel">OFF</Property>
<Property name="gelfHost">udp:lab3-test.eltex.loc</Property>
<Property name="gelfPort">12201</Property>

Уровень логирования:

<Property name="rootLevel">DEBUG</Property>

Многохостовая установка

При использовании многохостовой установки комплекса SoftWLC, сервис Eltex-doors рекомендуется устанавливать на одном сервере с Eltex-portal и Eltex-portal-constructor. Если eltex-doors находится на отдельном сервере - для корректного взаимодействия с eltex-portal и eltex-portal-constructor требуется скопировать на соответствующие сервера приватный и публичный ключи из папки /etc/eltex-doors/keys/ в аналогичную папку (папка может быть изменена, но это потребует исправления соответствующих настроек портала и конструктора порталов) и выполнить перезапуск сервисов eltex-portal и eltex-portal-constructor.

Докеризация сервиса

Сервис может быть запущен в docker-контейнере. Для этого необходимо подготовить файл с переменными окружения .env и docker-compose.yml.

version: "3"
services:
  doors:
    container_name: eltex-doors
    image: ${ELTEX_HUB}/eltex-doors:${SWLC_VERSION}
    ports:
      - 9097:9097
    environment:
      - database.host=${DOORS_DATABASE_HOST}
      - database.port=${DOORS_DATABASE_PORT}
      - DOORS_LOG_LEVEL=${DOORS_LOG_LEVEL}
      - DOORS_CONSOLE_LOG_LEVEL=${DOORS_CONSOLE_LOG_LEVEL}
      - GELF_LEVEL=${GELF_LEVEL}
      - GELF_HOST=${GELF_HOST}
      - GELF_PORT=${GELF_PORT}
      - TZ=${TZ}
    volumes:
    - /etc/eltex-doors/keys/:/etc/eltex-doors/keys

ELTEX_HUB=hub.eltex-co.ru/softwlc
SWLC_VERSION=1.21-<tag>
 
DOORS_DATABASE_HOST=<ip_database>
DOORS_DATABASE_PORT=3306
DOORS_LOG_LEVEL=INFO
DOORS_CONSOLE_LOG_LEVEL=INFO
#Настройка перенаправления логов на сервер Graylog
GELF_LEVEL=OFF
GELF_HOST=udp:<ip_graylog_server>
GELF_PORT=12201

#Настройка часового пояса
TZ=Asia/Novosibirsk

Вместо <tag> необходимо указать актуальную версию, которую можно посмотреть по ссылке.

Вместо <ip_database> необходимо указать ip-адрес сервера MariaDB.

Вместо <ip_graylog_server> необходимо указать ip-адрес сервера Graylog.

Описание переменных (environment)

Запуск сервиса

ELTEX_HUB - URL репозитория Элтекс;
SWLC_VERSION - версия образа;

Подключение к БД (MariaDB)

DOORS_DATABASE_HOST - ip-адрес для подключения к БД MariaDB;
DOORS_DATABASE_PORT - порт для подключения к БД MariaDB;

Параметры логирования

DOORS_LOG_LEVEL - уровень логгирования сервиса;
DOORS_CONSOLE_LOG_LEVEL - уровень логгирования сервиса в консоль.

Настройка перенаправления логов на сервер Graylog

GELF_LEVEL - уровень логов, перенаправляемых в Graylog
GELF_HOST - адрес хоста Graylog
GELF_PORT - порт хоста Graylog

Настройка часового пояса

TZ - часовой пояс в формате Asia/Novosibirsk (список существующих можно посмотреть командой timedatectl list-timezones).

Файлы .env и docker-compose.yml должны находиться в одной папке. Контейнер запускается командой:

docker-compose up -d