Авторизация с Webasyst ID

Для пользователей вашего интернет-сайта или клиентского приложения вы можете реализовать возможность авторизации с помощью Webasyst ID — по аналогии с авторизацией через социальные сети. Авторизация работает с использованием протокола oAuth 2.0.

Доступны 2 схемы работы:

для серверных приложений (например, интернет-сайтов);
для клиентских приложений (нативных для ПК и мобильных устройств или SPA).

Авторизация в серверных приложениях

Используется спецификация oAuth 2.0 / Authorization Code.

Порядок работы:

Получить токен авторизации.
Выполнять запросы к серверу ресурсов Webasyst.

Шаг 1. Получение токена авторизации

Серверное приложение (например, серверный код интернет-сайта) перенаправляет пользователя в браузере на URL сервера авторизации Webasyst https://www.webasyst.com/id/oauth2/auth/code со следующими GET-параметрами:
- response_type=code. Это обязательный фиксированный параметр, который декларирует использование схемы «Authorization Code».
- client_id — ID клиента, который нужно получить для своего сайта в Центре заказчика Webasyst.
- scope — список идентификаторов разрешений для выполнения запросов к серверу ресурсов Webasyst. Идентификаторы разрешений должны отделяться друг от друга символом «+».
  
  Пример: profile+license:read
  
  Доступные идентификаторы разрешений:
  - profile — доступ к личным данным пользователя Центра заказчика (имя, email-адрес, загруженное изображение). Этот идентификатор считается используемым по умолчанию всегда, даже если не указать его явно.
  - profile:write — редактирование личных данных пользователя Центра заказчика (имя, email-адрес, загруженное изображение).
  - license:read — доступ к информации о принадлежащих пользователю лицензиях программных продуктов.
- redirect_uri — URL, на который нужно перенаправить пользователя после авторизации.
- state — случайным образом сформированная строка любых символов произвольной длины.
Сервер авторизации предлагает пользователю авторизоваться, если он ещё не авторизован.
Сервер авторизации предлагает пользователю подтвердить доступ серверного кода к тем видам данным, которые были перечислены в параметре scope.
После получения согласия пользователя сервер авторизации перенаправляет его на URL, указанный в параметре redirect_uri. К этому URL добавляются следующие GET-параметры:
- code — одноразовый код авторизации с коротким сроком действия;
- state — строка, переданная в параметре state в п. 1.
Серверный код проверяет соответствие полученного значения GET-параметра state с тем значением, которое было отправлено в п. 1.
Серверный код, не используя браузер, выполняет POST-запрос на URL https://www.webasyst.com/id/oauth2/auth/token:
- grant_type=authorization_code. Это обязательный фиксированный параметр.
- code — код авторизации, полученный от сервера авторизации.
- redirect_uri — URL, который был отправлен в параметре redirect_uri в п. 1.
- client_id — ID клиента, который был отправлен в параметре client_id в п. 1.
- client_secret — секретный код клиента, который разработчик должен получить для своего сайта в Центре заказчика Webasyst.
Сервер авторизации возвращает ответ в формате JSON:
```
{
    "access_token":"...",     //токен авторизации
    "token_type":"bearer",    //тип токена
    "expires_in":3600,        //срок действия токена в секундах
    "refresh_token":"..."     //токен для обновления токена авторизации по истечении его срока действия
}
```
Начиная с этого момента пользователь считается авторизованным.

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

Обновление токена авторизации

Токен авторизации нужно обновлять по истечении его срока действия. Если этого не сделать, то сервер ресурсов перестанет обрабатывать запросы к API.

Обновление токена авторизации представляет собой получение нового токена авторизации с помощью последнего полученного токена обновления. Для этого нужно нужно отправить POST-запрос по адресу https://www.webasyst.com/id/oauth2/auth/token:

grant_type=refresh_token. Это обязательный фиксированный параметр, который показывает, что требуется обновление токена авторизации.
refresh_token — последний полученный токен для обновления токена авторизации.
client_id — ID клиента, полученный в Центре заказчика.
client_secret — секретный код клиента, который разработчик должен получить для своего в Центре заказчика Webasyst.

