Настройка сервисов авторизации#

Если вы планируете использовать авторизацию по номеру телефона, необходимо зарегистрироваться на сайте минимум одного из перечисленных поставщиков услуг доставки SMS и получить данные для авторизации. В разделе представлена информация об интеграции со следующими поставщиками:

СМС-Агент;
Twilio;
Vonage.

Если вы планируете использовать авторизацию по электронной почте, необходимо получить следующие данные SMTP-сервера для отправки писем у вашего провайдера электронной почты:

адрес почтового сервера для исходящих писем;
тип шифрования;
порт для исходящих писем;
логин почтового ящика;
пароль для внешнего приложения.

В разделе представлена информация о настройке следующих почтовых сервисов:

Gmail;
Яндекс.

Если вы планируете использовать авторизацию через Single Sign-On, необходимо настроить интеграцию SSO-провайдера с Compass On-premise по протоколу OpenID Connect и получить следующие данные для авторизации:

ID и секретный ключ клиентского приложения, зарегистрированные в SSO-провайдере;
ссылка на метаданные SSO-провайдера;
название атрибутов учетной записи SSO.

В разделе представлена информация об интеграции со следующими SSO-провайдерами:

Active Directory Federation Services (AD FS);
Okta;
Keycloak.

Подключение провайдера СМС-Агент#

Провайдер СМС-Агент подключается в три шага:

Шаг 1: Регистрация аккаунта.
Шаг 2: Предоставление данных об организации.
Шаг 3: Получение данных для настройки серверной части Compass On‑premise.

Шаг 1: Регистрация аккаунта#

Перейдите на страницу регистрации сервиса СМС-Агент и заполните все необходимые поля.
Подтвердите номер телефона с помощью SMS‑кода.
Заполните все необходимые поля, затем подтвердите создание аккаунта.
Перейдите на главную страницу Личного кабинета, нажав на кнопку «Личный кабинет».
При переходе в личный кабинет откроется страница информации о счете. Далее вам поступит звонок от персонального менеджера для подтверждения регистрации.
Если персональный менеджер вам не позвонит, для создания API-аккаунта необходимо перейти в раздел «API-интерфейс». В нем вы найдете ссылку на контактные данные персонального менеджера.
В разделе «Справка» также можно найти контактные данные вашего персонального менеджера, чтобы связаться с ним по дальнейшим шагам подключения.

Шаг 2: Предоставление данных об организации#

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

Шаг 3: Получение необходимых данных для подключения#

После завершения регистрации специалист провайдера отправит login и password для вашего API-аккаунта.
Для подключения провайдера СМС-Агент укажите значения login и password в соответствующие поля при заполнении файла конфигурации SMS-сервиса во время установки серверной части приложения:
```
sms_agent.login: <login>
sms_agent.password: <password>
```

Подключение провайдера Twilio#

Внимание

Для загрузки сайта провайдера может потребоваться VPN.
Российские телефонные номера не поддерживаются провайдером при регистрации.
Провайдер не работает с российскими банковскими картами.

Подключение провайдера Twilio состоит из шести шагов:

Шаг 1: Регистрация аккаунта.
Шаг 2: Настройка тестовой отправки SMS (опционально).
Шаг 3: Оплата и обновление аккаунта.
Шаг 4: Покупка номера для отправки SMS.
Шаг 5: Настройка номера.
Шаг 6: Получение необходимых данных в личном кабинете Twilio.

Шаг 1: Регистрация#

Перейдите на страницу регистрации и заполните все необходимые поля. Затем подтвердите создание аккаунта.

Внимание

Российские номера не поддерживаются.
Подтвердите личный номер телефона. Номер будет использоваться для получения тестовых сообщений от Twilio в пробном режиме.
Предоставьте ответы на вопросы для настройки аккаунта после подтверждения личного номера.
После завершения регистрации, откроется панель мониторинга проекта в консоли Twilio. Здесь вы получите доступ к бесплатной версии аккаунта Twilio, где сможете настроить тестовый телефон и проверить отправку SMS через консоль.

Шаг 2: Настройка тестовой отправки SMS (опционально)#

