Инструкция интеграции для портала

@startuml Scenario_A_First_Login
title Сценарий A — iFrame + postMessage: первый вход

skinparam sequenceArrowThickness 1.5
skinparam participantPadding 12
skinparam boxPadding 10
skinparam roundcorner 6

actor "Пользователь" as User

box "Браузер" #f5f5f5
  participant "Портал\n(Frontend)" as ParentFE
  participant "iFrame\n(App Frontend)" as AppFE
end box

participant "Бэкенд\nпортала" as ParentBE
participant "App API\n(Express)" as AppAPI
database "Supabase\n(PostgreSQL)" as DB

autonumber

== Загрузка ==

User -> ParentFE: Открывает страницу портала
ParentFE -> AppFE: <iframe src="...?view_mode=embedded&provider=ciam">
activate AppFE

AppFE -> AppFE: EMBEDDED_MODE = true\nproviderId = 'ciam'
AppFE -> AppFE: Регистрирует listener message

== Handshake ==

AppFE -> ParentFE: postMessage({type:'IFRAME_READY', providerId:'ciam'}, portalOrigin)

note right of ParentFE
  Портал не должен отправлять
  ваучер до IFRAME_READY.
end note

== Выпуск ваучера ==

ParentFE -> ParentBE: GET /api/sso-voucher
activate ParentBE
ParentBE -> ParentBE: jwt.sign({sub, provider, type, jti, iss, aud})\nTTL = 60s
ParentBE --> ParentFE: {providerId:'ciam', voucher:'eyJ...'}
deactivate ParentBE

ParentFE -> AppFE: postMessage({type:'SSO_VOUCHER', providerId, voucher}, appOrigin)

== Обмен ваучера ==

AppFE -> AppFE: Проверяет event.origin\nПроверяет event.source\nПроверяет providerId

AppFE -> AppAPI: POST /auth/sso/exchange\n{providerId:'ciam', voucher:'eyJ...'}
activate AppAPI

AppAPI -> DB: SELECT * FROM sso_providers WHERE id='ciam'
DB --> AppAPI: {method:'rs256', public_key, kid, issuer, audience}
AppAPI -> AppAPI: verify signature, check claims
AppAPI -> DB: INSERT INTO used_sso_voucher_jtis
DB --> AppAPI: OK
AppAPI -> DB: Найти или создать SSO-пользователя
DB --> AppAPI: {id, email, role}
AppAPI --> AppFE: {accessToken, user}
deactivate AppAPI

== Инициализация ==

AppFE -> AppFE: setAccessToken(token, memoryOnly=true)\nsetUser(user)
AppFE --> User: Приложение загружено внутри iframe

deactivate AppFE
@enduml

@startuml Scenario_A_Refresh
title Сценарий A — iFrame: обновление токена через новый ваучер

skinparam sequenceArrowThickness 1.5
skinparam participantPadding 12
skinparam roundcorner 6

actor "Пользователь" as User

box "Браузер" #f5f5f5
  participant "Портал\n(Frontend)" as ParentFE
  participant "iFrame\n(App Frontend)" as AppFE
end box

participant "Бэкенд\nпортала" as ParentBE
participant "App API\n(Express)" as AppAPI
database "Supabase" as DB

autonumber

User -> AppFE: Делает действие
AppFE -> AppAPI: REST запрос\nAuthorization: Bearer <expired>
AppAPI --> AppFE: 401 Unauthorized

AppFE -> ParentFE: postMessage({type:'REQUEST_TOKEN_REFRESH', providerId:'ciam'}, portalOrigin)

ParentFE -> ParentBE: GET /api/sso-voucher
activate ParentBE
ParentBE -> ParentBE: Новый ваучер с новым jti
ParentBE --> ParentFE: {providerId, voucher:'eyJ...new...'}
deactivate ParentBE

ParentFE -> AppFE: postMessage({type:'SSO_VOUCHER_REFRESHED', providerId, voucher}, appOrigin)

AppFE -> AppAPI: POST /auth/sso/exchange\n{providerId, voucher}
activate AppAPI
AppAPI -> DB: Проверка подписи, jti, claims
DB --> AppAPI: OK
AppAPI --> AppFE: {accessToken:'renewed', user}
deactivate AppAPI

AppFE -> AppFE: setAccessToken(newToken, memoryOnly=true)
AppFE -> AppAPI: Повтор исходного запроса
AppAPI --> AppFE: 200 OK

AppFE --> User: Данные без перезагрузки
@enduml

@startuml Scenario_B_Redirect
title Сценарий B — Прямой URL: вход через redirect-flow

skinparam sequenceArrowThickness 1.5
skinparam participantPadding 12
skinparam boxPadding 10
skinparam roundcorner 6

actor "Пользователь" as User
participant "Браузер\n(App Frontend)" as AppFE
participant "App API\n(Express)" as AppAPI
participant "Бэкенд\nпортала" as PortalBE
database "Supabase" as DB

autonumber

== Начальная загрузка ==