Сервер авторизации возвращает ответ в формате JSON:

{
    "access_token":"...",     //новый токен авторизации
    "token_type":"bearer",    //тип токена
    "expires_in":3600,        //срок действия токена в секундах
    "refresh_token":"..."     //новый токен для обновления токена авторизации
}

Шаг 2. Выполнение запросов к API сервера ресурсов

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

При обращении к API сервера ресурсов нужно использовать последний полученный токен авторизации, срок действия которого ещё не истёк. Токен с истёкшим сроком действия нужно обновить перед отправкой очередного запроса к API.

Токен авторизации нужно передавать в HTTP-заголовке запроса:

Authorization: Bearer токен_авторизации

API сервера ресурсов возвращает ответы на запросы в формате JSON.

Авторизация в клиентских приложениях

Порядок работы:

Получить токен авторизации.
Получить список аккаунтов Webasyst, в которых пользователь включил для себя вход в бекенд с использованием Webasyst ID.
Получить коды доступа к каждому из аккаунтов, выбранных пользователем.
Получить токены доступа к API выбранных аккаунтов.
Отправлять запросы к API приложений этих аккаунтов.

Для SPA-приложений пока не поддерживается обращение к API аккаунтов Webasyst, поэтому для них доступны только авторизация пользователя и вызов методов API сервера ресурсов Webasyst.

Шаг 1. Получить токен авторизации

Используется спецификация oAuth 2.0 / Authorization Code + PKCE.

Здесь описан стандартный порядок авторизации с использованием браузера, установленного на устройстве пользователя. Если ваше приложение должно формировать собственный визуальный интерфейс для этих целей, используйте получение токена авторизации по headless-протоколу.

Клиентское приложение открывает в браузере URL сервера авторизации https://www.webasyst.com/id/oauth2/auth/code со следующими GET-параметрами:
- response_type=code. Это обязательный фиксированный параметр, который декларирует, что используется схема «Authorization Code».
- client_id — ID клиента, который разработчик должен получить в Центре заказчика Webasyst для своего клиентского приложения.
- device_id — ID устройства, строковая константа длиной до 64 символов, которая не должна изменяться со временем для каждого экземпляра приложения, запущенного на каждом из устройств. Разные устройства и экземпляры приложения должны иметь разные идентификаторы.
- scope — строка вида token:{разделённые точкой строковые идентификаторы приложений Webasyst, к которым клиентское приложение должно получать доступ при подключении к аккаунтам Webasyst}.
  
  Пример: token:shop.site.blog
  В этом примере клиентскому приложению требуется получить доступ к приложениям Shop-Script, «Сайт» и «Блог».
- redirect_uri — URL, на который нужно перенаправить пользователя после авторизации.
- state — случайным образом сформированная строка любых символов произвольной длины.
- code_challenge — хеш одноразового пароля, сгенерированного перед отправкой этого запроса и упакованного в формат Base64-URL-encoded (если устройство пользователя поддерживает алгоритм SHA256), или сам пароль в незашифрованном виде (если SHA256 не поддерживается).
- code_challenge_method — способ формирования хеша пароля для параметра code_challenge: строка "SHA256" (если поддерживается устройством пользователя) или "plain" (если алгоритм SHA256 не поддерживается).
  
  Одноразовый пароль, сгенерированный для формирования значения параметра code_challenge, должен иметь длину от 43 до 128 символов и может содержать в любом количестве латинские буквы, цифры и 4 специальных символа: -._~ (дефис, точку, символ подчеркивания или тильду).
  
  Хеш должен формироваться по алгоритму SHA256, если он доступен на устройстве пользователя. Полученный хеш должен быть затем переведён в формат BASE64-URL-encoded.
  
  Если устройство пользователя не поддерживает алгоритм SHA256, то вместо хеша в параметре code_challenge передаётся сам сгенерированный пароль в незашифрованном виде.
