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

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

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

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

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

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

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

Метод 1: HTTP заголовки (простая интеграция)

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

Метод 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 со следующими данными:

Поле	Тип	Описание
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
// Читаем JSON из тела запроса
$json = file_get_contents('php://input');
$data = json_decode($json, true);

if ($data['action'] === 'setOidcUserInfo') {
    $userInfo = $data['user_info'];
    $userId = $userInfo['sub'];
    $username = $userInfo['preferred_username'];
    $displayName = $userInfo['name'];
    $email = $userInfo['email'];
    $permissions = $userInfo['permissions'];
    
    // Создаем или обновляем сессию пользователя в вашем приложении
    session_start();
    $_SESSION['identyx_user_id'] = $userId;
    $_SESSION['identyx_username'] = $username;
    $_SESSION['identyx_display_name'] = $displayName;
    $_SESSION['identyx_email'] = $email;
    $_SESSION['identyx_permissions'] = $permissions;
    $_SESSION['identyx_access_token'] = $data['oidc_access_token'];
    $_SESSION['identyx_session'] = $data['oidc_session'];
    
    // Создаем cookie для идентификации сессии приложения
    setcookie('app_session_id', session_id(), [
        'path' => '/',
        'httponly' => true,
        'secure' => true,
        'samesite' => 'Lax'
    ]);
    
    // Возвращаем успешный ответ
    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 session = require('express-session');

const app = express();
app.use(express.json());
app.use(session({
    secret: 'your-secret-key',
    resave: false,
    saveUninitialized: false,
    cookie: { 
        secure: true, 
        httpOnly: true,
        sameSite: 'lax'
    }
}));

app.post('/api/identyx/session', (req, res) => {
    const { action, user_info, oidc_access_token, oidc_refresh_token, oidc_session } = req.body;
    
    if (action !== 'setOidcUserInfo') {
        return res.status(400).json({ error: 'Invalid action' });
    }
    
    // Сохраняем информацию о пользователе в сессию
    req.session.identyxUserId = user_info.sub;
    req.session.identyxUsername = user_info.preferred_username;
    req.session.identyxDisplayName = user_info.name;
    req.session.identyxEmail = user_info.email;
    req.session.identyxPermissions = user_info.permissions;
    req.session.identyxAccessToken = oidc_access_token;
    req.session.identyxSessionId = oidc_session;
    
    res.json({ success: 'true' });
});

app.listen(8080);

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

from flask import Flask, request, session, jsonify

app = Flask(__name__)
app.secret_key = 'your-secret-key'

@app.route('/api/identyx/session', methods=['POST'])
def identyx_session():
    data = request.get_json()
    
    if data.get('action') != 'setOidcUserInfo':
        return jsonify({'error': 'Invalid action'}), 400
    
    user_info = data.get('user_info', {})
    
    # Сохраняем информацию о пользователе в сессию
    session['identyx_user_id'] = user_info.get('sub')
    session['identyx_username'] = user_info.get('preferred_username')
    session['identyx_display_name'] = user_info.get('name')
    session['identyx_email'] = user_info.get('email')
    session['identyx_permissions'] = user_info.get('permissions', [])
    session['identyx_access_token'] = data.get('oidc_access_token')
    session['identyx_session'] = data.get('oidc_session')
    
    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
session_start();

// Проверяем сессию приложения
if (!isset($_SESSION['identyx_user_id'])) {
    // Сессия истекла - сообщаем прокси
    http_response_code(401);
    header('X-App-Auth-Error: true');
    setcookie('app_auth_error', 'true', 0, '/');
    echo 'Сессия истекла';
    exit;
}

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

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

app.use((req, res, next) => {
    // Проверяем сессию приложения
    if (!req.session.identyxUserId) {
        // Сессия истекла - сообщаем прокси
        res.status(401);
        res.header('X-App-Auth-Error', 'true');
        res.cookie('app_auth_error', 'true', { path: '/' });
        return res.send('Сессия истекла');
    }
    
    // Сессия валидна - продолжаем
    next();
});

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

from flask import session, make_response

@app.before_request
def check_session():
    # Проверяем сессию приложения
    if 'identyx_user_id' not in session:
        # Сессия истекла - сообщаем прокси
        response = make_response('Сессия истекла', 401)
        response.headers['X-App-Auth-Error'] = 'true'
        response.set_cookie('app_auth_error', 'true', path='/')
        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 с информацией о пользователе
6. Приложение создает сессию — ваше приложение создает свою сессию и возвращает cookie
7. Работа с приложением — пользователь получает доступ к приложению
8. Обновление токенов — прокси автоматически обновляет токены при истечении
9. Завершение сессии — пользователь выходит или сессия истекает по таймауту

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

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

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

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

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

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