7. Руководство по интеграции

Ниже на практическом примере рассмотрено как встроить IDENTYX в веб-приложение. Демонстрационное приложение, на примере которого рассматривается интеграция, входит в комплект поставки IDENTYX.

Способы интеграции

IDENTYX предлагает три основных подхода к интеграции, от самого простого до наиболее гибкого:

Способ 0: Прокси, без доработок

Самый простой способ защитить приложение, не требующий изменений в его коде:

Принцип работы: IDENTYX размещает прокси-сервер перед вашим приложением, который проверяет наличие сессии пользователя
Доступ: Контролируется на уровне URL-адресов
Приложение: Не получает информации о пользователе

Способ подходит для быстрой защиты существующих приложений, если:

У вас нет возможности изменять код приложения
Требуется быстрое внедрение защиты
Достаточно простого контроля доступа по URL

Способ 1: Прокси, с доработками

Немного более сложный, но гораздо более функциональный способ:

Принцип работы: Прокси-сервер интегрируется с приложением через специальные API-вызовы
Доступ: Контролируется как на уровне URL, так и внутри приложения
Приложение: Получает информацию о пользователе и его разрешениях

Способ рекомендуется в большинстве случаев, если:

Требуется более детальный контроль доступа внутри приложения
Нежелательно реализовывать полный протокол OIDC
Приложение уже имеет некоторую логику авторизации

Способ 2: По стандарту OIDC/OAuth 2.0

Наиболее гибкий и стандартизированный подход:

Принцип работы: Прямая интеграция приложения со IDENTYX через протоколы OIDC/OAuth 2.0
Доступ: Полностью контролируется приложением
Приложение: Самостоятельно управляет всем процессом аутентификации и авторизации

Способ подходит для случаев, когда прокси-сервиса недостаточно, например:

Требуется максимальная гибкость управления сессиями
Приложение не разделено на клиент-сервер (монолит, мобильное приложение)
Используется микросервисная архитектура, не подходящая для проксирования

Способ 0: Прокси, без доработок

Это самый простой способ защиты вашего приложения.

Добавление в IDENTYX (без доработок)