Для отправки тестового SMS вам необходимо получить пробный номер телефона.
С подробной инструкцией настройки номеров для отправки SMS можно ознакомиться в кратком руководстве по обмену сообщениями.

Шаг 3: Оплата и активация платного тарифа#

Для дальнейшей работы с телефонными номерами Twilio необходимо активировать платный тариф и заполнить данные для оплаты.

Внимание

Российские банковские карты не поддерживаются.

Шаг 4: Покупка номера для отправки SMS#

Для подключения телефонного номера Twilio с функцией SMS необходимо его приобрести. Перейдя на страницу «Купить номер», установите флажок «SMS» и нажмите «Поиск».
Отобразится список доступных телефонных номеров. Выберите предпочтительный номер и нажмите «Купить», чтобы добавить его в свою учетную запись.

Шаг 5: Настройка номера Twilio#

Настройка купленного номера Twilio аналогична настройке тестового номера из шага 2.
С подробной инструкцией настройки номеров для отправки SMS можно ознакомиться в кратком руководстве по обмену сообщениями.
Далее необходимо зарегистрировать имя (Alphanumeric), которое будет указано как «отправитель». С информацией по настройке и регистрации Alphanumeric Sender ID можно ознакомиться в разделе Как регистрировать Alphanumeric Sender ID.

Шаг 6: Получение необходимых данных в личном кабинете Twilio#

Для подключения провайдера Twilio укажите значения Account SID, Auth Token и Alphanumeric в соответствующие поля при заполнении файла конфигурации SMS-сервиса во время установки серверной части приложения:
```
twilio.app_name: <Alphanumeric>
twilio.account_sid: <Account SID>
twilio.account_auth_token: <Auth Token>
```

Подключение провайдера Vonage#

Внимание

Для загрузки сайта провайдера может потребоваться VPN.
Провайдер не работает с российскими банковскими картами.

Подключение провайдера Vonage состоит из пяти шагов:

Шаг 1: Регистрация аккаунта.
Шаг 2: Настройка тестовой отправки SMS (опционально).
Шаг 3: Оплата и активация платного тарифа.
Шаг 4: Покупка номера для отправки SMS.
Шаг 5: Получение необходимых данных в личном кабинете Vonage.

Шаг 1: Регистрация#

Перейдите на страницу регистрации и заполните все необходимые поля.
Подтвердите электронную почту и номер телефона.

Шаг 2: Настройка тестовой отправки SMS (опционально)#

После завершения регистрации, откроется стартовая страница настройки аккаунта. Выберите «Yes» в ответе на вопрос «Are you a developer?».
Нажмите на раздел с названием «SMS».
Перейдите на главную страницу личного кабинета, кликнув на логотип в левом верхнем углу экрана.

Шаг 3: Оплата и активация платного тарифа#

Для дальнейшей работы с телефонными номерами Vonage необходимо активировать платный тариф и заполнить данные для оплаты.

Внимание

Российские банковские карты не поддерживаются.

Шаг 4: Покупка номера для отправки SMS#

Для подключения телефонного номера Vonage с функцией SMS необходимо его приобрести. Перейдя в раздел Build & Manage на страницу Buy Numbers, установите фильтр «SMS» и нажмите «Поиск».

Шаг 5: Получение необходимых данных в личном кабинете Vonage#

После покупки номера перейдите на главную страницу Vonage API. На дашборде будут отображены данные для подключения SMS. Значения API key и API Secret потребуются при настройке серверной части Compass On‑premise.
Для подключения провайдера Vonage укажите значения API key и API Secret в соответствующие поля при заполнении файла конфигурации SMS-сервиса во время установки серверной части приложения:

vonage.api_key: <API key>
vonage.api_secret: <API Secret>

Подключение почты Gmail#

Почтовый сервис Gmail подключается в четыре шага:

Шаг 1: Регистрация аккаунта.
Шаг 2: Включение двухэтапной аутентификации.
Шаг 3: Создание пароля приложения.
Шаг 4: Получение данных для настройки серверной части Compass On‑premise.

Шаг 1: Регистрация аккаунта#

Перейдите на страницу регистрации сервиса Gmail и заполните все необходимые поля.
Придумайте пароль и завершите создание аккаунта.
После завершения создания аккаунта откроется главная страница.