Сервер авторизации предлагает пользователю авторизоваться, если он ещё не авторизован.
Сервер авторизации предлагает пользователю подтвердить доступ клиентского приложения к тем видам данным, которые были перечислены в параметре scope в п. 1.
После получения согласия пользователя сервер авторизации перенаправляет пользователя обратно в клиентское приложение — на URL, указанный в параметре redirect_uri в п. 1. К этому URL добавляются следующие GET-параметры:
- code — одноразовый код авторизации с коротким сроком действия;
- state — строка, переданная в параметре state GET-запроса в п. 1.
Клиентское приложение проверяет соответствие полученного значения GET-параметра state с тем значением, которое было отправлено в п. 1.
Клиентское приложение, не используя браузер, выполняет POST-запрос на URL https://www.webasyst.com/id/oauth2/auth/token:
- grant_type=authorization_code. Это обязательный фиксированный параметр.
- code — код авторизации, полученный от сервера авторизации.
- redirect_uri — URL, который был отправлен в параметре redirect_uri в п. 1.
- client_id — ID клиента, который был отправлен в параметре client_id в п. 1.
- device_id — ID устройства, который был отправлен в параметре device_id в п. 1.
- code_verifier — одноразовый пароль в незашифрованном виде, который был сгенерирован для формирования хеша в параметре code_challenge в п. 1.

Сервер авторизации возвращает ответ в формате JSON:

{
    "access_token":"...",     //токен авторизации
    "token_type":"bearer",    //тип токена
    "expires_in":3600,        //срок действия токена в секундах
    "refresh_token":"..."     //токен для обновления токена авторизации
}

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

Получение токена авторизации по headless-протоколу

Это альтернативный способ получения токена авторизации и токена обновления. Используйте его в том случае, если ваше клиентское приложение должно формировать собственный визуальный интерфейс для авторизации пользователя вместо использования стандартного браузера, установленного на его устройстве.

Пользователь вводит свой email-адрес или номер телефона в визуальном интерфейсе, предоставленном для этого клиентским приложением.
Клиентское приложение отправяет POST-запрос на URL сервера авторизации Webasyst https://www.webasyst.com/id/oauth2/auth/headless/code/ со следующими параметрами (либо в формате JSON, либо в обычном формате form-data):
- client_id — ID клиента, который разработчик должен получить в Центре заказчика Webasyst для своего клиентского приложения.
- device_id — ID устройства, строковая константа длиной до 64 символов, которая не должна изменяться со временем для каждого экземпляра приложения, запущенного на каждом из устройств; разные устройства и экземпляры приложения должны иметь разные идентификаторы.
- scope — строка вида token:{разделённые точкой строковые идентификаторы приложений Webasyst, к которым клиентское приложение должно получать доступ при подключении к аккаунтам Webasyst}.
  
  Пример: token:shop.site.blog
  В этом примере клиентскому приложению требуется получить доступ к приложениям Shop-Script, «Сайт» и «Блог».
- code_challenge — хеш одноразового пароля, сгенерированного перед отправкой этого запроса (если устройство пользователя поддерживает алгоритм SHA256), или сам пароль в незашифрованном виде (если SHA256 не поддерживается).
  
  Одноразовый пароль, сгенерированный для формирования значения этого параметра, должен иметь длину от 43 до 128 символов и может содержать в любом количестве латинские буквы, цифры и 4 специальных символа: -._~ (дефис, точку, символ подчеркивания или тильду).
  
  Хеш должен формироваться по алгоритму SHA256, если он доступен на устройстве пользователя. Полученный хеш должен быть затем переведён в формат Base64-URL-encoded.
  
  Если устройство пользователя не поддерживает алгоритм SHA256, то вместо хеша в этом параметре передаётся сам сгенерированный пароль в незашифрованном виде.
