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

ℹ️ О документе

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

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

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

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

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

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

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

1️⃣ Через заголовок X-Session-Id

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

2️⃣ Через REST endpoint

При создании новой сессии прокси отправляет POST запрос на ваш endpoint с полной информацией о пользователе и токенами доступа. Приложение сохраняет данные в своё хранилище сессий, используя полученный идентификатор.

3️⃣ Через API учетных записей

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

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

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

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

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

Отсутствие app-cookies устраняет проблемы с SameSite политиками браузеров и упрощает архитектуру — приложению не нужно управлять своими сессионными cookies.

Метод 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)

Обязательная проверка подписи

⚠️ Без этой проверки приложение уязвимо

Endpoint принимает права пользователя и создаёт сессию, поэтому он отвечает до того, как сессия появилась, — то есть находится вне вашей собственной проверки авторизации. Если endpoint не проверяет подпись, любой уже вошедший пользователь может отправить в него запрос со своим sub и произвольным списком permissions и выдать себе права администратора.

IDENTYX подписывает каждый запрос к endpoint секретом вашего OIDC-клиента (Client Secret из карточки приложения) и передаёт подпись заголовком:

X-Identyx-Signature: t=1700000000,v1=29ce539761ac105288272e9de563de5451d7955df38dd478211c5c7bef85f06f
Параметр Описание
t Момент подписания, unix-время в секундах
v1 HMAC-SHA256 в нижнем регистре hex от строки «<t>.<тело запроса>», ключ — Client Secret приложения

Что обязан сделать endpoint:

  1. Взять сырое тело запроса — ровно те байты, что пришли. Повторная сериализация разобранного JSON даст другой порядок ключей и другое экранирование, и подпись не сойдётся.
  2. Посчитать hmac_sha256(client_secret, t . "." . сырое_тело) и сравнить с v1 сравнением за постоянное время (hash_equals, crypto.timingSafeEqual, hmac.compare_digest).
  3. Отвергнуть запрос, если |сейчас − t| > 300 секунд: это ограничивает повтор перехваченного запроса. Часы приложения и IDENTYX должны быть синхронизированы (NTP).
  4. Сверить X-Session-Id с полем oidc_session из тела. Заголовок подписью не покрыт, и без этой сверки чужой подписанный запрос можно переиграть в свою сессию.
  5. При любом расхождении — отказать. Запасного пути «подписи нет, но пропустим» быть не должно: он полностью обесценивает проверку.
⚠️ Смена Client Secret

Секрет один и тот же с двух сторон. Если поменять Client Secret в карточке приложения, endpoint начнёт отвергать запросы IDENTYX, и вход в приложение прекратится до тех пор, пока новый секрет не будет доставлен в приложение.

Структура объекта 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 = file_get_contents('php://input');
$data = json_decode($json, true);

// Проверка подписи. Без неё endpoint раздаёт права кому угодно.
$clientSecret = 'ваш Client Secret из карточки приложения';
$parts = [];
foreach (explode(',', $_SERVER['HTTP_X_IDENTYX_SIGNATURE'] ?? '') as $chunk) {
    $pair = explode('=', trim($chunk), 2);
    if (count($pair) === 2) {
        $parts[strtolower(trim($pair[0]))] = trim($pair[1]);
    }
}

$t = $parts['t'] ?? '';
$v1 = $parts['v1'] ?? '';

if (!ctype_digit($t) || abs(time() - (int)$t) > 300
    || !hash_equals(hash_hmac('sha256', $t . '.' . $json, $clientSecret), $v1)) {
    http_response_code(403);
    echo json_encode(['error' => 'Invalid identyx call signature']);
    exit;
}

// X-Session-Id подписью не покрыт — связываем его с подписанным телом
if ($sessionId !== null && !hash_equals((string)($data['oidc_session'] ?? ''), $sessionId)) {
    http_response_code(403);
    echo json_encode(['error' => 'Invalid identyx call signature']);
    exit;
}

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 crypto = require('crypto');

const app = express();
// Сохраняем сырое тело: подпись считается по присланным байтам, а не по JSON.stringify(req.body)
app.use(express.json({ verify: (req, res, buf) => { req.rawBody = buf; } }));

