Интеграция с корпоративными порталами и сайтами (iFrame API)

Разработчикам / Обеспечение взаимодействия BOOCO с другими ИТ-системами

Введение

iFrame API можно использовать для интеграции BOOCO в корпоративные порталы и другие сайты. Например, если вы хотите отображать карту офиса на корпоративном портале, то iFrame API позволяет это сделать.

Для работы BOOCO iFrame API:

• BOOCO Astra (v 2.18.0 или новее) должен быть установлен и доступен по протоколу https;
• корпоративный сайт должен поддерживать авторизацию на основе JWT-токенов, которые подписываются открытым или закрытым ключом;
• для авторизации через iFrame API пользователи должны быть добавлены в BOOCO: необходимо настроить синхронизацию пользователей сервера BOOCO и службы каталогов или добавить пользователей в систему другим способом.

Чтобы интегрировать карту офиса и другие модули в корпоративный портал, выполните следующие шаги:

• Настройте микросервис bosql, чтобы он поддерживал внешнюю авторизацию, и передайте в него открытый или закрытый ключ (для проверки подписи токенов авторизации).
• На странице, которая будет отображать iFrame:
• настройте политики контента;
• добавьте iFrame;
• вызовите метод для отправки JWT-токена и настройте регулярное обновление токенов;
• вызовите метод для настройки отображения iFrame;
• при необходимости можно переписать окна бронирования.

Настройка CSP (content security policy)

Если корпоративный портал (хост) использует политику безопасности контента (CSP), то необходимо дополнить его правила:

• в заголовок ответа (если используется) добавьте: Content-Security-Policy: frame-src https://<адрес сервера BOOCO>;
• в теге meta (если используется) укажите:
Copy

<meta
	http-equiv="Content-Security-Policy"
	content="frame-src https://<адрес сервера BOOCO>;"
>

Интеграция iFrame-модулей на страницу корпоративного портала

1. Вставьте iFrame в html-страницу корпоративного портала:
Copy

<iframe src="https://<адрес сервера BOOCO>/iframe-module/<module-name>"/>

Возможные значения module-name:

• map — модуль карт офиса;
• resources — модуль ресурсов.
2. Отправьте сообщение инициализации модуля.
‣
Пример с картой офиса
‣
Пример с ресурсами
3. Отправьте сообщение для авторизации.

Необходимо авторизовать пользователя в iFrame, отправив в iFrame JWT-токен и email пользователя (микросервис bosql должен быть настроен, пользователь должен быть уже добавлен на сервер BOOCO).

Copy

const authMessage: IMessageAuth = { 
	type: 'auth', 
	data: {
		token: authJWT, // JWT-токен авторизации
		email: useremail // email пользователя
	}
}

window.postMessage(
	authMessage,
	'https://<адрес сервера BOOCO>/iframe-module/<module-name>',
)

⚠️
Сообщение для авторизации необходимо отправлять каждый раз, когда корпоративный портал получает новый JWT-токен.

Описание конфигурации модулей

Получение сообщений от iFrame на хосте

// Устанавливаем слушатель сообщений
window.addEventListener("message", (event: MessageEvent<ICommonMessage>) => {
  // Если сообщение пришло не от доверенного домена — проигнорировать
  if (event.origin !== 'https://<адрес сервера BOOCO>') return;
  
  // Обрабатываем сообщения по type
  switch (event.data.type) {
		case 'loaded':
			// iframe-модуль готов принимать postMessage сообщения
			// Можно отправить сообщение "init" и "auth"
			break;
		case 'resource-selected':
			// Обрабатываем
			break;
		case 'unauthorized':
			// Обрабатываем
			break;
		default:
			break;
	}
}

На текущий момент iFrame-модули отправляют несколько типов сообщений:

Типизация