- code_challenge_method — способ формирования хеша пароля для параметра code_challenge: строка 'SHA256' (если поддерживается устройством пользователя) или 'plain' (если алгоритм SHA256 не поддерживается).
- locale — локаль пользователя, используемая в клентском приложении.
- email — email-адрес, указанный пользователем в интерфейсе авторизации; не передаётся, если адрес не был указан.
- phone — номер телефона, указанный пользователем в интерфейсе авторизации; не передаётся, если номер не был указан.
Сервер авторизации генерирует код подтверждения и отправляет его пользователю либо в email-сообщении (если при авторизации был введён email-адрес), либо в SMS-сообщении (если при авторизации был введён номер телефона). Сервер авторизации отправляет ответ в формате JSON:
```
{
    "next_request_allowed_at": ..., //период времени в секундах, спустя который можно будет повторно отправить код подтверждения 
    "code_expires_at": ..., //период времени в секундах, спустя который код подтверждения станет недействительным
}
```
Клиентское приложение самостоятельно формирует и показывает пользователю интерфейс для ввода полученного кода подтверждения.
Клиентское приложение отправляет POST-запрос с введённый пользователем кодом подтверждения на URL сервера авторизации (в формате JSON или в обычном form-data):
- client_id: ID клиента.
- device_id: ID устройства.
- code_verifier: одноразовый пароль в открытом виде, хеш которого был передан на предыдущем шаге в параметре code_challenge.
- code: код подтверждения, введённый пользователем.

В случае успешного подтверждения сервер авторизации возвращает ответ в формате JSON:

{
    "access_token":"...",     //токен авторизации
    "token_type":"bearer",    //тип токена
    "expires_in":3600,        //срок действия токена в секундах
    "refresh_token":"..."     //токен для обновления токена авторизации
}

Обновление токена авторизации

Токен авторизации для использования в клиентском приложении нужно обновлять так же, как и для серверного кода, но без передачи параметра client_secret.

Шаг 2. Получить список аккаунтов Webasyst с активированным входом с Webasyst ID

Клиентское приложение отправляет запрос для получения аккаунтов Webasyst, в которых пользователь включил вход с Webasyst ID.

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

Шаг 3. Получить коды доступа к выбранным аккаунтам Webasyst

Клиентское приложение отправляет POST-запрос со списком идентификаторов аккаунтов Webasyst на URL сервера авторизации https://www.webasyst.com/id/api/v1/auth/client/:

client_id[]=...&client_id[]=...&client_id[]=...

Альтернативный вариант — использовать в содержимом POST-запроса формат JSON:

{"client_id": ["...", "...", "..."]}

В ответ на запрос сервер авторизации возвращает коды доступа к указанным аккаунтам Webasyst:

{
    "{client_id ...}":"{код доступа}",
    "{client_id ...}":"{код доступа}",
    ...
}

Шаг 4. Получить токены доступа к API выбранных аккаунтов Webasyst

Чтобы выполнять вызовы методов API приложений в аккаунтах Webasyst, клиентское приложение должно получить токены доступа к API для каждого из аккаунтов.

Для этого клиентское приложение должно отправить POST-запросы к этим аккаунтам на URL вида {URL аккаунта Webasyst}/api.php/token-headless:

code — код доступа к данному аккаунту, полученный от сервера авторизации.
scope — список строковых идентификаторов приложений, разделённых точкой, доступ к которым необходим для работы клиентского приложения. Указанные идентификаторы приложений должны совпадать с теми, которые клиентское приложение отправляло в шаге 1 для получения токена авторизации.

Пример: shop.site.blog
client_id — произвольный уникальный идентификатор приложения, составленный разработчиком по своему усмотрению. Для веб-приложений (например, SPA) рекомендуется добавить в идентификатор часть доменного имени, чтобы избежать возможных конфликтов.

Пример: XYZCompanyShopImportApp

API аккаунта Webasyst возвращает ответ в формате JSON с токеном доступа:

{
    "access_token":"..." //токен доступа
}

Шаг 5. Отправлять запросы к API приложений в аккаунтах Webasyst

Полученный токен доступа нужно использовать в клиентском приложении для вызова методов API приложений Webasyst, идентификаторы которых были перечислены в параметре scope.

Объединение нескольких профилей Webasyst ID

Объединение необходимо в том случае, если пользователь сначала авторизовался в клиентском приложении по номеру телефона, который отсутствует в свойствах профилей клиентов Webasyst. При такой первоначальной авторизации по номеру телефона создаётся временный, пустой профиль пользователя.