Войдите в административную консоль IDENTYX (http://localhost:8090)
Перейдите в раздел "Приложения"
Нажмите "Добавить приложение"
Заполните форму:
- Название: Имя вашего приложения
- Порт: Порт для доступа к приложению через прокси (например, 8216)
- URL приложения: Внутренний адрес вашего приложения (например, http://demo-app:80)
- Настройте маршруты и правила предоставления доступа к ним
- Запомните Client ID и Client Secret
Нажмите "Сохранить"

Проверка работы

Откройте приложение через прокси: http://localhost:8091 (порт 8216 отображается в 8091)
При попытке доступа к защищённым страницам вы будете перенаправлены на страницу входа
После успешной аутентификации вы получите доступ к защищённым ресурсам

Преимущество этого подхода — вам не нужно менять код приложения вообще. Достаточно настроить прокси в консоли IDENTYX.

Способ 1: Прокси, с доработками

Этот подход позволяет приложению получать информацию о пользователе и его разрешениях, что даёт возможность реализовать более детальный контроль доступа.

Добавление в IDENTYX (настройка прокси)

Порядок действий аналогичен Способу 0, однако необходимо добавить маршруты к эндпоинтам приложения, отвечающим за получение информации о начале и окончании сессии.

При этом необходимо реализовать эти два обязательных эндпоинта в приложении.

Эндпоинт `/proxy/newsession`

Этот эндпоинт вызывается IDENTYX при успешной аутентификации пользователя. Приложение должно извлечь и запомнить сведения о пользователе и его разрешениях.

Информация о пользователе, передаваемая от IDENTYX имеет следующую структуру:

{
  "user_info": {
    "sub": "1234567890",
    "name": "Иван Петров",
    "email": "ivan@example.com",
    "permissions": [
      "/:/auth",
      "/rooms/floor1:/book",
      "/rooms/floor2:/read"
    ]
  },
  "oidc_session": "AHHps7zVREyKD6d2P8FqhwYMY9tWe1Bs"
}

Вот пример реализации эндпоинта на языке Python:

@app.route('/proxy/newsession', methods=['POST'])
def newsession():
    # Получаем данные от IDENTYX
    data = flask.request.get_json()
    
    # Извлекаем идентификатор сессии и информацию о пользователе
    session = data.get('oidc_session', 'no-session')
    user_info = data.get('user_info', {})
    
    # Сохраняем информацию в сессии приложения
    # В реальном приложении следует использовать защищённое хранилище
    app.session_info[session] = user_info
    
    # Создаём ответ с флагом успеха
    response = flask.jsonify({"success": "true"})
    
    # Устанавливаем cookie с идентификатором сессии
    response.set_cookie('session', session)
    
    return response

Эндпоинт `/proxy/endsession`

Этот эндпоинт вызывается при завершении сессии. Приложение должно сбросить сохраненные ранее данные о пользователе и его разрешениях.

@app.route('/proxy/endsession')
def endsession():
    # Получаем идентификатор текущей сессии
    session = flask.request.cookies.get('session', 'no-session')
    
    # Удаляем информацию о сессии
    app.session_info.pop(session, None)
    
    # Перенаправляем на страницу выхода IDENTYX
    redirect_url = '/api/service/sprut-proxy/logout?redirect=true'
    return flask.redirect(redirect_url)

Проверка разрешений (прокси)

Теперь вы можете проверять разрешения пользователя в любой части кода. При этом рекомендуется использовать ранее сохраненные права доступа, либо каждый раз обращаться к IDENTYX за актуальными данными пользователя.

def checkPermission(permission):
    # Получаем идентификатор сессии из cookie
    session = flask.request.cookies.get('session', 'no-session')
    
    # Получаем информацию о сессии
    session_info = app.session_info.get(session, {})
    
    # Получаем список разрешений
    permissions = session_info.get('permissions', [])
    
    # Проверяем наличие требуемого разрешения
    return permission in permissions

Вызов процедуры проверки разрешения

# Пример использования в обработчике запроса
@app.route('/app/edit')
def edit():
    # Проверяем, авторизован ли пользователь
    if not checkPermission('/:/auth'):
        return "Доступ запрещен", 403
        
    # Проверяем конкретное разрешение
    if not checkPermission('/rooms/floor1:/book'):
        return "Недостаточно прав для бронирования", 403
        
    # Код обработки запроса...
    return "Редактирование разрешено"

Способ 2: По стандарту OIDC/OAuth 2.0

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

Добавление в IDENTYX (настройка OIDC)

Порядок действий аналогичен Способу 0, однако необходимо выбрать режим "Не использовать прокси".

На закладке Безопасность необходимо задать допустимый список Redirect URI, включив туда внешние URL приложения для обработки ответа после аутентификации (например, http://localhost:8081/oidc/callback)

Структура эндпоинтов сервера OIDC

Эндпоинты OIDС расположены по адресу /api/service/oidc

Например, интерфейс автообнаружения сервисов доступен на /api/service/oidc/.well-known/openid-configuration

# Адреса OIDC-сервера (внешний для перенаправления пользователя, внутренний для API-запросов)
OIDC_SERVER_EXT=http://localhost:8090
OIDC_SERVER_INT=http://sprut-iam:8215

# Эндпоинты OIDC
AUTH_ENDPOINT=${OIDC_SERVER_EXT}/login/oidc
TOKEN_ENDPOINT=${OIDC_SERVER_INT}/api/service/oidc/token
LOGOUT_ENDPOINT=${OIDC_SERVER_INT}/api/service/oidc/end-session
SERVICE_ENDPOINT=${OIDC_SERVER_INT}/api/service/ext-apps
USERINFO_ENDPOINT=${OIDC_SERVER_INT}/api/service/oidc/userinfo

Эндпоинт `/oidc/login`

Этот эндпоинт инициирует процесс аутентификации, перенаправляя пользователя на страницу входа IDENTYX:

@app.route('/oidc/login')
def login():
    # Генерируем случайное значение state для защиты от CSRF
    state = f'{time.time()**2:.0f}'
    flask.session['state'] = state
    
    # Формируем URL для перенаправления на страницу аутентификации
    redirect_url = (
        f'{ENV["AUTH_ENDPOINT"]}?'
        f'response_type=code&'
        f'client_id={ENV["CLIENT_ID"]}&'
        f'redirect_uri={ENV["CLIENT_REDIRECT"]}&'
        f'scope=openid profile permissions&'
        f'state={state}'
    )
    
    # Перенаправляем пользователя
    return flask.redirect(redirect_url)

Эндпоинт `/oidc/callback`

Этот эндпоинт обрабатывает ответ от IDENTYX после успешной аутентификации:

@app.route('/oidc/callback')
def callback():
    # Проверяем соответствие значения state для защиты от CSRF
    state = flask.session.get('state', 'no-state')
    check = flask.request.args.get('state', 'no-check')
    
    if state != check:
        return "Ошибка безопасности: несоответствие state", 400
    
    # Получаем код авторизации
    code = flask.request.args.get('code', 'no-code')
    
    # Обмениваем код на токены
    tokens = fetchTokens('authorization_code', 'code', code)
    
    if not tokens:
        return "Не удалось получить токены", 400
    
    # Декодируем и проверяем токены
    session_info = decodeTokens(tokens)
    
    if not session_info:
        return "Не удалось декодировать токены", 400
    
    # Сохраняем информацию о сессии
    session = session_info['id_token']['sid']
    saveSessionInfo(session, session_info)
    
    # Перенаправляем на главную страницу
    return flask.redirect(flask.url_for('root'))

Эндпоинт `/oidc/logout`

Этот эндпоинт завершает сессию пользователя:

@app.route('/oidc/logout')
def logout():
    # Получаем токен доступа
    access_token = getSessionInfo().get('access_token', None)
    
    # Вызываем эндпоинт завершения сессии в IDENTYX
    http_request('GET', ENV['LOGOUT_ENDPOINT'], access_token=access_token)
    
    # Очищаем локальную сессию
    clearSessionInfo(getSessionId())
    
    # Перенаправляем на главную страницу
    return flask.redirect(flask.url_for('root'))

Проверка разрешений (сервер)

Проверка разрешений в режиме сервера OIDC выполняется аналогично режиму прокси. Однако, в отличие от режима прокси, необходимо самостоятельно проверять активность сессии.

API для загрузки справочников

Если приложение работает с собственными объектами (например, комнаты, документы, проекты), можно загрузить их в IDENTYX для назначения прав доступа в разрезе прикладных объектов. Можно загружать справочник организаций, объектов и действий.

Для загрузки справочников используется эндпоинт /api/service/ext-apps

# Отправляем справочники в IDENTYX
http_request('POST', ENV['SERVICE_ENDPOINT'], json={
    'client_id': ENV['CLIENT_ID'],
    'client_secret': ENV['CLIENT_SECRET'],
    'action': 'putDictionaries',
    'data': { 'dictionaries': dictionaries }
})

Данные справочников передаются в структуре dictionaries, в виде массива структур { id, title }. Отдельно передаются справочники организаций (organizations), объектов (objects), действий (actions)

Идентификаторы объектов (поле id) имеют иерархическую структуру:

Должны начинаться с символа /
Вложенные объекты также указываются через /
Например: /floor1/room101 означает, что объект "room101" находится внутри объекта "floor1"

# Пример загружаемых справочников
dictionaries = {
    # Действия (например, чтение, запись, бронирование)
    'actions': [
        {'id': '/auth', 'title': 'Авторизация'},
        {'id': '/book', 'title': 'Бронирование'},
        {'id': '/read', 'title': 'Чтение'},
        {'id': '/write', 'title': 'Запись'}
    ],
    
    # Объекты (например, комнаты, этажи)
    'objects': [
        {'id': '/floor1', 'title': 'Этаж #1'},
        {'id': '/floor1/room101', 'title': 'Переговорная 1-01'},
        {'id': '/floor1/room102', 'title': 'Переговорная 1-02'},
        {'id': '/floor2', 'title': 'Этаж #2'},
        {'id': '/floor2/room201', 'title': 'Переговорная 2-01'}
    ],
    
    # Организации
    'organizations': [
        {'id': '/org0001', 'title': 'Организация #1'},
        {'id': '/org0002', 'title': 'Организация #2'}
    ]
}

IDENTYX IAM Help

7. Руководство по интеграции

Способы интеграции

Способ 0: Прокси, без доработок

Добавление в IDENTYX (без доработок)

Проверка работы

Способ 1: Прокси, с доработками

Добавление в IDENTYX (настройка прокси)

Эндпоинт `/proxy/newsession`

Эндпоинт `/proxy/endsession`

Проверка разрешений (прокси)

Способ 2: По стандарту OIDC/OAuth 2.0

Добавление в IDENTYX (настройка OIDC)

Структура эндпоинтов сервера OIDC

Эндпоинт `/oidc/callback`

Эндпоинт `/oidc/logout`

Проверка разрешений (сервер)

API для загрузки справочников

Рекомендации по интеграции

Особенности реализации

Производительность

7. Руководство по интеграции

Способы интеграции

Способ 0: Прокси, без доработок

Добавление в IDENTYX (без доработок)

Проверка работы

Способ 1: Прокси, с доработками

Добавление в IDENTYX (настройка прокси)

Эндпоинт /proxy/newsession

Эндпоинт /proxy/endsession

Проверка разрешений (прокси)

Способ 2: По стандарту OIDC/OAuth 2.0

Добавление в IDENTYX (настройка OIDC)

Структура эндпоинтов сервера OIDC

Эндпоинт /oidc/login

Эндпоинт /oidc/callback

Эндпоинт /oidc/logout

Проверка разрешений (сервер)

API для загрузки справочников

Рекомендации по интеграции

Особенности реализации

Производительность

Эндпоинт `/proxy/newsession`

Эндпоинт `/proxy/endsession`

Эндпоинт `/oidc/login`

Эндпоинт `/oidc/callback`

Эндпоинт `/oidc/logout`