Как использовать 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

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

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

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