Шаг 2: Включение двухэтапной аутентификации#

Перейдите в раздел «Безопасность», нажмите на кнопку «Двухэтапная аутентификация».
Нажмите кнопку «Начать», чтобы перейти к настройке.
Введите номер телефона и нажмите кнопку «Далее».
Подтвердите номер телефона проверочным кодом и нажмите кнопку «Далее».
Завершите настройку двухэтапной аутентификации нажатием кнопки «Включить». Откроется страница раздела «Безопасность».

Шаг 3: Создание пароля приложения#

Перейдите в раздел настройки двухэтапной аутентификации. Может потребоваться ввод пароля от аккаунта.
Нажмите на пункт «Пароли приложений» в нижней части раздела двухэтапной аутентификации.
Введите название приложения, например «Compass On‑premise». Нажмите кнопку «Создать».
После подтверждения названия приложения будет создан пароль приложения. Скопируйте и сохраните пароль, он потребуется далее для настройки серверной части приложения.

Шаг 4: Получение данных для настройки серверной части Compass On‑premise#

Для завершения подключения почты Gmail укажите ваш email и пароль приложения в соответствующие поля при заполнении файла конфигурации почтового сервиса во время установки серверной части приложения:

smtp.host: "smtp.gmail.com"
smtp.username: "your_email@gmail.com"
smtp.password: "пароль приложения"
smtp.from: "your_email@gmail.com"

Подключение почты Яндекс#

Почтовый сервис Яндекс подключается в четыре шага:

Шаг 1: Регистрация аккаунта.
Шаг 2: Создание пароля приложения.
Шаг 3: Разрешение доступа к почтовому ящику.
Шаг 4: Получение данных для настройки серверной части Compass On‑premise.

Шаг 1: Регистрация аккаунта#

Перейдите на страницу регистрации сервиса Яндекс и заполните все необходимые поля.
Придумайте пароль и завершите создание аккаунта.
После завершения создания аккаунта откроется главная страница.

Шаг 2: Создание пароля приложения#

Перейдите в раздел «Безопасность». Нажмите на пункт «Пароли приложений» в нижней части раздела.
Выберите пункт «Почта». Откроется экран ввода имени пароля приложения.
Введите имя пароля приложения, например «Compass On‑premise». Нажмите кнопку «Далее».
После подтверждения будет создан пароль приложения. Скопируйте и сохраните пароль, он потребуется далее для настройки серверной части приложения.

Шаг 3: Разрешение доступа к почтовому ящику#

Перейдите на страницу разрешения доступа к почтовому ящику от лица созданного ранее аккаунта.

Примечание

Включение доступа – это требование Яндекс. Приложение использует только подключение SMTP для отправки писем.
Нажмите галочку «С сервера imap.yandex.ru по протоколу IMAP» и нажмите кнопку «Сохранить изменения».

Шаг 4: Получение данных для настройки серверной части Compass On‑premise#

Для завершения подключения почты Яндекс укажите ваш email и пароль приложения в соответствующие поля при заполнении файла конфигурации почтового сервиса во время установки серверной части приложения:

smtp.host: “smtp.yandex.ru”
smtp.username: “your_email@yandex.ru”
smtp.password: “пароль приложения”
smtp.from: “your_email@yandex.ru”

Настройка SSO-авторизации через AD FS#

SSO-авторизация через AD FS настраивается в три шага:

Шаг 1: Настройка интеграции с серверной частью Compass On‑premise.
Шаг 2: Настройка интеграции с клиентской частью Compass On‑premise.
Шаг 3: Получение данных для настройки серверной части Compass On‑premise.

Шаг 1: Настройка интеграции с серверной частью Compass On‑premise#

