Как использовать SSO

Для проектов на Laravel существует отдельный модуль, там все написано как его использовать.

Описание

Система сквозной авторизации состоит из трех компонентов:

• Клиент - браузер пользователя
• Брокер (сервис) - сайт, который он посещает
• Сервер - место, которое отвечает за валидность данных и хранилище сессий (это ЦАС)

Адрес сервера: /sso

Брокер должен иметь при себе открытый и закрытый ключ, которые он использует, чтобы сервер мог его распознать. Получить их можно из ЦАСа.

Когда клиент заходит к брокеру, брокер создает случайный токен, который хранится в виде cookie. Затем брокер отправляет клиента к серверу (на ЦАС) вместе со своим открытым ключом и случайным токеном. Сервер с генерирует хеш, используя открытый и закрытый ключи брокера и присланный случайный токен. Этот хеш используется для того, чтобы связать сервер с клиентской сессией. Когда связь создана, сервер перенаправляет клиента обратно к брокеру.

Брокер может сгенерировать этот же хеш на своей стороне, используя те же данные (случайный токен из куки, открытый и закрытый ключ). С каждым запросом он должен посылать его на сервер, чтобы сервер мог восстановить по этому хешу соответствующую сессию.

Алгоритм

Первое посещение

Клиент заходит к брокеру, брокер смотрит лежит ли в куках случайный токен. Если нет, то генерирует его, кладет в куки и перенаправляет клиента на сервер (ЦАС) для связывания сессий.

Случайный токен, который надо сгенерировать в куку пользователю это в прямом смысле случайный токен (но нельзя использовать символы подчеркивания _) Следить следует только за тем, чтобы не было совпадений с другими пользователями брокера.

Если токен уже сгенерирован брокером и лежит в куках, то никуда перенаправлять и ничего генерировать не требуется. Также следует понимать, что если кука пропала/закончилась или еще один редирект произошел, то это ничем не повредит, просто на сервере добавится еще одна связь с сессией пользователя, а прошлая станет неактуальной.

Вместе с редиректом брокер отправляет следующие данные:

command => attach
broker => открытый ключ брокера
token => случайный токен
checksum => см. ниже Как сгенерировать checksum
return_url => URL, куда следует перенаправить клиента с сервера

Значение параметра return_url должно быть закодированно с помощью механизма urlencode.

Общение с сервером

Теперь брокер может свободно посылать запросы на адрес sso.

Параметры, которые следует отправлять с каждым запросом:

command => команда, которую нужно выполнить. См. ниже Список команд
sso_session => см. ниже Как сгенерировать session_id

Параметры command и sso_session подставляются в URL запроса как GET-параметры.

Пример:

/sso?command=foo&sso_session=bar

Остальные параметры запроса подставляются так:

• для POST-запросов, как поля формы (в теле запроса)
• для GET-запросов, как обычные дополнительные GET-параметры

Ошибки при запросах

Если при запросе произошла ошибка, отследить ее можно по соответствующему http-коду. При успешных запросах http-код < 400.

Ошибки в формате json в виде { 'error' => 'текст или код ошибки' }

Как сгенерировать checksum

checksum = sha256-дайджест строки вида: "attach"+token+(закрытый ключ брокера)

Например, attachrandom_tokenbroker_key

Как сгенерировать session_id

session_checksum = sha256-дайджест строки вида: "session"+token+(закрытый ключ брокера)

Например, sessionrandom_tokenbroker_key

session_id = "SSO_"+(открытый ключ брокера)+"_"+(token)+"_"+session_checksum

То есть, например SSO_broker-open-key_token_session-checksum

Список команд

Авторизоваться

POST command=login

Параметры:

username - email пользователя

password - пароль пользователя

Ответ: объект пользователя

Авторизоваться по строке авторизации

POST command=authnative

Параметры:

auth_string - зашифрованная строка

Ответ:

user - объект пользователя

authorize - был ли пользователь авторизован (разные сервисы авторизуют пользователя по разному)

reg_data - данные из строки

Если authorize == false, то добавляется user_exists - существует пользователь по такой строке или нет

Если в auth_string отсутствует user_id, то будет возвращен код ошибки, но без самой ошибки, а с данными из строки

Авторизоваться по коду подтверждения

POST command=authconfirm

Параметры:

confirmation_code - код подтверждения

Ответ: объект пользователя

Получить данные пользователя

GET command=userInfo

Параметры: нет

Ответ: объект пользователя или null

Выход

POST command=logout

Параметры: нет

Ответ: http 204

Обновить информацию о пользователе

POST command=updateUser

Параметры: см. update

Ответ: {success => 1}

Получить список привязанных приложений

GET command=getApps

Параметры: нет

Ответ: список приложений пользователя

Дополнительные методы

Проверка аутентификации

Проверка наличия активной сессии, для переданного клиентского идентификатора сессии.

Метод позволяет проверить активна ли сессия не запрашивая профиль целиком.

При наличии активной связки сессии - продлевает срок ее действия.

Method: [GET /sso/check]

Запрос должен сопровождаться отправкой BearerToken вида SSO_{$brokerId}_{$token}_{$session_checksum} в заголовке Authorization (типа Bearer).

Пример запроса

GET /sso/check
Accept: application/json
Authorization: Bearer {$bearerToken}
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.9,es;q=0.8

Пример ответа

{
  "success": 1,
  "result": {
    "is_authenticated": true
  }
}

ВНИМАНИЕ: Все остальные действия, не касающиеся непосредственно работы с авторизованным пользователем можно проводить через обычный API.