🚀 RBP Platform Architecture•Verze 2.0.1•● Autorizováno pro Produkci & Sandbox

API Gateway v2 & Identity (IAM)

Komplexní vývojářská příručka pro integraci aplikací s Retailys Business Platform: OAuth 2.0 autentizace s PKCE S256 (RFC 7636), Zero-Trust API směrování, SDK v Pythonu a Next.js, interaktivní diagramy a chybová matice.

Sandbox Gateway: https://api.sandbox.retailys.com/v2/
IAM Server: https://api.sandbox.retailys.com/v2/iam/
🏛️
Architektura
Úvod a přehled architektury platformy RBP
🏛️
Kapitola 1 • Architektura

Úvod a přehled architektury platformy RBP

Úvodní představení Retailys Business Platform, architektonických standardů RFC 6749, rolí aktérů, multi-doménového Single Sign-On (SSO) a Zero-Trust modelu.

1.1

Architektonické standardy a bezpečnostní principy

Retailys Business Platform (RBP) je moderní modulární e-commerce operační systém a ekosystém mikroslužeb. Platforma poskytuje komplexní správu produktových dat (PIM), digitálních aktiv (DAM), vztahů se zákazníky (CRM), objednávek (OMS), skladů a logistiky (WMS), pokladních systémů (POS), fakturace (Billing) a AI asistentů.

Tato dokumentace vychází z mezinárodních bezpečnostních standardů (v souladu s RFC 6749, RFC 7636, RFC 7519, RFC 8414 a OpenID Connect Core 1.0). Základními pilíři jsou:

▸
Striktní vymezení rolí: Jasně definované odpovědnosti mezi koncovým uživatelem, klientskou aplikací (Relying Party), centrálním autorizačním serverem a API Gateway / Resource Serverem.
▸
Kanonické deklarace endpointů: Veškeré adresy jsou odvozeny z discovery dokumentu .well-known/openid-configuration.
▸
Krok-za-krokem integrační postupy: Od sestavení autorizační URL přes PKCE S256 hash až po proaktivní obnovu tokenů.
▸
Exhaustivní chybová matice: Tabulkový přehled všech standardních i doménových chyb s popisem příčin a nápravných kroků.
1.2

Role aktérů v architektuře

V rámci komunikace s RBP Platformou vystupují čtyři klíčové entity:

📋 Role aktérů v architektuře
Entita / RoleStandardní označeníPopis a implementace v RBP
Uživatel / Vlastník zdrojůResource OwnerKoncový uživatel (obchodník, operátor skladu, administrátor) přistupující přes webový prohlížeč nebo mobilní aplikaci.
Klientská aplikaceRelying Party (RP) / ClientNext.js SPA frontendy (os, app, admin, ai, chat, backstore), mobilní aplikace, POS terminály nebo backendové servery a AI agenti.
Autorizační serverAuthorization ServerSlužba Retailys Identity (IAM) vystavená na /v2/iam/connect/ plně implementující standardy RFC 6749, RFC 7636 (PKCE), RFC 7519 (JWT) a RFC 8414 (Discovery).
API Gateway & Resource ServerResource Server (RS)API Gateway v2 (Resource Server & Reverse Proxy dle RFC 6749 / OpenAPI 3.1.0) směrující požadavky na mikroslužby (PIM, DAM, OMS atd.).
1.3

Multi-doménová krajina a Single Sign-On (SSO)

Všechny webové frontendy platformy Retailys operují na vyhrazených subdoménách jednotné domény .sandbox.retailys.com (respektive produkční .retailys.com):

ℹ️Sdílení Relace

Díky nastavení cookies na doménu .sandbox.retailys.com dochází k okamžitému sdílení přihlašovací relace mezi všemi šesti subdoménami bez nutnosti opakovaného zadávání přihlašovacích údajů.

Multi-doménová Architektura a SSO Tok
text
┌─────────────────────────────────────────────────────────────────────────────────┐
│                      RBP MULTI-DOMAIN PLATFORM LANDSCAPE                        │
└─────────────────────────────────────────────────────────────────────────────────┘
         │
         ├── os.sandbox.retailys.com        (OS App Hub & Launcher)
         ├── app.sandbox.retailys.com       (Katalogy, PIM, WMS & Objednávky)
         ├── admin.sandbox.retailys.com     (Správa Tenantů, Uživatelů a Rolí)
         ├── chat.sandbox.retailys.com      (Multi-Agent Chatlys)
         ├── ai.sandbox.retailys.com        (AI Studio & Automatizace)
         └── backstore.sandbox.retailys.com (Sklad a Expedice)
         │
         ▼ (HTTPS Cross-Subdomain SSO Cookie Domain: .sandbox.retailys.com)
┌─────────────────────────────────────────────────────────────────────────────────┐
│                   API GATEWAY v2 (api.sandbox.retailys.com/v2/)                 │
└─────────────────────────────────────────────────────────────────────────────────┘
         │
         ├── /v2/iam/*          ──► Retailys Identity (IAM Autorizační Server + REST API)
         ├── /v2/pim/*          ──► Product Information Management (:8001)
         ├── /v2/dam/*          ──► Digital Asset Management (:8002)
         ├── /v2/crm/*          ──► Customer Relationship Management
         ├── /v2/oms/*          ──► Order Management System
         ├── /v2/wms/*          ──► Warehouse Management System
         ├── /v2/pos/*          ──► Point of Sale Backend
         ├── /v2/billing/*      ──► Billing & Subscription Engine
         └── /v2/catalogs/*     ──► Master Catalogs & Localization
1.4

Zero-Trust bezpečnostní model

API Gateway v2 implementuje striktní Zero-Trust architekturu:

1. Žádný příchozí požadavek z internetu nesmí nést předvyplněné interní hlavičky identity (x-retailys-*, x-user-*, x-tenant-*, x-roles, x-permissions). Tyto hlavičky jsou na proxy bráně bezpodmínečně smazány.

2. Přítomnost hlavičky x-middleware-subrequest je vyhodnocena jako pokus o zneužití zranitelnosti CVE-2025-29927 a okamžitě zablokována kódem 403 Forbidden.

3. Teprve po úspěšném kryptografickém ověření OAuth 2.0 Bearer JWT tokenu Gateway injektuje ověřenou identitu do upstream komunikace.

⚡Zero-Trust Sanitizace

Veškerá klientská volání procházejí Ingress fází sanitace, kde jsou eliminovány neautorizované hlavičky před dosažením mikroslužeb.