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

Как реализовать авторизацию с использованием Webasyst ID для пользователей серверных и клиентских приложений

Содержание...

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

Схемы работы:


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

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

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

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

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

  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-адрес, загруженное изображение). Этот идентификатор считается используемым по умолчанию всегда, даже если не указать его явно.
      • license:read — доступ к информации о принадлежащих пользователю лицензиях программных продуктов Webasyst.
      Подробнее об использовании разных разрешений в описании методов API сервера ресурсов.
    • redirect_uri — URL, на который нужно перенаправить пользователя после авторизации.
    • state — случайным образом сформированная строка любых символов произвольной длины.
  2. Сервер авторизации Webasyst предлагает пользователю авторизоваться, если он ещё не авторизован.
  3. Сервер авторизации Webasyst предлагает пользователю подтвердить доступ серверного приложения к тем видам данным, которые были перечислены в параметре scope.
  4. После получения согласия пользователя сервер авторизации Webasyst перенаправляет его на URL, который был указан в параметре redirect_uri GET-запроса. К этому URL добавляются GET-параметры:
    • code — одноразовый код авторизации с коротким сроком действия;
    • state — строка, переданная в параметре state в п. 1.
  5. Серверное приложение проверяет соответствие полученного значения GET-параметра state с тем значением, которое было отправлено в п. 1.
  6. Серверное приложение, не используя браузер, выполняет POST-запрос на URL https://www.webasyst.com/id/oauth2/auth/token со следующими значениями:
    • grant_type=authorization_code. Это обязательный фиксированный параметр.
    • code — код авторизации, полученный от сервера авторизации Webasyst.
    • redirect_uri — URL, который был отправлен в параметре redirect_uri в п. 1.
    • client_id — ID клиента, который был отправлен в параметре client_id в п. 1.
    • client_secret — секретный код клиента, который разработчик должен получить для своего программного продукта или сайта в Центре заказчика Webasyst.
  7. Сервер авторизации Webasyst возвращает ответ в формате JSON следующего содержания:
    {
        "access_token":"...",     //токен авторизации
        "token_type":"bearer",    //тип токена
        "expires_in":3600,        //срок действия токена в секундах
        "refresh_token":"..."     //токен для обновления токена авторизации по истечении его срока действия
    }
    Начиная с этого момента пользователь считается авторизованным.

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

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

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

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

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

Сервер авторизации Webasyst вернёт ответ в следующем формате:

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

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

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

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

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

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

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

Методы API сервера ресурсов Webasyst

Получение личных данных пользователя Центра заказчика Webasyst

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

GET: https://www.webasyst.com/id/api/v1/profile/

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

{
    "name":"Имя Отчество Фамилия",
    "firstname":"Имя",
    "lastname":"Фамилия",
    "middlename":"Отчество",
    "userpic":"https://{абсолютный URL загруженного изображения пользователя размером 96х96 пикселей}",
    "userpic_original_crop":"https://{абсолютный URL загруженного изображения пользователя исходного размера}",
    "userpic_uploaded":{true или false},    //есть ли у пользователя загруженное изображение
    "email":[    //массив email-адресов
        {
            "value":"name@domain.ru",               //email-адрес
            "ext":"work",                           //необязательное обозначение типа адреса
            "status":{"confirmed" или "unknown"}    //статус адреса
        },
        {
            "value":"...",
            "ext":"...",
            "status":"..."
        }
    ]
}
Получение списка установок фреймворка, в которых пользователь активировал вход в бекенд с использованием Webasyst ID

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

GET: https://www.webasyst.com/id/api/v1/installations/

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

[
    {
        "id":"{client_id установки фреймворка}",
        "domain":"{доменное имя установка}",
        "url":"{абсолютный URL установки}"
    },
    {
        ...
    }
]
Получение списка лицензий, которыми владеет пользователь

Необходимые разрешения: license:read.

GET: https://www.webasyst.com/id/api/v1/licenses/

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

[
    {
        "license_id":"{идентификатор лицензии}",
        "slug":"{строковый идентификатор программного продукта}",
        "product_id":"{числовой идентификатор программного продукта}",
        "order_id":"{номер заказа покупки лицензии}",
        "app_id":"{строковый идентификатор приложения, к которому относится программный продукт}",
        "ext_id":"{дополнительный идентификатор плагина, темы дизайна или виджета}",
        "type":"{тип программного продукта:  APP, PLUGIN, THEME или WIDGET}",
        "name":"{название программного продукт}",
        "expire_date":{дата истечения аренды продукта, если он используется на условиях аренды},
        "bound_to":"{доменное имя установки, к которой прикреплена лицензия}",
        "bind_available_date":{дата, когда лицензию можно будет прикрепить к другой установке, если эта возможность в данный момент заблокирована}
    },
    ...
 ]
