ТЕХНОЛОГИИ

Как подключить Bank ID: пошаговое руководство по использованию сервиса

Назад
24
December 2018

Что такое Bank ID?

BankID - это надежный способ удаленного подтверждения личности пользователя, через банк, в котором он обслуживается.

Как работает проверка через BankID?

  1. На сайте нажимаете на кнопку “Войти через Bank ID”;
  2. В открывшимся окне выбираете банк, которым пользуетесь: (например ПриватБанк, Ощадбанк.);

  3. Вводите логин/пароль своего банка. Подтверждаете, что готовы передать третьей стороне личную информацию;

  4. Вводите СМС пароль;

  5. Банк передаёт сайту информацию про Вас.

Где можно применять BankID?

  1. Взаимодействовать с государственными органами онлайн: заказ выписок, оформление субсидий и т.д.
  2. Авторизация на сайте. По механике использования он ничем не отличается от обычной авторизации на сайте с помощью facebook или G+ аккаунта.
  3. Верификация данных пользователя. Самой главной причиной подключить BankID, является набор данных, которые нам будут переданы банком, а именно:
  • ФИО;
  • дата рождения;
  • ИНН;
  • адрес регистрации;
  • номер телефона;
  • e-mail;
  • скан копии паспорта и ИНН.

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

Банки Украины, через которые можно пройти верификацию:

На данный момент существует два провайдера, через которые можно организовать проверку и в каждой подключены разные банки:

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

Как подключить BankID к сайту?

Все начинается с выбора BankID провайдера (НБУ и/или ПриватБанка) и заключения с ними договора о предоставлении услуг. После того, как все юридический вопросы будут решены, вам предоставят доступы (client_id и secret_key) к системе, с помощью которой вас будут идентифицировать при каждом запросе с вашего сайта.

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

Схематически, взаимодействие сайта с провайдером выглядит так:

Технические нюансы интеграции с BankID

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

По механике использования, BankID ничем не отличается от обычной авторизации на сайте с помощью вашего facebook аккаунта. Да и технически они очень схожи, т.к. они оба реализованы на базе протокола OAuth2.

Мы использовали готовое решение по работе с авторизационными протоколами OAuth2 на python и на базе него написали свое решение по получению данных пользователя.

Пошагово, взаимодействие с BankID провайдером выглядит так:

Шаг 1. После клика на кнопку ”авторизации с помощью BankID” на вашем сайте, перенаправляйте пользователя на сайт провайдера с вашим client_id и параметрами необходимыми для последующей работы.

Пример запроса к сервису для авторизации пользователя:

 https://{IP:port}/DataAccessService/das/authorize?response_type=
code&client_id=client_id&redirect_uri=http://vash/url/dlia/redirect  

где
https://{IP:port}/DataAccessService/das/authorize? - адрес, на который отправляется запрос;
client_id - id вашего проекта в системе bankID;
redirect_uri - ссылка по которой вам необходимо чтобы сервис перенаправил пользователя, после успешной авторизации на последнем;

Шаг 2. На стороне провайдера происходит процедура авторизации пользователя и после его перенаправляют по redirect_url, вместе с временным токеном, с помощью которого вы сможете единожды запросить авторизационный токен - access_token;

Пример запроса к сервису на получение access_token:

 http://vash-url-dlia-redirect?code=jOS6lz 

гдe
vash-url-dlia-redirect - redirect_uri который вы передали на втором шаге;
code - токен, который в дальнейшем вам будет необходим, для получения access_token;

Шаг 3. Данный шаг выполняется сразу после возвращения пользователя обратно. Вы должны отправить с сервера запрос провайдеру на получение “авторизационного токена” access_token, указав в запросе токен - code , полученный вами на предыдущем шаге;

Пример запроса к сервису для получения того самого access_token :

 https://{IP:port}/DataAccessService/oauth/token?grant_type=authorization_code&client_id=client_id&client_secret=SHA1{client_id+client_secret+code}&code=jOS6lz&redirect_uri=http://vash/url/dlia/redirect

Пример ответа от сервиса при запросе на получение access_token :

{"access_token":"095be9eb-01e7-4045-b60b-9d71581fb4d9","token_type":"bearer","refresh_token":"a3798f16-8039-49c9-9b61-82936977489d","expires_in":179} 

гдe
access_token - авторизационный токен;
token_type - тип авторизационного токена;
expires_in - через сколько токен станет невалидный (в секундах);
refresh_token - токен для обновления авторизационного токена;

Шаг 4. Ну и наконец, с помощью “авторизационного токена” вы можете отправить запрос на получение данных по пользователю.

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

 https://{IP:port}/ResourceService/checked/data 

тело запроса:



{ "cardToCheck":"nw5zznM73Jq2qBE6z8cu9unxV2iP5IxTLieygtW/q4pyd/tu2wKyG4Q/
CF9fGuLWDVMwsG1I6XTIM8oGjduN6Uns6U+/AEkh34sWSnS5L3aKHT0jiR3IIXwE6NAwG/FZwKzFaw3WEfCwfidxIlkFLZA++g11E1gGfRNPo4D7d39Q426opLrVYprhFEqKeJ4tKeqV5F9G739pR7pHC1nKdLHr9G6Lm0uPo0BLyuMikZWsujJK/MSx8LlnO5/NPS+lgVX77noXMMXwXGi61VCmFQEkcSlb4j7qYYswiL+ar8puOBHUG/F3XXCBOztMH+gsF8HH/lvpiRwr42DVx/F26Q==",
"fields":["firstName","middleName","lastName","phone","inn","clId","clIdText","birthDay","email","sex","resident","dateModification"],
"scans":[{"type":"passport","fields":["link","dateCreate","extension","dateModification"]},/*{"type":"zpassport","fields":["link","dateCreate","extension","dateModification"]},*//*{"type":"inn","fields":["link","dateCreate","extension","dateModification"]},*//*{"type":"personalPhoto","fields":["link","dateCreate","extension","dateModification"]}*/],
"addresses":[{"type":"factual","fields":["country","state","area","city","street","houseNo","flatNo","dateModification"]},/*{"type":"birth","fields":["country","state","area","city","street","houseNo","flatNo","dateModification"]}]*/,
"documents":[{"type":"passport","fields":["series","number","issue","dateIssue","dateExpiration","issueCountryIso2","dateModification"]},/*{"type":"zpassport",
"fields":["series","number","issue","dateIssue","dateExpiration","issueCountryIso2","dateModification"]}*/]} 

 

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



{"state":"ok","customer":{"type":"physical","inn":"1112618222",/*если есть открытый ключ, значение может выглядеть так: "inn":"fgvb5476/v8634c347f64tf4f/3452g2985f"*/"birthDay":"20.01.1973","clId":"46378c05eb48127552e60cffd086e6e34287ff04","firstName":"ЄВГЕН","lastName":"САЛО","middleName":"МИКОЛАЙОВИЧ","phone":"+380681231212","signature":"bad3419d8f4aee6945636e8b3fe7e492798e4564","addresses":[{"type":"factual","country":"UA","state":"ДНЕПРОПЕТРОВСКАЯ",Version 4.07 30.06.2016"city":"ДНЕПРОПЕТРОВСК","street":"МИРА","houseNo":"11","flatNo":"75","dateModification": "19.06.2015 00:47:36"},{"type":"birth","country":"UA","street":"Нет улицы","dateModification": "29.05.2014 17:52:25"}],"documents":[{"type":"passport","series":"ШО","number":"123456","issue":"ДНЕПРОПЕТРОВСКИМ РО УМВД","dateIssue":"11.06.1997","issueCountryIso2":"UA","dateModification": "29.05.2014 17:52:25"}],"scans":[{"type":"passport","link":"http://10.0.0.15:29932/DataAccessService/checked/scan/pasport","dateCreate":"09.04.2015","extension":"zip", "dateModification": "29.05.2014 17:52:25"},{"type":"zpassport","link":"http://10.0.0.15:29932/DataAccessService/checked/scan/zpasport","dateCreate":"09.04.2015"}]}}
 

Шаг 5. Данный шаг является дополнительным, потому его выполнение не является обязательным. Речь пойдет о refresh_token. С его помощью можно обновить access_token, без необходимости повторной авторизации со стороны пользователя.

Пример запроса на обновление access_token:

 https://{IP:port}/DataAccessService/oauth/token?grant_type=refresh_token&client_id=client_id&client_secret=SHA1{client_id+client_secret+refresh_token}&refresh_token=refresh_token

P.S. И что важно, я надеюсь вы еще не забыли про RSA ключи? Так вот напоминаю, что банки перед тем как отдать данные пользователя шифруют их с помощью публичного ключа, а вы должны на сервере их расшифровать с помощью закрытого ключа. Удачи, да прибудет с вами сила!

Какова же роль библиотеки, о которой мы говорили, спросите вы. Всем этим, собственно, она и занимается. Нам остается только дописать код для специфических вещей, вроде расшифровки данных клиента, формирования особенного секрета, который передается банку для проверки нашего сервиса и использование разных доменов для авторизации и получения клиентских данных. Да-да, вам следует учесть, что во время тестирования у вас будет тестовый сервер для отладки всего процесса, на бою же, у вас будет один домен, по которому будете ходить для авторизации и второй домен для получения токенов и клиентских данных. Вот такая вот еще одна ступень безопасности от украинского BankID.

Все вышесказанное идеально складывается, если мы говорим об авторизации пользователя. Но к примеру в нашем последнем проекте была одна “маааленькая” особенность - мы не авторизовали пользователя. Задача состояла только в том, чтобы получать данные пользователя для проверки личности. И одним из вариантов идентификации был BankID. Это несколько усложнило процесс, ведь помимо этого нужно было безопасно хранить данные пользователя в процессе многошаговой авторизации и последующей идентификации пользователя уже на нашем проекте. Но если бы все было просто, зачем бы нужны были мы?

Доверяй, но проверяй!

Также стоит упомянуть важную мелочь - проверяйте данные, которые передаете на BankID. Был случай, когда в результате опечатки мы передали неправильный client_secret.Тут нужно остановиться детальнее. Дело в том, что требуется передать не просто client_secret, а хеш от склееных client_id, client_secret и кода полученного от BankID. У нас же вместо результата хеширования отправлялось название функции (забыли поставить скобки) и вместо ошибки вроде invalid_credentials или invalid_secret приходила html-ка с единственным сообщением - подозрительный запрос. Мораль сей басни такова - проверяйте параметры и пишите тесты ибо надежды на нормальный ответ от внешних сервисов нет.

Спасибо за ваш интерес!

Мы с вами свяжемся в ближайшее время