Откройте приложение «Server Manager», нажмите кнопку «Tools», выберите пункт «AD FS Management». Откроется окно настройки AD FS.
Откройте раздел «Application Groups», нажмите на «Add Application Group…». Откроется окно настройки интеграции.
Введите название интеграции с приложением, например «Compass On‑premise SSO». Нажмите на «Server application» и кнопку «Next».
Скопируйте и сохраните Client Identifier, эти данные потребуются далее для настройки интеграции и серверной части приложения.
Введите в поле «Redirect URl» следующую ссылку: «https://<ваш Compass On‑premise домен>/federation/sso/auth_result/oidc/». Нажмите кнопку «Add» и затем кнопку «Next».
Нажмите галочку «Generate a shared secret». Скопируйте и сохраните сгенерированный код Secret, он потребуются далее для настройки серверной части приложения. Нажмите кнопку «Next».
Проверьте настройки и нажмите кнопку «Next» для завершения создания интеграции с серверной частью Compass On-premise.

Шаг 2: Настройка интеграции с клиентской частью Compass On‑premise#

В разделе «Application Groups» выберите созданную интеграцию с серверной частью Compass On-premise и нажмите «Properties».
В открывшемся окне нажмите кнопку «Add application…». Откроется окно настройки интеграции с приложением.
Нажмите на «Web API» и затем кнопку «Next».
Вставьте в поле «Identifier» ранее сохраненный Client Identifier (шаг 1, пункт 4), нажмите кнопку «Add» и затем кнопку «Next».
Нажмите на «Permit everyone» и затем кнопку «Next».
Нажмите галочки «allatclaims» и «openid», нажмите кнопку «Next».
Проверьте настройки и нажмите кнопку «Next» для завершения создания интеграции с клиентской частью Compass On-premise.

Шаг 3: Получение данных для настройки серверной части Compass On‑premise#

В окне интеграции с Compass On-premise нажмите на созданное Web API приложение, нажмите кнопку «Edit…».
Откройте вкладку «Issuance Transform Rules» и нажмите кнопку «Add Rule…».
В открывшемся окне нажмите кнопку «Next». Откроется экран настройки атрибутов учетной записи.
Введите в поле «Claim rule name» любое название, например «profile_attributes». В поле «Attribute store» выберите «Active Directory».
Укажите следующие значения в таблице:
- E-Mail-Addresses: mail;
- Given-Name: first_name;
- Surname: last_name.
Скопируйте и сохраните названия атрибутов: mail, first_name, last_name, эти данные потребуются далее для настройки серверной части приложения. Нажмите кнопку «Finish» для завершения настройки атрибутов.
В открывшемся окне нажмите кнопку «Apply» и затем «ОК».
Для завершения настройки SSO-авторизации через AD FS укажите ваши Client Identifier, Secret, first_name, last_name, mail и домен, на котором развернут AD FS, в соответствующие поля при заполнении файла конфигурации SSO-авторизации во время установки серверной части приложения:

sso.client_id: "Client Identifier"
sso.client_secret: "Secret"
sso.oidc_provider_metadata_link: "https://<ваш домен, на котором развернут AD FS>/adfs/.well-known/openid-configuration"
sso.attribution_mapping.first_name: "first_name"
sso.attribution_mapping.last_name: "last_name"
sso.attribution_mapping.mail: "mail"
sso.attribution_mapping.phone_number: ""

Настройка SSO-авторизации через Okta#

SSO-авторизация через Okta настраивается в два шага:

Шаг 1: Настройка интеграции с приложением Compass On‑premise.
Шаг 2: Получение данных для настройки серверной части Compass On‑premise.

Шаг 1: Настройка интеграции с приложением Compass On‑premise#

Перейдите в свой аккаунт в Okta, нажмите кнопку «Администратор» для перехода в панель администратора.
Откройте раздел «Applications», нажмите на кнопку «Create App Integration».
Выберите пункт «OIDC - OpenID Connect».
Выберите пункт «Web Application», нажмите кнопку «Next». Откроется страница настройки интеграции.
Введите название интеграции с приложением, например «Compass On‑premise SSO».
Поставьте галочки, как показано на изображении ниже.
Введите в поле «Sign-in redirect URls» следующую ссылку: «https://<ваш Compass On‑premise домен>/federation/sso/auth_result/oidc/». Нажмите на крестик справа от поля «Sign-out redirect URls».
Введите ваш домен в поле «Base URls» следующим образом: «https://<ваш Compass On‑premise домен>/». Выберите пункт «Allow everyone in your organization to access» и нажмите кнопку «Save».
Откроется страница успешно созданной интеграции с приложением Compass On-premise.

