Developer/authentication/

Основные положения

Аутентификация и авторизация при работе с API осуществляется на основании специализированного токена (Access token), включаемого в HTTP запросы на стороне системы, осуществляющей вызов API. Токен представляет собой длинную строковую последовательность, в которой закодированы параметры пользователя, время жизни токена и ресурс, с которым разрешена работа при помощи этого токена.

Разновидности токенов

Система поддерживает 2 разновидности токенов по способу их получения

• API ключ

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

• OAuth токен

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

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

Когда и что использовать?

• Если вы хотите использовать API в личных целях

  Если вы являетесь клиентом Seeneco и хотите использовать API в личных целях(например, получать выписки по своим счетам) то вам достаточно сгенерировать API-ключ в своем личном кабинете. Это быстрои не требует от вас никаких усилий. Но по этому токену будут доступны только данные вашего собственного аккаунта Seeneco.

• Если вы хотите использовать API для своих клиентов

  Если вы представляете компанию-разработчика он-лайн сервиса (например, он-лайн бухгалтерия или какой-то FinTech сервис) и хотите чтобы ваши клиенты (пользователи этого сервиса) смогли использовать API Seeneco, например для обмена данными с подключенными к Seeneco банками не покидая вашего сервиса, то вам необходимо зарегистрировать сервис в Seeneco и реализовать процесс сквозной авторизации, в результате которого вашим клиентам будут выданы персонифицированные OAuth токены

Работа с API-ключами

Получение API-ключа

Для получение токена необходимо выполнить следующие шаги:

• Войти в личный кабинет пользователя сервиса
• Выбрать в настройках раздел API
• В открывшемся разделе нажать на кнопку “Сгенерировать токен”
• Будет сгенерирован токен, значение которого можно просмотреть в соответствующем поле. Для копирования токена в буфер обмена можно воспользоваться кнопкой “Копировать в буфер обмена”

Отзыв API-ключа

В случае, если вы понимаете, что используемый токен был скомпрометирован, или вы не хотите более его использовать в стороннем ПО, вам необходимо выполнить отзыв ранее выданного токена. Для этого необходимо нажать на кнопку “Отозвать токен” в разделе API личного кабинета

Если вы хотите обновить токен и выпустить новый взамен текущего, необходимо нажать на кнопку “Сгенерировать новый токен”, которая доступна после генерации первичного токена. Это приведет к аннулированию текущего токена и выпуску нового

Сквозная авторизация

Что это такое?

Сквозная авторизация (Single-Sign-On, SSO) – это предоставление возможности входа в вашу систему при помощи стороннего сервиса без ввода учетных данных (например, логина и пароля). По итогам поддержки данного механизма клиенты партнерского сервиса получат возможность

• Получать и отправлять данные в Seeneco и подключенные банки при помощи партнерского сервиса, использующего API Seeneco
• Без ввода логина и пароля переходить из интерфейса Seeneco в интерфейс сервиса
• Без ввода логина и пароля переходить из интерфейса системы ДБО банка, подключенного к платформе Seeneco в интерфейс сервиса

В качестве подхода к выполнению сквозной авторизации Seeneco использует OpenID Connect, основанный на OAuth2. Это де-факто стандарт при построении систем сквозной авторизации в таких компаниях как Google, Facebook, Amazon и прочих. Также, различные вариации данного протокола используют и крупнейшие банки, например Сбербанк РФ. Подробнее о протоколе и терминах можно прочитать здесь, но для реализации взаимодействия с Seeneco вам не нужно самостоятельно изучать все протоколы и спецификации, достаточно выполнить шаги описанные ниже.

Как это работает?

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

• Пользователь – пользователь, выполняющий переход в партнёрский сервис со сторонней площадки (интерфейса Seeneco или системы ДБО подключенного банка).
• Партнерский сервис (client, в терминологии OAuth) – сервис, клиентом которого является пользователь
• Провайдер идентификации (identity provider, Open ID Connect provider) – сервис, которому партнер доверяет проводить идентификацию клиента. В случае с подключением к платформе Seeneco эту роль играет сервис авторизации Seeneco.

При подключении к Seeneco реализуется один из наиболее распространенных способов OAuth аутентификации – аутентификация при помощи кода авторизации (OAuth code flow).
Процесс состоит из следующих шагов

1. Пользователь переходит по специальной ссылке на партнерский сервис.
2. При переходе по этой ссылке партнерский сервис формирует запрос кода авторизации путем перенаправления сессии браузера по адресу /authorize на стороне Seeneco
3. Seeneco определяет, был ли уже авторизован пользователь ранее и при необходимости перенаправляет его на страницу логина для авторизации. По итогам успешной авторизации Seeneco возвращает код авторизации в партнерский сервис в качестве одного из параметров адресной строки
4. Партнерский сервис проверяет код авторизации и запрашивает токен доступа (OAuth Access token) путем направления запроса на адрес /token на стороне Seeneco
5. Seeneco проверяет запрос и в случае успеха возвращает значение токена и минимальную информацию о пользователе(уникальный идентификатор пользователя в Seeneco), для которого был выдан токен
6. Партнерский сервис запрашивает информацию о пользователе. Это делается путем направления запроса по адресу /user_info, подписанного полученным ранее токеном. В состав этой информации входит
   • Информация о пользователе ( уникальный идентификатор, наименование, email, телефон)
   • Информация об организации ( уникальный идентификатор, наименование, ИНН)
7. Получив подробную информацию о пользователе партнерский сервис идентифицирует по ней пользователя и регистрирует или (в случае если пользователь уже найден) авторизует его и перенаправляет в интерфейс.
8. В дальнейшем полученный токен доступа может использоваться для обращения к API Seeneco, такому как получение информации о банковских счетах пользователя или отправка платежных поручений в банк.

Как подключиться?

Для того чтобы подключиться к платформе Seeneco вам необходимо направить письмо с запросом на регистрацию сервиса по адресу по адресу api@seeneco.ru, включающее следующую информацию

1. Наименование сервиса. Например “Онлайн-бухгалтерия Seeneco и Партнеры”
2. Адрес входа в сервис через механизм сквозной авторизации. Например, https://seeneco-partner-service.ru/oauth/seeneco
3. Адрес на который осуществлять перенаправление пользователя по итогам успешной авторизации (redirectURI, см. ниже). Например, https://seeneco-partner-service.ru/oauth/api/client

В ответном письме вы получите следующие данные

1. Идентификатор вашего сервиса в Seeneco (в терминах спецификации OAuth – это client_id вашего сервиса). Например, seeneco_partner
2. Секретный ключ вашего сервиса (в терминах спецификации OAuth – это client_secret вашего сервиса). Например, seeneco_partner_secret
3. Информацию о тестовой среде, на которйо можно будет провести тестирование интеграции

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

1. Запрос кода авторизации GET /authorize. Описание API авторизации приведено здесь
2. Обработка кода авторизации и запрос токена POST /token. Описание API получения токена приведено здесь
3. Запрос данных о пользователе GET /user_info. Описание API получения информации о пользователе приведено здесь

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