После этой первоначальной авторизации пользователю предлагается дополнительно авторизоваться в своём основном профиле по email-адресу, чтобы подключить список его активов к клиентскому приложению. После этой дополнительной авторизации пустой профиль с номером телефона объединяется с основным профилем пользователя.

Последовательность действий при объединении профилей:

Выполнить API-метод для получения кода объединения профилей с токеном текущего, пустого профиля. Сервер ресурсов возвращает код, необходимый для выполнения следующего шага. Этот код действует в течение 1 часа.
Прекратить сессию авторизации с пустым профилем и авторизовать пользователя заново с отправкой дополнительных параметров change_user=1 и mergecode (в этот параметр нужно передать код, полученный на предыдущем шаге).

После успешной авторизации пустой профиль автоматически объединится с основным профилем пользователя, который теперь становится авторизованным в клиентском приложении.

Информацию о результатах объединения профилей можно получить путём вызова специального метода с токеном текущего (основного) профиля пользователя. Эта информация доступна в течение 1 часа.

Методы API аккаунтов Webasyst

Используйте вызовы этих системных методов API в своём программном продукте, чтобы управлять данными в аккаунтах Webasyst. Для управления данными в отдельных приложениях Webasyst используйте вызовы методов API этих приложений.

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

Получение общей информации об аккаунте Webasyst

HTTP-запросы

GET: /api.php/webasyst.getInfo

Необходимые разрешения

webasyst

Формат ответа

{
    "name": "...", // Название компании, указанное в системных настройках
    "backend_url": "https://.../webasyst/", // URL бекенда аккаунта
    "logo": { //информация о логотипе
        "mode": "gradient",
        "text": {
            "value": "",
            "color": "",
            "default_value": "",
            "default_color": "#fff",
            "formatted_value": ""
        },
        "two_lines": false,
        "gradient": {
            "from": "#FF248B",
            "to": "#FF5900",
            "angle": 0
        },
        "image": {
            "thumbs": [],
            "original": []
        }
    }
}

Установка программного продукта

HTTP-запросы

POST: /api.php/installer.product.install

Необходимые разрешения

installer

Формат запроса

Только form-data.

slug: полный строковый идентификатор продукта.

Формат ответа

Строка 'true' с одним из кодов ответа:

200: продукт уже был установлен ранее;
201: продукт успешно установлен.

Формат ответа в случае ошибки:

{
    "error":"...", // код ошибки
    "error_description":"...", // текстовое описание ошибки
}

Возможные коды ответа сервера при возникновении ошибок:

402: Установка продукта требует наличия лицензии. Возвращается в случае, если продукт является платным и у пользователя нет его лицензии. В этом случае нужно предварительно активировать лицензию с помощью метода сервера ресурсов для активировании лицензии продукта. Если аккаунт установлен в облаке Webasyst, где доступна аренда указанного продукта, то установка таких платных приложений выполняется без необходимости предварительной активации лицензии.
403: У пользователя, для которого сгенерирован токен доступа, нет прав доступа к «Инсталлеру», или значение параметра scope, указанного при получении токена, не содержит идентификатор приложения installer.
404: Причина ошибки указывается в поле "error" тела ответа:
- invalid_method: в аккаунте установлена версия фреймворка, которая не поддерживает выполнение этого метода;
- product_not_found: продукт, соответствующий указанному значению параметра slug, не существует;
- check_installed_fail: проверка значения параметра slug завершилась ошибкой — например, если в этом значении указаны недопустимые символы.
409: Причина ошибки указывается в поле "error" тела ответа:
- requirements_not_satisfied: не удовлетворены системные требования, необходимые для установки продукта;
- in_progress: в данный момент уже устанавливается другой продукт; нужно подождать несколько минут и повторить попытку вызова метода.

Приглашение нового пользователя

HTTP-запросы

POST: /api.php/team.users.invite

Необходимые разрешения

Не требуются

Формат запроса

Только form-data.