Шаг 2: Получение данных для настройки серверной части Compass On‑premise#

На странице созданной интеграции с приложением Compass On-premise скопируйте и сохраните Client ID и Client Secrets, эти данные потребуются далее для настройки серверной части приложения.
Нажмите на профиль в правом верхнем углу страницы, скопируйте и сохраните ссылку на ваше пространство в Okta, она потребуются далее для настройки серверной части приложения.
Откройте вкладку «Sign On» и нажмите на ссылку «Configure profile mapping». Откроется экран с атрибутами учетной записи SSO в Okta.
Скопируйте и сохраните следующие названия атрибутов учетной записи: given_name, family_name и email, эти данные потребуются далее для настройки серверной части приложения.
Для завершения настройки SSO-авторизации через Okta укажите ваши Client ID, Client Secrets, ссылку на ваше пространство в Okta, given_name, family_name и email в соответствующие поля при заполнении файла конфигурации SSO-авторизации во время установки серверной части приложения:
```
sso.client_id: "Client ID"
sso.client_secret: "Client Secrets"
sso.oidc_provider_metadata_link: "https://<ссылка на ваше пространство в Okta>/.well-known/openid-configuration?client_id=<ваш Client ID>"
sso.attribution_mapping.first_name: "given_name"
sso.attribution_mapping.last_name: "family_name"
sso.attribution_mapping.mail: "email"
sso.attribution_mapping.phone_number: ""
```

Настройка SSO-авторизации через Keycloak#

SSO-авторизация через Keycloak настраивается в два шага:

Шаг 1: Настройка интеграции с приложением Compass On‑premise.
Шаг 2: Получение данных для настройки серверной части Compass On‑premise.

Шаг 1: Настройка интеграции с приложением Compass On‑premise#

Перейдите в административную панель Keycloak.
Создайте новый realm. Если планируете использовать существующий, то можете сразу перейти к пункту 4 ниже.
Введите название нового realm и завершите создание.
Перейдите в раздел «Clients» и нажмите «Create client».
Введите «Client ID», например, «Compass».
Включите «Client authentication» и поставьте галочки, как показано на изображении ниже.
Введите ваш домен Compass в поля «Root URL» и «Home URL» следующим образом: «https://<ваш Compass On‑premise домен>/». Введите в поле «Valid redirect URIs» следующую ссылку: «https://<ваш Compass On‑premise домен>/federation/sso/auth_result/oidc/». Завершите создание, нажав «Save».

Шаг 2: Получение данных для настройки серверной части Compass On‑premise#

На странице созданной интеграции с приложением Compass On-premise в разделе «Settings» скопируйте «Client ID».
Перейдите во вкладку «Credentials» и скопируйте «Client Secret».
Откройте раздел «Client scopes» и перейдите в «profile».
Во вкладке «Mappers» найдите поля, соответствующие имени и фамилии, откройте каждый и скопируйте «Token Claim Name». Значения по умолчанию будут «given_name» и «family_name». Эти данные потребуются далее для настройки серверной части приложения.
Название для поля почтового ящика аналогично можно найти в «Client scopes» в «email». Значение по умолчанию «email».
В разделе «Realm settings» скопируйте ссылку на «OpenID Endpoint Configuration».
Для завершения настройки SSO-авторизации через Keycloak укажите ваши Client ID, Client Secret, ссылку на конфигурацию OpenID, given_name, family_name и email в соответствующие поля при заполнении файла конфигурации SSO-авторизации во время установки серверной части приложения.
```
sso.client_id: "Client ID"
sso.client_secret: "Client Secret"
sso.oidc_provider_metadata_link: "https://<ваш домен, на котором развернут Keycloak>/realms/<название realm>/.well-known/openid-configuration"
sso.attribution_mapping.first_name: "given_name"
sso.attribution_mapping.last_name: "family_name"
sso.attribution_mapping.mail: "email"
sso.attribution_mapping.phone_number: ""
```

Напишите нам в пространстве поддержки On-premise, Telegram, WhatsApp или на почту support@getcompass.ru, чтобы получить индивидуальную демонстрацию функционала и помощь по вопросам интеграции мессенджера в вашей компании.