Техническая информация о сервисе ВТБ ID

29.12.2023

Группа ВТБ

0

Описание сценария

Сценарий Web

1. Клиент выбирает вход через ВТБ ID

2. Сервис партнера перенаправляет пользователя (браузер) на url адрес ВТБ ID для аутентификации и авторизации: https://id.vtb.ru .

Ссылка содержит параметры авторизации партнера, тип запрашиваемого доступа

3. Пользователь авторизуется на id.vtb.ru и, при необходимости, дает согласие

4. Результат авторизации — код авторизации. Подробнее в п. Запрос авторизации

5. Приложение партнера обменивает авторизационный код на access токен и refresh токен в сервисе ВТБ ID. Адрес сервиса: https://id.vtb.ru/oauth2/token. Подробнее в п. Запрос токенов доступа (/oauth2/token). После чего сервис ВТБ ID возвращает access токен иrefresh токен

6. Приложение партнера запрашивает персональные данные пользователя, передавая access токен, подробнее в п. Получение персональных данных пользователя (/oauth2/me).

Адрес сервиса: https://gost-id.vtb.ru/oauth2/me. Для получения персональных данных нужно установить КриптоПро CSP, см. документы для скачивания «Инструкция по установке КриптоПро CSP». Access токен имеет ограниченный срок жизни, если нужно повторить запрос персональных данных, приложение партнера должно хранить refresh токен и обновлять access токен после истечения его срока жизни.

Подробнее в п. Обновление токенов доступа (refresh_token)

7. Клиент входит на сайт Партнера

Сценарий App

1. Клиент выбирает вход через ВТБ ID

2. Приложение Партнера перенаправляет пользователя в мобильное приложение ВТБ Онлайн по диплинку: https://online.vtb.ru/i/vtbid/ , параметры перечислены в п. Запрос авторизации

3. Пользователь выполняет авторизацию в сервисе ВТБ и, при необходимости, дает согласие на передачу данных

4. Результат авторизации — код авторизации. Приложение ВТБ перенаправляет пользователя в приложение Партнера по диплинку, указанному в параметре redirect_uri и передает код авторизации. Приложение партнера должно уметь обрабатывать диплинки (universal link/deeplink)

5. Приложение партнера должно обменять авторизационный код на access токен и refresh токен в сервисе VTBID, подробнее в п. Запрос токенов доступа (/oauth2/token).

Адрес сервиса: https://id.vtb.ru/oauth2/token . После чего сервис VTBID возвращает access токен и refresh токен

6. Приложение партнёра запрашивает персональные данные пользователя, передавая access токен, подробнее в п. Получение персональных данных пользователя (/oauth2/ me). Адрес сервиса: https://gost-id.vtb.ru/oauth2/me . Для получения персональных данных необходима установка программного обеспечения КриптоПро CSP, см. документы для скачивания «Инструкция по установке КриптоПро CSP». Access токен имеет ограниченный срок жизни, если необходимо иметь возможность повторить запрос персональных данных, приложение партнёра должно хранить refresh токен и обновлять access токен после истечения его срока жизни. Подробнее в п. Обновление токенов доступа (refresh_token)

7. Клиент входит в приложение Партнера

Описание запросов

1. Запрос авторизации

С этого начинается процесс авторизации. Пользователь переходит по предварительно сформированной ссылке:

Web:

App:

Параметр client_id

Уникальный идентификатор приложения партнера. Выдается ВТБ при регистрации приложения партнера, как пользователя сервиса ВТБ ID

Обязательно

Параметр response_type

Указывает, какой сценарий авторизации использовать. Поддерживаемое значение — code

Обязательно

Параметр redirect_ur

URL адрес, на который произойдет перенаправление пользователя после завершения авторизации (успешно или неуспешно). Этот URL должен быть внесен в список допустимых при регистрации приложения партнера. Если при регистрации приложения был указан адрес https://example.com/auth, то при авторизации должно быть передано такое же значение: redirect_uri=https://example.com/auth

Обязательно

Параметр state

Параметр для защитыот CSRF атак. Подробнее см. RFC-6749

Необязательно

Параметр scope

Разделенный пробелами список разрешений (области разрешений), для который требуется авторизация. Это может быть доступ к определённым данным профиля пользователя, перечень доступных данных см. в документах для скачивания «Данные пользователя». Запросить можно только те данные, которые были зарегистрированы в сервисе ВТБ ID для Партнера