User -> AppFE: Открывает https://demo.routemax.ru
AppFE -> AppAPI: GET /auth/sso/providers
AppAPI -> DB: SELECT id, name FROM sso_providers\nWHERE enabled=true AND authorization_url IS NOT NULL
DB --> AppAPI: [{id:'ciam', name:'CIAM Portal'}]
AppAPI --> AppFE: {providers:[{id:'ciam', name:'CIAM Portal'}]}
AppFE --> User: Показывает кнопку\n"Войти через CIAM Portal"

== Инициация SSO ==

User -> AppFE: Клик "Войти через CIAM Portal"
AppFE -> AppAPI: GET /auth/sso/start?provider=ciam&return_url=/history
activate AppAPI
AppAPI -> DB: SELECT authorization_url FROM sso_providers\nWHERE id='ciam' AND enabled=true
DB --> AppAPI: {authorization_url:'https://portal.corp.ru/sso/authorize'}
AppAPI -> AppAPI: validate return_url => '/history'\ngenerate opaque state
AppAPI --> AppFE: Set-Cookie sso_state=...\nSet-Cookie sso_provider=ciam\nSet-Cookie sso_return_url=/history\n302 -> portal /sso/authorize?state=...
deactivate AppAPI

== Портал ==

AppFE -> PortalBE: GET /sso/authorize?state=...
activate PortalBE
PortalBE -> PortalBE: Пользователь уже залогинен\nна портале
PortalBE -> PortalBE: Не интерпретирует state\nВыпускает новый JWT-ваучер\n{sub, provider:'ciam', type, jti, iss, aud}
PortalBE --> AppFE: 302 -> /auth/sso/callback?voucher=eyJ...&state=...
deactivate PortalBE

note right of PortalBE
  Для v1 параметр voucher в query string
  должен маскироваться в proxy/application logs.
end note

== Callback ==

AppFE -> AppAPI: GET /auth/sso/callback?voucher=eyJ...&state=...
activate AppAPI
AppAPI -> AppAPI: Проверяет state cookie\nБерёт providerId из sso_provider cookie
AppAPI -> DB: Загружает конфиг provider='ciam'
DB --> AppAPI: {method:'rs256', public_key:'...', kid:'portal-main-2026-01', issuer, audience}
AppAPI -> AppAPI: Проверяет подпись и claims\nСравнивает payload.provider === 'ciam'
AppAPI -> DB: INSERT used_sso_voucher_jtis(provider_id,jti,expires_at)
DB --> AppAPI: OK
AppAPI -> DB: Найти или создать SSO-пользователя
DB --> AppAPI: {id:'uuid-123', email:'sso:ciam:CONT_001@internal'}
AppAPI --> AppFE: Set-Cookie refreshToken=...\n302 -> https://demo.routemax.ru/history?sso=1
deactivate AppAPI

== Bootstrap через refresh-cookie ==

AppFE -> AppFE: Видит ?sso=1\nsetHasSession()\nhistory.replaceState('/history')
AppFE -> AppAPI: POST /auth/refresh\nCookie: refreshToken=...
activate AppAPI
AppAPI --> AppFE: {accessToken:'eyJ...', user:{id,email,role}}
deactivate AppAPI

AppFE -> AppFE: setAccessToken(accessToken)\nsetUser(user)
AppFE --> User: Пользователь залогинен\nи видит /history
@enduml

@startuml Scenario_B_CSRF_Attack
title Негативный сценарий: CSRF на callback

skinparam sequenceArrowThickness 1.5
skinparam roundcorner 6

actor "Атакующий" as Attacker
participant "Браузер жертвы" as Victim
participant "App API" as AppAPI

autonumber

note over Attacker, AppAPI
  Атакующий заставляет браузер жертвы
  выполнить callback с чужим ваучером.
end note

Attacker -> Victim: /auth/sso/callback?voucher=X&state=ATTACKER_STATE
Victim -> AppAPI: GET callback\nCookie: sso_state=VICTIM_STATE
activate AppAPI
AppAPI -> AppAPI: ATTACKER_STATE != VICTIM_STATE
AppAPI --> Victim: 400 Invalid SSO state
deactivate AppAPI

note over Victim, AppAPI
  Callback отклонён. Жертва не залогинена.
end note
@enduml

@startuml Flow_Comparison
title Сравнение потоков: embedded vs redirect

skinparam activityBorderThickness 1.5
skinparam roundcorner 8

|Сценарий A — iFrame|
start
:Портал загружает iframe\n?view_mode=embedded&provider=ciam;
:App -> IFRAME_READY;
:Портал -> SSO_VOUCHER\nproviderId + voucher;
:POST /auth/sso/exchange;
:Проверка подписи и jti;
:Токен -> память;
:Сессией управляет портал;
stop

|Сценарий B — direct URL|
start
:Пользователь открывает app напрямую;
:GET /auth/sso/providers;
:Клик -> GET /auth/sso/start;
:Cookies state/provider/return_url;
:Redirect на портал (только state);
:Портал -> callback c voucher + state;
:Проверка state/provider/jti;
:Refresh-cookie + ?sso=1;
:Frontend -> POST /auth/refresh;
:Полноценная сессия;
stop
@enduml