Интеграция приложения с IDENTYX Proxy

Обзор интеграции

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

Преимущества интеграции:

• Автоматическая аутентификация — не нужно реализовывать собственную систему входа
• Единый вход (SSO) — пользователи входят один раз в IDENTYX и получают доступ ко всем приложениям
• Централизованное управление — все права доступа управляются в IDENTYX
• Безопасность — HTTPS для всех подключений, защищенная передача данных

Способы получения данных о пользователе

Ваше приложение может получить информацию о пользователе тремя способами:

Метод 1: Заголовок X-Session-Id

Прокси добавляет заголовок X-Session-Id к каждому запросу, который проксируется на бэкенд. Значение этого заголовка — уникальный идентификатор сессии прокси.

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

// Пример чтения заголовка
$sessionId = $_SERVER['HTTP_X_SESSION_ID'];

Метод 2: REST endpoint (рекомендуется)

Это наиболее универсальный способ интеграции, подходящий для приложений с собственной системой управления сессиями.

Настройка endpoint в IDENTYX

Пошаговая инструкция:

1. Откройте карточку вашего приложения в IDENTYX
2. Перейдите на вкладку Проксирование → подвкладка Перенаправления
3. В поле "REST endpoint для информации о новой сессии" укажите URL вашего endpoint (например, http://localhost:8080/api/identyx/session)
4. Сохраните настройки приложения

Что прокси отправляет на ваш endpoint

Когда пользователь успешно аутентифицируется, IDENTYX Proxy отправляет POST запрос на указанный endpoint. Запрос содержит заголовок X-Session-Id и JSON-тело со следующими данными:

Поле	Тип	Описание
action	string	Всегда "setOidcUserInfo"
user_info	object	Объект с информацией о пользователе
oidc_access_token	string	Access токен для обращения к IDENTYX API
oidc_refresh_token	string	Refresh токен для обновления access токена
oidc_session	string	Идентификатор сессии прокси (GUID)

Структура объекта user_info

Поле	Тип	Описание
sub	string	Уникальный идентификатор пользователя (ID)
preferred_username	string	Имя пользователя (username)
name	string	Отображаемое имя пользователя
email	string	Email пользователя
permissions	array	Массив прав доступа пользователя в формате объект:действие

Примеры реализации endpoint

Пример на PHP:

<?php
// Идентификатор сессии приходит в заголовке X-Session-Id
$sessionId = $_SERVER['HTTP_X_SESSION_ID'] ?? null;

// Читаем JSON из тела запроса
$json = file_get_contents('php://input');
$data = json_decode($json, true);

if ($data['action'] === 'setOidcUserInfo' && $sessionId) {
    $userInfo = $data['user_info'];

    // Используем session_id из заголовка — cookie не нужна
    ini_set('session.use_cookies', '0');
    session_id($sessionId);
    session_start();

    $_SESSION['user_id'] = $userInfo['sub'];
    $_SESSION['username'] = $userInfo['preferred_username'];
    $_SESSION['display_name'] = $userInfo['name'];
    $_SESSION['email'] = $userInfo['email'];
    $_SESSION['permissions'] = $userInfo['permissions'];
    $_SESSION['access_token'] = $data['oidc_access_token'];

    header('Content-Type: application/json');
    echo json_encode(['success' => 'true']);
} else {
    http_response_code(400);
    echo json_encode(['error' => 'Invalid action']);
}
?>

Пример на Node.js (Express):

const express = require('express');
const app = express();
app.use(express.json());

// Хранилище сессий (в продакшне используйте Redis или другое хранилище)
const sessions = new Map();

app.post('/api/identyx/session', (req, res) => {
    const sessionId = req.headers['x-session-id'];
    const { action, user_info, oidc_access_token, oidc_session } = req.body;

    if (action !== 'setOidcUserInfo' || !sessionId) {
        return res.status(400).json({ error: 'Invalid action' });
    }

    // Сохраняем данные сессии, используя session_id из заголовка
    sessions.set(sessionId, {
        userId: user_info.sub,
        username: user_info.preferred_username,
        displayName: user_info.name,
        email: user_info.email,
        permissions: user_info.permissions,
        accessToken: oidc_access_token,
    });

    res.json({ success: 'true' });
});

// Middleware для проверки авторизации — читаем X-Session-Id
app.use((req, res, next) => {
    const sessionId = req.headers['x-session-id'];
    req.userSession = sessionId ? sessions.get(sessionId) : null;
    next();
});

app.listen(8080);

Пример на Python (Flask):

from flask import Flask, request, jsonify

app = Flask(__name__)

# Хранилище сессий (в продакшне используйте Redis или другое хранилище)
sessions = {}

@app.route('/api/identyx/session', methods=['POST'])
def identyx_session():
    session_id = request.headers.get('X-Session-Id')
    data = request.get_json()

    if data.get('action') != 'setOidcUserInfo' or not session_id:
        return jsonify({'error': 'Invalid action'}), 400

    user_info = data.get('user_info', {})

    # Сохраняем данные сессии, используя session_id из заголовка
    sessions[session_id] = {
        'user_id': user_info.get('sub'),
        'username': user_info.get('preferred_username'),
        'display_name': user_info.get('name'),
        'email': user_info.get('email'),
        'permissions': user_info.get('permissions', []),
        'access_token': data.get('oidc_access_token'),
    }

    return jsonify({'success': 'true'})

if __name__ == '__main__':
    app.run(port=8080)

Обработка ошибок авторизации приложения

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

Способы сообщения об ошибке

Ваше приложение может сообщить прокси об ошибке авторизации одним из трех способов:

Способ	Описание	Применение
HTTP статус код	Вернуть статус 401 Unauthorized или 403 Forbidden	Универсальный способ, работает всегда
HTTP заголовок	Добавить заголовок X-App-Auth-Error: true	Для случаев, когда нужен статус 200, но есть ошибка авторизации
Cookie	Установить cookie app_auth_error=true	Для сложных приложений с многоэтапной авторизацией

Примеры обработки ошибок

Пример на PHP:

<?php
// Восстанавливаем сессию по X-Session-Id
$sessionId = $_SERVER['HTTP_X_SESSION_ID'] ?? null;
if ($sessionId) {
    ini_set('session.use_cookies', '0');
    session_id($sessionId);
    session_start();
}

// Проверяем сессию приложения
if (!isset($_SESSION['user_id'])) {
    // Сессия не найдена - сообщаем прокси
    header('X-App-Auth-Error: true');
    echo json_encode(['error' => 'Не авторизован']);
    exit;
}

// Сессия валидна - продолжаем работу
echo 'Добро пожаловать, ' . $_SESSION['display_name'];
?>

Пример на Node.js (Express):

app.use((req, res, next) => {
    const sessionId = req.headers['x-session-id'];
    req.userSession = sessionId ? sessions.get(sessionId) : null;

    if (!req.userSession) {
        res.header('X-App-Auth-Error', 'true');
        return res.status(200).json({ error: 'Не авторизован' });
    }

    next();
});

Пример на Python (Flask):

@app.before_request
def check_session():
    session_id = request.headers.get('X-Session-Id')
    user_session = sessions.get(session_id) if session_id else None

    if not user_session:
        response = make_response(jsonify({'error': 'Не авторизован'}), 200)
        response.headers['X-App-Auth-Error'] = 'true'
        return response

Метод 3: API учетных записей

Если ваше приложение должно автоматически входить в сторонние системы, вы можете получить сохраненные учетные записи пользователя через API прокси.

Получение учетных записей

Endpoint: GET /api/service/proxy/getBestCredentials

Этот endpoint возвращает наиболее подходящие учетные записи пользователя для текущего приложения.

Ответ:

{
  "success": true,
  "data": {
    "credentials": [
      {
        "object_path": "/myapp",
        "credential": {
          "id": 123,
          "title": "Рабочая учетная запись",
          "type": "password",
          "source": "personal",
          "content": {
            "login": "user@example.com",
            "password": "secretpassword"
          }
        }
      }
    ],
    "user_id": 456,
    "application_id": "myapp-id",
    "count": 1
  }
}

Пример использования

JavaScript (клиентская сторона):

// Запрашиваем учетные записи
async function getCredentials() {
    const response = await fetch('/api/service/proxy/getBestCredentials');
    const result = await response.json();
    
    if (result.success && result.data.credentials.length > 0) {
        const credential = result.data.credentials[0].credential;
        
        // Автоматически заполняем форму
        document.getElementById('username').value = credential.content.login;
        document.getElementById('password').value = credential.content.password;
        
        // При необходимости автоматически отправляем форму
        document.getElementById('loginForm').submit();
    }
}

// Вызываем при загрузке страницы
getCredentials();

Жизненный цикл сессии

Понимание жизненного цикла сессии поможет правильно интегрировать приложение с прокси.

1. Пользователь обращается к приложению — открывает URL приложения в браузере
2. Прокси проверяет сессию — если сессии нет, перенаправляет на страницу входа IDENTYX
3. Аутентификация в IDENTYX — пользователь вводит логин и пароль (или использует другие методы входа)
4. Прокси получает токены — после успешной аутентификации прокси получает access и refresh токены
5. Прокси отправляет данные приложению — POST запрос на ваш endpoint с заголовком X-Session-Id и информацией о пользователе
6. Приложение сохраняет сессию — ваше приложение сохраняет данные пользователя, используя полученный идентификатор сессии
7. Работа с приложением — пользователь получает доступ к приложению, каждый запрос содержит заголовок X-Session-Id
8. Обновление токенов — прокси автоматически обновляет токены при истечении
9. Завершение сессии — пользователь выходит или сессия истекает по таймауту

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

Решение проблем интеграции

Проблема	Возможная причина	Решение
Endpoint не получает данные от прокси	Неправильный URL или приложение недоступно	Проверьте URL endpoint в настройках приложения. Убедитесь, что endpoint доступен с сервера IDENTYX
Пользователь видит ошибку после входа	Endpoint не вернул {"success": "true"}	Убедитесь, что endpoint возвращает корректный JSON ответ
Сессия постоянно сбрасывается	Приложение не сохраняет данные по X-Session-Id или хранилище сессий недоступно	Убедитесь, что приложение корректно читает заголовок X-Session-Id и сохраняет данные в хранилище. Проверьте доступность хранилища сессий
Прокси не обнаруживает ошибку авторизации	Приложение не отправляет правильные сигналы	Используйте HTTP статус 401/403 или добавьте заголовок X-App-Auth-Error

Тестирование интеграции

Для проверки корректности интеграции протестируйте следующие сценарии:

1. Первичный вход — пользователь входит в приложение впервые
2. Повторный вход — пользователь возвращается в приложение с активной сессией прокси
3. Истечение сессии приложения — сессия приложения истекла, но сессия прокси активна
4. Истечение сессии прокси — сессия прокси истекла, пользователь должен войти заново
5. Принудительный выход — пользователь нажимает кнопку "Выйти"
6. Несколько вкладок — пользователь открывает приложение в нескольких вкладках одновременно