phone: Номер телефона нового пользователя.
email: Email-адрес нового пользователя. Используется, если не заполнен параметр phone.
send: Флаг, означающий необходимость отправки email-уведомления со ссылкой для входа в бекенд аккаунта Webasyst новому пользователю. Используется, только если заполнен параметр email.

Если в POST-запросе заполнен параметр phone, то по указанному в нём номеру телефона новому пользователю отправляется SMS-сообщение со ссылкой для входа в бекенд аккаунта Webasyst.

Если параметр phone не заполнен, но заполнен параметр email, то по указанному в нём email-адресу отправляется сообщение со ссылкой для входа в бекенд аккаунта Webasyst — только в том случае, если также передан непустой флаг в параметре send. Если же параметр send пуст, то email-сообщение новому пользователю не отправляется, а ссылку для входа в бекенд можно показать в клиентском приложении, получив её из ответа сервера.

Формат ответа

{
    "contact_id":"...",    // ID контакта с указанным номером телефона или email-адресом. Или ID созданного для приглашения нового контакта, если существующий контакт не был найден.
    "invitation_link":"..."    // URL ссылки для входа нового пользователя в бекенд аккаунта Webasyst.
}

Получение списка пользователей бекенда Webasyst

HTTP-запросы

GET: /api.php/team.users.getList

Необходимые разрешения

Не требуются

Формат запроса

Только form-data.

filter: Необязательный ассоциативный массив параметров фильтрации списка пользователей. Доступные ключи массива:
- group_id: ID групп, пользователей которых нужно получить.
- access: Информация о минимальном уровне доступа к отдельным приложениям тех пользователей, список которых должен вернуть метод. В этом элементе массива могут использоваться следующие строковые константы:
  - 'limited' — ограниченный либо полный доступ;
  - 'full' — только полный доступ.
  Допустимые варианты значений этого элемента массива:
  - Ассоциативный массив с ID приложений в качестве ключей и констант с обозначением уровня доступа в качестве значений.
  - Нумерованный массив с ID приложений. Такой формат соответствует поиску пользователей с обозначением доступа 'limited' к этим приложениям.
  - ID одного приложения для поиска пользователей с обозначением доступа 'limited' к этому приложению.
  Пример
```
// Ассоциативный массив
[
    'access' => [
        'crm' => 'limited',
        'files' => 'full',
    ],
];

// Нумерованнный массив
[
    'access' => [
        'crm',   // 'limited'
        'files', // 'limited'
    ],
];

// ID одного приложения
[
    'access' => 'crm', // 'limited',
];
```

Формат ответа

[
    [
        "id":"...",     // ID контакта пользователя
        "name":"...",   // Имя пользователя
        "...":"...",    // Другие свойства пользователя
    ],
    [
        "id":"...",
        "name":"...",
        "...":"...",
    ],
    ...
]

Авторизация в серверных приложениях

Шаг 1. Получение токена авторизации

Обновление токена авторизации

Шаг 2. Выполнение запросов к API сервера ресурсов

Авторизация в клиентских приложениях

Шаг 1. Получить токен авторизации

Получение токена авторизации по headless-протоколу

Обновление токена авторизации

Шаг 2. Получить список аккаунтов Webasyst с активированным входом с Webasyst ID

Шаг 3. Получить коды доступа к выбранным аккаунтам Webasyst

Шаг 4. Получить токены доступа к API выбранных аккаунтов Webasyst

Шаг 5. Отправлять запросы к API приложений в аккаунтах Webasyst

Объединение нескольких профилей Webasyst ID

Методы API аккаунтов Webasyst

Получение общей информации об аккаунте Webasyst

HTTP-запросы

Необходимые разрешения

Формат ответа

Установка программного продукта

HTTP-запросы

Необходимые разрешения

Формат запроса

Формат ответа

Приглашение нового пользователя

HTTP-запросы

Необходимые разрешения

Формат запроса

Формат ответа

Получение списка пользователей бекенда Webasyst

HTTP-запросы

Необходимые разрешения

Формат запроса

Пример

Формат ответа