Обязательно

Данные пользователя

509 Кб

Успешный ответ:

Перенаправление на адрес redirect_uri с параметрами код авторизации и state
Для app2app приложение ВТБ попытается открыть http ссылку. Приложение Партнера должно обработать universal link/deeplink и перевести пользователя на заданную в ссылке страницу

Пример ссылки:

https://partner.ru?state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7&code=7987d347-6460-4d2e-a515-72332c434522

Параметр code

Код авторизации (результат успешного завершения сценария авторизации). Код необходимо обменять на токены доступа

Обязательно

Параметр state

Значение параметра state, которое было отправлено в запросе на авторизацию

Обязательно

Ошибка:

Пример ссылки:

https://partner.ru?error=access_denied&error_message=Consentrequired

Параметр error

Тип ошибки, с которым завершился процесс авторизации. Описание ошибок см. в документах для скачивания «Перечень ошибок»

Обязательно

Параметр error_message

Краткое описание ошибки

Необязательно

2. Запрос токенов доступа (/oauth2/token)

Запрос выполняет обмен кода авторизации на токены доступа

Пример обмена кода авторизации на токены доступа: curl --location --request POST 'https: //id.vtb.ru/oauth2/token' \ --header 'Authorization: Basic YXRGb3BIWWZxRHFUd3BjTHlfdFdSWnhHbWdrYToyczNmTGFGX2tIMjVQX1E2ZkM1WXVTUHhU Mm9h' \

--header 'Content-Type: application/json' \

--data-raw '{

"grant_type": "code", 

"code": "83ca5003-a384-4858-8dca-20be4cd5eb36"

}'

Параметр grant_type

Согласно спецификации Oauth2, должно содержать значение "code"

Обязательно

Параметр code

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

Обязательно

Параметр Authorization

base64 закодированная строка, которая содержит clientId и client secret выданные партнеру на этапе регистрации приложения в ВТБ ID. Поле имеет формат: Authorization: Basic <base64 encoded client_id:client_secret>

Успешный ответ:

{

"scope": "openid", "access_token": "006fad70-c36c-4995-82e0-99cd86bc0c72",
"refresh_token": "91179b52-9a6e-4601-840d-bc518b796e87",

"id_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMzcwNTA2MSIsImF1ZCI6ImF0Rm9wSFlmcURxV HdwY0x5X3RXUlp4R21na2EiLCJhenAiOiJhdEZvcEhZZnFEcVR3cGNMeV90V1JaeEdtZ2thIiwic3Bfb mFtZSI6InZ0Yi1nYW1lLW1hc3RlcmNhcmQiLCJpc3MiOiJodHRwczovL2lkLnZ0Yi5ydSIsIm5iZiI6MT YzNDIwMjQ1MiwiaWF0IjoxNjM0MjAyNDUyLCJleHAiOjE2MzQyMDI3NTIsImFtciI6WyJjb2RlIl0sIm FjciI6Im1zYT1leUpZTFZWelpYSXRVMlZ6YzJsdmJpMUpSQ0k2SWpaalpUTTRZamRpTFRNeFl6UXR OR1UxWmkwNU0yRXhMVGxqWkRBeE4yTmpZekZsTkNJc0luSnZkWFJsVG1GdFpTSTZJa1JKVTBG VFZFVlNJaXdpYzJoaGNtUk9ZVzFsSWpvaVJFbFRRVk5VUlZJaUxDSllMVkpQVlZSRkxVNUJUVVVpT 2lKRVNWTkJVMVJGVWlJc0lsZ3RVMGhCVWtRdFRrRk5SU0k2SWtSSlUwRlRWRVZTSWl3aVdDMU VaV0oxWnlJNkltWmhiSE5sSWl3aVdDMUpibWwwYVdGMGIzSXRTRzl6ZENJNklrNHZRU0lzSWxnd FEyaGhibTVsYkNJNklrMXZZbWxzWlVKaGJtc3lJaXdpV0MxUWJHRjBabTl5YlNJNkluZGxZaUlzSW xndFRHOW5hVzR0VFc5a1pTSTZiblZzYkN3aVdDMVdaWEp6YVc5dUlqcHVkV3hzZlE9PSIsImF1dG hvcml6YXRpb25faWQiOiI4ZWVmNWY1MS03M2U0LTRkNDgtYjIyOS1jMGQ1MTJiOTdmNzEiLCJkb 21haW4iOiJtYXN0ZXIiLCJtc2Ffc2Vzc2lvbl9pZCI6IjZjZTM4YjdiLTMxYzQtNGU1Zi05M2ExLTljZDAxN 2NjYzFlNCJ9.T27T0VkR0gMAADQKeAJLXUVzPJsS88GQ51LKW072GGaG793rj0gQu2cyz_b3xyzu7 IgzAVHjCQFGzfoedSZtBKNkq0n540ekf8oq66rK_7P3RKcEvVUrLKt1LY5sw5XgW8E3LhX4un7AIHJ xLVmofRBUbuWJskvO8qX7zeic6CktFEBJHeO b25entEtfksYQnbr6cvQKKC6NMoVtKSqZgLQaRb : br Vcx8GoX9lGGPm PH9ZjLNH7mWU0XIhLKc4VVjud67S58dZHf34ib_ OzNXYrvuPwGor3ZS4-xL5atPxbENBZ0vIrggnxhWDHI0sB
HaVnOvms Q4e6Atx1fTbDQOw"

Параметр scope

Список разрешений, для которых действуют выданные токены

Обязательно

Параметр access_token

Токен доступа. Представляет собой уникальное значение определённого формата. Токен используется для доступа к VTBID API. Имеет ограниченное время жизни

Обязательно

Параметр refresh_token

Токен обновления. Требуется для получения новых токенов доступа. Одноразовый

Обязательно

Параметр id_token

Пользовательский JWT токен, который содержит некоторую информацию о пользователе. В частности, может использоваться для доступа к внутренним сервисам ВТБ и генерируется только при запросе разрешения openid

Необязательно

Ошибка:

{

"error": "invalid_grant",

"error_message": "No authorization code found"

}

Параметр error

Тип ошибки, с которым завершился запрос

Обязательно

Параметр error_message

Краткое описание ошибки

Необязательно

3. Обновление токенов доступа (refresh_token)

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

Пример: curl --location --request POST 'https:// id.vtb.ru/oauth2/token' -- header 'Authorization: Basic YXRGb3BIWWZxRHFUd3BjTHlfdFdSWnhHbWdrYToyczNmTGFGX2t IMjVQX1E2ZkM1WXVTUHhUMm9h'

\

--header 'Content-Type: application/json' \

--data-raw '{

"grant_type": "refresh_token",

 "refresh_token": "91179b52-9a6e-4601-840d-bc518b796e87«

Параметр Authorization

base64 — закодированная строка, которая содержит clientId и client secret, выданные партнеру на этапе регистрации приложения в VTBID. Поле имеет формат: Authorization: Basic <base64 encoded client_id:client_secret>

Обязательно

Параметр grant_type

Значение refresh_token

Обязательно

Параметр refresh_token

Токен обновления, полученный ранее на этапе запроса или обновления токенов

Обязательно

Успешный ответ:

{

"scope": "openid",

"access_token": "006fad70-c36c-4995-82e0-99cd86bc0c72",

"refresh_token": "91179b52-9a6e-4601-840d-bc518b796e87",

"id_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMzcwNTA2MSIsImF1ZCI6ImF0Rm9wSFlmcURxV HdwY0x5X3RXUlp4R21na2EiLCJhenAiOiJhdEZvcEhZZnFEcVR3cGNMeV90V1JaeEdtZ2thIiwic3Bfb mFtZSI6InZ0Yi1nYW1lLW1hc3RlcmNhcmQiLCJpc3MiOiJodHRwczovL2lkLnZ0Yi5ydSIsIm5iZiI6MT YzNDIwMjQ1MiwiaWF0IjoxNjM0MjAyNDUyLCJleHAiOjE2MzQyMDI3NTIsImFtciI6WyJjb2RlIl0sIm FjciI6Im1zYT1leUpZTFZWelpYSXRVMlZ6YzJsdmJpMUpSQ0k2SWpaalpUTTRZamRpTFRNeFl6UXR OR1UxWmkwNU0yRXhMVGxqWkRBeE4yTmpZekZsTkNJc0luSnZkWFJsVG1GdFpTSTZJa1JKVTBG VFZFVlNJaXdpYzJoaGNtUk9ZVzFsSWpvaVJFbFRRVk5VUlZJaUxDSllMVkpQVlZSRkxVNUJUVVVpT 2lKRVNWTkJVMVJGVWlJc0lsZ3RVMGhCVWtRdFRrRk5SU0k2SWtSSlUwRlRWRVZTSWl3aVdDMU VaV0oxWnlJNkltWmhiSE5sSWl3aVdDMUpibWwwYVdGMGIzSXRTRzl6ZENJNklrNHZRU0lzSWxn dFEyaGhibTVsYkNJNklrMXZZbWxzWlVKaGJtc3lJaXdpV0MxUWJHRjBabTl5YlNJNkluZGxZaUlzSW xndFRHOW5hVzR0VFc5a1pTSTZiblZzYkN3aVdDMVdaWEp6YVc5dUlqcHVkV3hzZlE9PSIsImF1dG hvcml6YXRpb25faWQiOiI4ZWVmNWY1MS03M2U0LTRkNDgtYjIyOS1jMGQ1MTJiOTdmNzEiLCJkb 21haW4iOiJtYXN0ZXIiLCJtc2Ffc2Vzc2lvbl9pZCI6IjZjZTM4YjdiLTMxYzQtNGU1Zi05M2ExLTljZDAxN 2NjYzFlNCJ9.T27T0VkR0gMAADQKeAJLXUVzPJsS88GQ51LKW072GGaG793rj0gQu2cyz_b3xyzu7 IgzAVHjCQFGzfoedSZtBKNkq0n540ekf8oq66rK_7P3RKcEvVUrLK t1LY5sw5XgW8E3LhX4un7AIHJxLVmofRBUbu
WJskvO8qX7zeic6 CktFEBJHeOb25entEtfksYQnbr6cvQKKC6NMo VtKSqZgLQaRbVcx 8GoX9lGGPmPH9Z
jLNH7mWU0XIhLKc4V Vjud67S58dZHf34ib_OzNXYrvuPwGor3ZS4- xL5atPxbENBZ0vIrggnxhWDHI0sBHa
VnOvmsQ4e6Atx1fTbDQOw"

Параметр scope

Список разрешений, для которых действуют выданные токены

Обязательно

Параметр access_token

Токен доступа. Представляет собой уникальное значение определённого формата.
Токен используется для доступа к VTBID API. Имеет ограниченное время жизни

Обязательно

Параметр refresh_token

Токен обновления. Требуется для получения новых токенов доступа. Одноразовый

Обязательно

Параметр id_token

Пользовательский JWT токен, который содержит некоторую информацию о пользователе.
В частности, может использоваться для доступа к внутренним сервисам ВТБ
и генерируется только при запросе разрешения openid

Необязательно

Ошибка:

{

"error": "invalid_grant", "error_message": "No authorization code found"

}

Параметр error

Тип ошибки, с которым завершился запрос

Обязательно

Параметр error_message

Краткое описание ошибки

Необязательно

4. Запрос на получение персональных данных пользователя (/oauth2/me)

Метод позволяет получить персональные данные клиента ВТБ. Для доступа используется access токен, полученный на этапе авторизации

Пример: curl -X GET "https:// gost-id.vtb.ru/oauth2/me?

scopes=name%20surname"

-H "accept: application/json"

-H "Authorization: Bearer a0b592b6-2d41-4ff9-9a7a-

11c7e831225a"

Параметр scopes

Разделенный пробелами список разрешений (данных пользователя). Перечень доступных данных см. в документах для скачивания «Данные пользователя». Запросить можно только те данные, которые были зарегистрированы в сервисе ВТБ ID для Партнера. При отсутствии параметра возвращается весь список разрешений, которые были запрошены при регистрации Партнера

Необязательно

Параметр Authorization

Bearer + access_token, полученный на шаге запроса токенов

Обязательно

Успешный ответ:

"surname": "Иванов",

"name": "Иван",

Параметр surname

Фамилия

Необязательно

Параметр name

Имя

Необязательно

Параметр patronymic

Отчество

Необязательно

Параметр gender

Пол

Необязательно

Параметр birthPlace

Место рождения

Необязательно

Параметр birthDate

Дата рождения

Необязательно

Параметр maritalStatus

Семейное положение

Необязательно

Параметр mainMobilePhone

Основной номер телефона

Необязательно

Параметр mobilePhone

Номер телефона

Необязательно

Параметр email

Адрес электронной почты

Обязательно

Параметр registrationAddress

Адрес регистрации (по паспорту)

Необязательно

Параметр temporaryAddress

Адрес временного проживания

Необязательно

Параметр actualAddress

Адрес фактического проживания

Необязательно

Параметр snils

Номер СНИЛС

Необязательно

Параметр inn

Номер ИНН

Необязательно

Параметр rfPassport

Номер Данные паспорта РФ

Необязательно

Параметр userId

Идентификатор пользователя

Необязательно

Ошибка:

{

"error": "invalid_scope",

"error_message": "Недопустимый список разрешений"

}

Параметр error

Тип ошибки, с которым завершился процесс авторизации. Описание ошибок см. в документах для скачивания «Перечень ошибок»

Обязательно

Перечень ошибок

453 Кб

Параметр error_message

Краткое описание ошибки

Необязательно

Вопросы и ответы

Сколько займет подключение ВТБ ID?

Настроить интеграцию можно за 1 день. Все зависит от количества сценариев.

Где посмотреть дополнительную информацию про ВТБ ID?

Бизнес-описание и этапы подключения можете посмотреть тут

Что делать, если заявка не отправляется?

Напишите нам на почту id@vtb.ru

Термины и сокращения

API

Application Programming Interface — сервисный контракт между двумя приложениями, который определяет, как они взаимодействуют друг с другом, используя запросы и ответы

Банк

Банк ВТБ (ПАО)

Партнер банка

Организация, заключившая договор с банком в целях использования сервиса VTBID

Пользователь

Клиент банка

VTBID

Сервис, который Банк предоставляет Партнеру

JWT

JSON Web Token — открытый стандарт (RFC 7519) для создания токенов доступа, основанный на формате JSON

universal link/deeplink

Ссылка, по которой пользователь сразу попадает в конкретный раздел приложения

Код авторизации

Уникальный набор символов (UUID/GUID), результат успешной аутентификации пользователя с помощью сервиса VTBID. Код авторизации связан с результатом аутентификации пользователя и согласием на предоставление данных пользователя банком Партнёру. Код авторизации одноразовый и имеет короткий срок действия

Access токен, токен доступа

Уникальный набор символов (UUID/GUID). Предоставляется банком Партнёру в обмен на Код авторизации. Обеспечивает доступ к API VTB ID для получения персональных данных Пользователя. Имеет ограниченный срок действия

Refresh токен, токен обновления

Уникальный набор символов (UUID/GUID). Используется для получение новой пары access и refresh токенов. Имеет ограниченный срок действия

ID token

JWT токен, содержащий информацию о пользователе

Scope

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

КриптоПро CSP

Комплекс программных средств для реализации механизмов хранения ключей и сертификатов с поддержкой ГОСТ Р 34.10-2012

Оставьте заявку прямо сейчас

Получите консультацию и начните интеграцию

Техническая информация о сервисе ВТБ ID

Описание сценария

Сценарий Web

Сценарий App

Описание запросов

1. Запрос авторизации

Web:

App:

Параметр client_id

Параметр response_type

Параметр redirect_ur

Параметр state

Параметр scope

Успешный ответ:

Параметр code

Параметр state

Ошибка:

Параметр error

Параметр error_message

2. Запрос токенов доступа (/oauth2/token)

Параметр grant_type

Параметр code

Параметр Authorization

Успешный ответ:

Параметр scope

Параметр access_token

Параметр refresh_token

Параметр id_token

Ошибка:

Параметр error

Параметр error_message

3. Обновление токенов доступа (refresh_token)

Параметр Authorization

Параметр grant_type

Параметр refresh_token

Успешный ответ:

Параметр scope

Параметр access_token

Параметр refresh_token

Параметр id_token

Ошибка:

Параметр error

Параметр error_message

4. Запрос на получение персональных данных пользователя (/oauth2/me)

Параметр scopes

Параметр Authorization

Успешный ответ:

Параметр surname

Параметр name

Параметр patronymic

Параметр gender

Параметр birthPlace

Параметр birthDate

Параметр maritalStatus

Параметр mainMobilePhone

Параметр mobilePhone

Параметр email

Параметр registrationAddress

Параметр temporaryAddress

Параметр actualAddress

Параметр snils

Параметр inn

Параметр rfPassport

Параметр userId

Ошибка:

Параметр error

Параметр error_message

Стайлгайд кнопки

Вопросы и ответы

Сколько займет подключение ВТБ ID?

Где посмотреть дополнительную информацию про ВТБ ID?

Что делать, если заявка не отправляется?

Термины и сокращения

Техническая документация