Інтеграція Superset із застосунком: Guest Token та RLS

Вбудовування Superset-дашбордів: Guest Token та RLS

Ми стикалися з ситуацією: у клієнта — fintech-стартап із 5 відділами (продажі, маркетинг, фінанси, HR, підтримка). Кожен відділ хотів бачити свою аналітику в загальному BI-порталі, але дані суворо розмежовані. Apache Superset — потужний інструмент із відкритим кодом, але «з коробки» його не вбудувати в сторонній застосунок без додаткового налаштування. Без правильної конфігурації Guest Token та Row Level Security (RLS) усі дашборди або бачать усі дані, або не завантажуються через CORS-помилки. Ми вирішили задачу, вбудувавши Superset через Embedded SDK, і тепер ділимося досвідом. Налаштування зайняло 3 дні, результат — кожен відділ бачить лише свої метрики, а IT-відділ керує доступом централізовано. Економія на ліцензіях порівняно з платними BI-рішеннями може становити від 300 000 до 500 000 гривень на рік.

Які проблеми вирішує вбудовування Superset?

Основний біль — розмежування даних між відділами. Без RLS доводилося створювати окремі дашборди для кожного відділу, що збільшувало час розробки на 2 тижні та робило систему негнучкою. Superset з Embedded SDK дозволяє вбудувати один дашборд і динамічно фільтрувати дані через Guest Token. Додатково вирішуються:

• CORS-помилки — неправильна конфігурація блокує завантаження дашбордів.
• Управління доступом — централізоване через ваш застосунок.
• Продуктивність — середній час завантаження дашборду скоротився на 40% після налаштування кешування.

Як працює вбудовування через Embedded SDK?

Superset використовує Embedded SDK та Guest Token для безпечного вбудовування. Guest Token — тимчасовий JWT-ключ із прив'язкою до користувача та дашборду. Як зазначено в офіційній документації Superset: Guest Token is a time-limited JWT used for embedding dashboards securely. Ми налаштовуємо endpoint у нашому застосунку, який видає токен через API Superset. На відміну від Metabase, де потрібно налаштовувати JWT-проксі, Superset дозволяє передавати RLS-умови прямо в токен. Це дає гнучкість: дані фільтруються на рівні SQL-запиту.

Конфігурація Superset

У superset_config.py:

FEATURE_FLAGS = {
    "EMBEDDED_SUPERSET": True,
    "ENABLE_TEMPLATE_PROCESSING": True
}

CORS_OPTIONS = {
    'supports_credentials': True,
    'origins': ['https://your-app.com']
}

SESSION_COOKIE_SAMESITE = None
SESSION_COOKIE_SECURE = True
SESSION_COOKIE_HTTPONLY = True

Ключові моменти: EMBEDDED_SUPERSET вмикає вбудовування; CORS — лише ваш домен; куки SameSite=None обов'язкові для iframe.

Генерація Guest Token

async function getSupersetGuestToken(
    dashboardId: string,
    userId: string,
    userEmail: string
): Promise<string> {
    // Отримати admin access token
    const loginResponse = await fetch(`${SUPERSET_URL}/api/v1/security/login`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            username: process.env.SUPERSET_ADMIN_USER,
            password: process.env.SUPERSET_ADMIN_PASSWORD,
            provider: 'db',
            refresh: false
        })
    });
    const { access_token } = await loginResponse.json();

    // Отримати Guest Token для конкретного дашборду
    const guestResponse = await fetch(`${SUPERSET_URL}/api/v1/security/guest_token/`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${access_token}`
        },
        body: JSON.stringify({
            user: {
                username: userId,
                first_name: userEmail.split('@')[0],
                last_name: ''
            },
            resources: [
                {
                    type: 'dashboard',
                    id: dashboardId
                }
            ],
            rls: [
                {
                    clause: `organization_id = '${getOrgId(userId)}'`
                }
            ]
        })
    });
    const { token } = await guestResponse.json();
    return token;
}

Зверніть увагу: ми використовуємо rls з динамічним organization_id. Це гарантує, що користувачі з різних компаній не побачать чужі дані.

React-компонент через SDK

npm install @superset-ui/embedded-sdk 

import { embedDashboard } from '@superset-ui/embedded-sdk';
import { useEffect, useRef } from 'react';

function SupersetDashboard({ dashboardId }) {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!containerRef.current) return;

    const embed = embedDashboard({
      id: dashboardId,
      supersetDomain: process.env.NEXT_PUBLIC_SUPERSET_URL,
      mountPoint: containerRef.current,
      fetchGuestToken: () =>
        fetch(`/api/superset/guest-token?dashboardId=${dashboardId}`)
          .then(r => r.json())
          .then(d => d.token),
      dashboardUiConfig: {
        hideTitle: true,
        hideTab: false,
        filters: { expanded: false }
      }
    });

    return () => embed.unmount();
  }, [dashboardId]);

  return (
    <div
      ref={containerRef}
      className="superset-container w-full rounded-xl overflow-hidden"
      style={{ height: '600px' }}
    />
  );
}

Компонент перевикористовується для будь-якого дашборду — достатньо передати ID.

Як налаштувати Row Level Security?

Через rls у Guest Token запити в Superset автоматично фільтруються на рівні SQL. Superset додасть до кожного запиту WHERE organization_id = 'user-org-id'. Користувач фізично не може побачити дані інших організацій. Це альтернатива налаштуванню окремих ролей у Superset — ми керуємо доступом централізовано зі свого застосунку. В одному з проектів RLS скоротив час розмежування прав із двох тижнів до двох днів.

Коли варто обирати Superset замість Metabase?

Superset виграє у гнучкості кастомізації та вартості — економія на ліцензіях порівняно з платними BI може становити від 300 000 до 500 000 гривень на рік. Якщо вам потрібна проста аналітика без складних RLS, Metabase простіше в налаштуванні. Але для глибокої кастомізації та розмежування даних Superset — оптимальний вибір.

Процес і строки роботи

1. Аналітика — вивчаємо ваші дашборди та користувацькі ролі.
2. Налаштування Superset — конфігурація CORS, Guest Token, RLS.
3. Розробка бекенду — endpoint для видачі токенів (зазвичай на Node.js або Django).
4. Інтеграція SDK — вбудовування компонента в React/Vue/Angular.
5. Тестування — перевірка прав доступу та завантаження.
6. Деплой — налаштування CI/CD та моніторингу.

У результаті ви отримуєте документацію з конфігурації, API для видачі токенів, схему RLS, готовий код компонента та навчання команди. Підтримка протягом 2 тижнів після запуску.

Типові помилки при вбудовуванні

• Ігнорування CORS — дашборд не завантажується. Переконайтеся, що в origin вказано точний домен застосунку, включаючи протокол.
• Неправильний SameSite для кукі — якщо не встановити None, iframe заблокує куки.
• Неправильні RLS-умови — без валідації користувачі можуть побачити чужі дані. Завжди перевіряйте, що clause підставляється коректно.
• Відсутність обробки закінчення терміну дії Guest Token — токен живе обмежений час (за замовчуванням 30 хвилин). Налаштуйте автоматичне оновлення на стороні клієнта.

Зв'яжіться з нами — оцінимо ваш проект за 1 день і запропонуємо оптимальне рішення. Замовте налаштування Superset із готовим модулем безпеки та отримайте консультацію з інтеграції з будь-яким фреймворком.