Аннулирование выданных ранее разрешений для выполнения запросов о пользователе

Отменить разрешения для каждого серверного продукта, получившего доступ к данным пользователя, пользователь может также в Центре заказчика Webasyst. Данный метод выполняет то же самое действие.

DELETE: https://www.webasyst.com/id/api/v1/delete/

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

{
    "delete":true
}

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

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

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

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

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

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

  1. Клиентское приложение открывает в браузере URL сервера авторизации Webasyst https://www.webasyst.com/id/oauth2/auth/code со следующими GET-параметрами:
    • response_type=code. Это обязательный фиксированный параметр, который декларирует, что используется схема «Authorization Code».
    • client_id — ID клиента, который разработчик должен получить в Центре заказчика Webasyst для своего клиентского приложения.
    • scope — строка вида token:{разделённые точкой строковые идентификаторы приложений Webasyst, к которым клиентское приложение должно получать доступ при подключении к установкам фреймворка}.

      Пример: token:shop.site.blog
      В этом примере клиентское приложение пытается получить доступ к приложениям Shop-Script, «Сайт» и «Блог».
    • redirect_uri — URL, на который нужно перенаправить пользователя после авторизации.
    • state — случайным образом сформированная строка любых символов произвольной длины.
    • code_challenge — хеш одноразового пароля, сгенерированного перед отправкой этого запроса (если устройство пользователя поддерживает алгоритм SHA256) или сам пароль в незашифрованном виде (если SHA256 не поддерживается).
    • code_challenge_method — способ формирования хеша пароля для параметра code_challenge: "SHA256" (если поддерживается устройством пользователя) или "plain" (если алгоритм SHA256 не поддерживается).

      Одноразовый пароль, сгенерированный для формирования значения параметра code_challenge, должен иметь длину от 43 до 128 символов и может содержать латинские буквы, цифры и 4 специальных символа: -._~ (дефис, точку, символ подчеркивания или тильду).

      Хеш должен формироваться по алгоритму SHA256, если он доступен на устройстве пользователя. Полученный хеш должен быть затем переведён в формат BASE64-URL-encoded.

      Если устройство пользователя не поддерживает алгоритм SHA256, то вместо хеша в параметре code_challenge передаётся сам сгенерированный пароль в незашифрованном виде.
  2. Сервер авторизации Webasyst предлагает пользователю авторизоваться, если он ещё не авторизован.
  3. Сервер авторизации Webasyst предлагает пользователю подтвердить доступ сайта или серверного приложения к тем видам данным, которые были перечислены в параметре scope в п. 1.
  4. После получения согласия пользователя сервер авторизации Webasyst перенаправляет пользователя обратно в клиентское приложение — на URL, который был указан в параметре redirect_uri в п. 1. К этому URL добавляются GET-параметры:
    • code — одноразовый код авторизации с коротким сроком действия;
    • state — строка, переданная в параметре state GET-запроса в п. 1.
  5. Клиентское приложение проверяет соответствие полученного значения GET-параметра state с тем значением, которое было отправлено в п. 1.
  6. Клиентское приложение, не используя браузер, выполняет POST-запрос на URL https://www.webasyst.com/id/oauth2/auth/token со следующими значениями:
    • grant_type=authorization_code. Это обязательный фиксированный параметр.
    • code — код авторизации, полученный от сервера авторизации Webasyst.
    • redirect_uri — URL, который был отправлен в параметре redirect_uri в п. 1.
    • client_id — ID клиента, который был отправлен в параметре client_id в п. 1.
    • code_verifier — одноразовый пароль, сгенерированный для формирования хеша в параметре code_challenge в п. 1.
  7. Сервер авторизации Webasyst вернёт ответ на этот запрос в следующем формате:

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

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

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

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

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

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

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

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

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

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

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

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

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

{
    "{client_id установки фреймворка}":"{код доступа}",
    "{client_id установки фреймворка}":"{код доступа}",
    ...
}

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

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

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

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

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

    Пример: XYZCompanyShopImportApp

В ответ на такой запрос API установки фреймворка вернёт токен доступа в следующим формате:

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

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

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