const CLIENT_SECRET = 'ваш Client Secret из карточки приложения';

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

// Проверка подписи. Без неё endpoint раздаёт права кому угодно.
function identyxSignatureIsValid(req) {
    const parts = Object.fromEntries(
        String(req.headers['x-identyx-signature'] || '')
            .split(',')
            .map((chunk) => chunk.trim().split('=', 2))
            .filter((pair) => pair.length === 2)
            .map(([key, value]) => [key.toLowerCase(), value])
    );

    if (!/^\d+$/.test(parts.t || '') || !parts.v1) return false;
    if (Math.abs(Math.floor(Date.now() / 1000) - Number(parts.t)) > 300) return false;

    const expected = crypto.createHmac('sha256', CLIENT_SECRET)
        .update(parts.t + '.')
        .update(req.rawBody)
        .digest('hex');

    const given = Buffer.from(parts.v1, 'utf8');
    const want = Buffer.from(expected, 'utf8');

    return given.length === want.length && crypto.timingSafeEqual(given, want);
}

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;

    // X-Session-Id подписью не покрыт — связываем его с подписанным телом
    if (!identyxSignatureIsValid(req) || (sessionId && sessionId !== oidc_session)) {
        return res.status(403).json({ error: 'Invalid identyx call signature' });
    }

    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):

import hashlib
import hmac
import time

from flask import Flask, request, jsonify

app = Flask(__name__)

CLIENT_SECRET = 'ваш Client Secret из карточки приложения'

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


# Проверка подписи. Без неё endpoint раздаёт права кому угодно.
def identyx_signature_is_valid(raw_body: bytes) -> bool:
    parts = {}
    for chunk in request.headers.get('X-Identyx-Signature', '').split(','):
        key, _, value = chunk.strip().partition('=')
        if value:
            parts[key.strip().lower()] = value.strip()

    t, v1 = parts.get('t', ''), parts.get('v1', '')

    if not t.isdigit() or not v1 or abs(int(time.time()) - int(t)) > 300:
        return False

    expected = hmac.new(
        CLIENT_SECRET.encode(), t.encode() + b'.' + raw_body, hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, v1)


@app.route('/api/identyx/session', methods=['POST'])
def identyx_session():
    session_id = request.headers.get('X-Session-Id')
    # Сырое тело: подпись считается по присланным байтам
    raw_body = request.get_data()
    data = request.get_json()

    # X-Session-Id подписью не покрыт — связываем его с подписанным телом
    if not identyx_signature_is_valid(raw_body) or (
        session_id and not hmac.compare_digest(str(data.get('oidc_session', '')), session_id)
    ):
        return jsonify({'error': 'Invalid identyx call signature'}), 403

    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)
✅ Важно

Endpoint должен возвращать JSON ответ {"success": "true"} при успешной обработке. Если прокси не получит этот ответ, пользователь увидит ошибку.

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

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

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

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

Способ Описание Применение
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
⚠️ Как это работает

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

Метод 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();
ℹ️ Типы учетных записей

Учетные записи могут быть двух типов:

  • personal — личные учетные записи пользователя
  • group — групповые учетные записи (доступны всем членам группы)

Личные учетные записи имеют приоритет над групповыми.

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

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

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

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

✅ Используйте X-Session-Id

Идентифицируйте пользователя по заголовку X-Session-Id, а не по собственным cookies приложения. Это устраняет проблемы с SameSite политиками браузеров.

✅ Сообщайте об ошибках

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

✅ Используйте HTTPS

Убедитесь, что endpoint для приема данных о сессии доступен по HTTPS или находится на localhost для безопасной передачи токенов.

✅ Храните токены безопасно

Храните access и refresh токены в серверной сессии, а не в cookies или localStorage на клиенте.

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

Проблема Возможная причина Решение
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. Несколько вкладок — пользователь открывает приложение в нескольких вкладках одновременно
✅ Готовы к следующему шагу?

После интеграции с прокси изучите раздел Учетные данные в интеграциях для работы с сохраненными учетными записями пользователей.