| Версия | Дата | Автор | Комментарий |
|---|---|---|---|
| 1.0.0 | Обновление согласно утвержденному стандарту Банка России |
Настоящий стандарт разработан Ассоциацией развития финансовых технологий (Ассоциацией ФинТех) при участии Центрального банка Российской Федерации (Банка России).
ПРИНЯТ И ВВЕДЕН в действие приказом Банка России от 19 декабря 2025 года № ОД-2888 «О введении в действие стандарта Банка России СТО БР «Открытые программные интерфейсы. Профили Открытых программных интерфейсов для расширенного режима безопасности. Технический стандарт».
Настоящий стандарт не может быть полностью или частично воспроизведен, тиражирован и распространен в качестве официального издания без разрешения Банка России.
Настоящий стандарт содержит принципы и рекомендации по реализации протокола взаимодействия OpenID Connect (OIDC) при осуществлении взаимодействия через Открытые программные интерфейсы с использованием расширенного профиля безопасности API, обеспечивающего высокий уровень доверия к идентификации и аутентификации при передаче финансовой информации.
Настоящий стандарт рекомендован к использованию организациями при обмене финансовыми сообщениями в среде Открытых программных интерфейсов.
Настоящий стандарт предназначен для:
Положения настоящего стандарта носят рекомендательный характер и применяются совместно со следующими документами:
В настоящем стандарте применяются термины и определения в соответствии с ФАПИ.СЕК, БФБО 1.8, СТО БР «Открытые программные интерфейсы. Глоссарий», а также следующие термины и определения:
Настоящий стандарт определяет два профиля безопасности OpenID Connect для использования в среде Открытых программных интерфейсов:
Выбор профиля безопасности осуществляется в зависимости от требований к уровню доверия при передаче финансовой информации и должен быть указан в прикладных стандартах и спецификациях API.
В профиле УДА 2 рекомендуется использование гибридного потока (Hybrid Flow) с использованием кода авторизации и ID токена.
Клиент должен аутентифицироваться методом private_key_jwt. Допускается использование метода tls_client_auth в качестве дополнительного.
В профиле УДА 3 обязательно использование гибридного потока с обязательным подписанным объектом запроса (request).
Клиент должен аутентифицироваться только методом private_key_jwt. Использование tls_client_auth допускается исключительно в дополнение к private_key_jwt.
ID Token в обоих профилях должен содержать следующие обязательные claims:
Дополнительные claims определяются прикладными стандартами комплекса Открытых API.
Согласно МР OIDC протокол OpenID Connect предоставляет три различных режима использования при генерации кода авторизации, в зависимости от уровня защиты и требований к передаче данных:
Расширенный профиль безопасности API требует обязательности применения гибридного потока с кодом авторизации для протокола OpenID Connect (Режим 3). При этом в соответствии с разделом 7.2.1 пункт 7 ФАПИ.СЕК участники могут применять Режим 2 (JARM). Сервер авторизации должен заявлять о поддерживаемых параметрах response_mode в своих метаданных.
Метод аутентификации private_key_jwt используется для того, чтобы клиент OAuth 2.0 аутентифицировался перед сервером авторизации, подписывая JWT (JSON Web Token) с помощью своего приватного ключа. Сервер авторизации затем проверяет этот JWT с использованием публичного ключа клиента, который он хранит или извлекает из URL JWKS клиента. Этот метод обеспечивает высокий уровень безопасности за счет асимметричной криптографии.
Клиент создает JWT с обязательными полями:
Клиент подписывает JWT с помощью своего приватного ключа для подписи авторизационных запросов. Применяемый ключ должен быть связан с публичным сертификатом, размещенным на JWKS и доступным серверу авторизации по идентификатору клиента (client_id) и идентификатору ключа (kid). Цифровая подпись должна быть вычислена по алгоритму ГОСТ Р 34.10-2012 согласно раздела 9.2.2 МР OIDC, за исключением случаев, когда контекст взаимодействия требует или допускает другие алгоритмы.
{
"kid": "S1a01AAV",
"alg": "GOST341012"
}{
"iss": "f917546e7a194df9bd02342632cd944f",
"sub": "f917546e7a194df9bd02342632cd944f",
"aud": "https://sb-as.openbankingrussia.ru/sandbox/as/aft/connect/token",
"exp": 1658763062,
"iat": 1658762462,
"jti": "90729a20-5eee-4035-9113-5c731e9e2c63"
}"IuboWQdp6iMKaZMWYPQAhqvSY_h346YOLu7vciLPM6cBn5d0xGEZI89ptVz7wu33IHxfJs6_ya13Q19cX72mPw"Клиент отправляет запрос с параметрами:
Когда сервер авторизации получает запрос с параметром client_assertion, он должен подтвердить подлинность JWT и аутентификацию клиента с помощью следующих проверок:
Если любая из этих проверок не проходит, сервер авторизации возвращает ошибку (например, invalid_request или invalid_client), указывая на конкретную проблему.
Пример ответа с ошибкой:
{
"error": "invalid_client",
"error_description": "The provided client_assertion is invalid."
}Если аутентификация успешна, сервер авторизации выдает клиенту токен доступа и, при необходимости, refresh token.
Тип доступа client_credentials используется для идентификации клиента в контексте, где отсутствует Пользователь и не требуется его согласие. Данный тип доступа поддерживается при аутентификации клиента на сервере авторизации поставщика услуг с использованием механизма аутентификации private_key_jwt (в соответствии с разделом 7.3 МР OIDC). При этом клиент, при запросе к конечной точке токена (POST /token), использует тип разрешения на доступ client_credentials в сочетании с assertions и jwt_bearer.
Запрос к конечной точке токена содержит метод POST, соответствующие заголовки и тело запроса.
| Параметр | Описание | Обязательность |
|---|---|---|
| grant_type | Тип доступа. В данном случае указывается значение client_credentials. | Обязательный |
| scope | Область действия. Определяет права доступа, которые запрашивает клиент. | Обязательный |
| client_assertion_type | Тип утверждения клиента (urn:ietf:params:oauth:client-assertion-type:jwt-bearer). | Обязательный |
| client_assertion | Значение client_assertion, созданное и подписанное на предыдущем этапе. | Обязательный |
POST /sandbox/as/aft/connect/token HTTP/1.1
Host: sb-as.openbankingrussia.ru
Content-Type: application/x-www-form-urlencoded
Content-Length: 819
---
grant_type=client_credentials &scope=accounts
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ...
{
"access_token": "eyJhbGciOiJQUzI1NiIsImtpZCI6IjdGMzZFMDAwMUFBRTFGOE...",
"refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "accounts"
}{
"nbf": 1660571646,
"exp": 1660575246,
"iss": "https://sb-as.openbankingrussia.ru/sandbox/as/aft",
"aud": "https://sb-as.openbankingrussia.ru/sandbox/as/aft/resources",
"client_id": "f917546e7a194df9bd02342632cd944f",
"scope": "accounts",
"jti": "4a07d081dc9b248c18f67d9acf9346bb841c1c9fb3e8faa69beb113eda6c3071",
"client_jwks_uri": "https://sb-jwks.openbankingrussia.ru/sandbox/jwks/f917546e7a194df9bd02342632cd944f",
"cnf": {
"x5t#St256": "C7qKLMKk_bJmQNCgT8MB50VV0d4HJBFgKANg25-Nj60"
}
}Тип доступа refresh_token используется для получения нового токена доступа на сервере авторизации, когда текущий токен доступа становится недействительным или истекает срок его действия.
Когда в запросе аутентификации запрашивается scope=offline_access, сервер авторизации выдает refresh token, что обеспечивает клиенту возможность получать новые токены доступа с помощью refresh token, не требуя от Пользователя заново проходить процесс аутентификации. offline_access не меняет сам токен доступа, но добавляет refresh token, который нужен для долгосрочного доступа к ресурсам, когда Пользователь не активен. Без offline_access клиент получает только токен доступа, срок действия которого ограничен. По истечении срока действия токена клиент запрашивает новый токен доступа через новую аутентификацию Пользователя.
| Параметр | Описание | Обязательность | Пример значения |
|---|---|---|---|
| grant_type | Тип доступа. В данном случае указывается значение refresh_token. | Обязательный | |
| refresh_token | Токен обновления, полученный в потоке с кодом авторизации и с использованием области доступа offline_access. | Обязательный | dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4... |
| client_assertion_type | Тип client_assertion, определяющий, что клиент использует JWT для аутентификации. Значение: urn:ietf:params:oauth:client-assertion-type:jwt-bearer. |
Обязательный | urn:ietf:params:oauth:client-assertion-type:jwt-bearer |
| client_assertion | JWT, используемый для аутентификации клиента на сервере авторизации. | Обязательный | eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ... |
POST /sandbox/as/aft/connect/token HTTP/1.1
Host: sb-as.openbankingrussia.ru
Content-Type: application/x-www-form-urlencoded
---
grant_type=refresh_token &refresh_token=dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ...
{
"access_token": "eyJhbGciOiJQUzI1NiIsImtpZCI6IjdGMzZFMDAwMUFBRTFGOE...",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "accounts offline_access"
}{
"nbf": 1660571646,
"exp": 1660575246,
"iss": "https://sb-as.openbankingrussia.ru/sandbox/as/aft",
"aud": "https://sb-as.openbankingrussia.ru/sandbox/as/aft/resources",
"client_id": "f917546e7a194df9bd02342632cd944f",
"scope": "accounts offline_access",
"sub": "1e3a7d4a-d213-416d-b4d3-ac8000f9d1d0",
"jti": "6e8f4a47dc9b248c18f67d9acf9346bb841c1c9fb3e8faa69beb113eda6c3071",
"client_jwks_uri": "https://sb-jwks.openbankingrussia.ru/sandbox/jwks/f917546e7a194df9bd02342632cd944f",
"cnf": {
"x5t#St256": "C7qKLMKk_bJmQNCgT8MB50VV0d4HJBFgKANg25-Nj60"
}
}Гибридный сценарий протокола OIDC с кодом авторизации (authorization_code) используется в соответствии с разделом 5.4.3 ФАПИ.СЕК и ограничениями, определенными в Главе 7 ФАПИ.СЕК. Запрос аутентификации должен выполняться с параметром типа запрашиваемого ответа (response_type) равного значению “code id_token” и использовать только параметры, включенные в подписанный объект запроса (параметр request). При этом клиент при запросе к конечной точке токена (POST /token) использует тип разрешения на доступ (grant_type) authorization_code в сочетании с assertions и jwt_bearer.
| Параметр | Описание | Обязательность | Пример |
|---|---|---|---|
| scope | Область доступа. Определяет перечень свойств защищаемых данных Пользователя, к которым запрашивается доступ. Требования к применению: • должен содержать значение прикладной области доступа (например, accounts). • должен содержать значение openid, указывающее на то, что клиент запрашивает аутентификацию Пользователя с помощью OpenID Connect и должен быть возвращен ID-токен. • для получения refresh_token должен содержать значение offline_access. |
Обязательный | openid accounts offline_access |
| response_type | Тип ответа и сценарий протокола авторизации; в данном сценарии используется значение "code id_token". | Обязательный | code id_token |
| response_mode | Значение, которое информирует сервер авторизации об используемом механизме, который возвращает параметры конечной точки авторизации; может принимать значение "fragment". | Опциональный | fragment |
| client_id | Идентификатор клиента, полученный при регистрации на сервере авторизации. | Обязательный | 4abd59d5970247969965a4f317a8f817 |
| redirect_uri | URI переадресации, на который будет отправлен ответ. | Обязательный | https://localhost.ru/cb |
| state | Строковое значение, используемое для синхронизации состояния между запросом и обратным вызовом; используется для защиты от атак межсайтовых запросов (CSRF); генерируется как случайная строка длиной не менее 20 байт. | Обязательный | 98d6691382344e7fb03c853739d0a988 |
| nonce | Случайное строковое значение, используемое для связывания запроса аутентификации с ID токеном и для защиты от атак повторного воспроизведения; генерируется как случайная строка длиной не менее 20 байт. | Обязательный | 642c0152a40a46bbb82bfda4e0799990 |
| request | Объект запроса; позволяет передавать параметры запроса аутентификации с цифровой подписью или кодом аутентификации клиента в форме JWT; обязательный для расширенного профиля безопасности. | Обязательный | eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJyZXNwb2... |
| code_challenge | Запрос подтверждения кода по технологии PKCE (Режима 2) - обязательный (Режима 3) - опциональный |
— | eHprXzdhQ0tDd1NBOWlVT2FSSDA2S0tyNJhfTm m65o |
| code_challenge_method | метод вычисления code_challenge на основе code_verifier (параметры PKCE определены в разделе 6.2.6 МР OIDC). | Обязательный, если указан code_challenge | st256 |
| login_hint | Подсказка серверу авторизации об конечном Пользователе для входа в систему. Например, может содержать ИНН, КПП юридического лица, от имени которого ожидается авторизация Пользователя. | Опциональный | {"taxId":"7728240000","taxType":"991230001"} |
Объект запроса (request) должен содержать параметр claims (подробнее OpenID Connect Core 1.0 раздел 5.5. Requesting Claims using the "claims" Request Parameter), который включает следующие объектные элементы:
Идентификатор ресурса согласия (далее consent_id) служит уникальным идентификатором согласия Пользователя. Платформы, использующие Открытые программные интерфейсы, Поставщики услуг и Сторонние поставщики услуг могут использовать consent_id для получения и проверки статуса согласия Пользователя, гарантируя, что согласие получено и соблюдается надлежащим образом.
Минимизация данных и безопасность
Стандарты Открытых программных интерфейсов подчеркивают принципы минимизации данных и безопасности, обеспечивая сбор, обработку и передачу только необходимой информации во время операций. Параметр openbanking_intent_id поддерживает эти принципы, обеспечивая механизм связи запросов на авторизацию с конкретным намерением Пользователя дать долгосрочное согласие или провести операцию, минимизируя риск несанкционированного доступа к персональным данным.
Связь намерения с процессом аутентификации
Открытые программные интерфейсы требует строгой аутентификации Пользователя для определенных действий, таких как инициирование платежей или доступ к конфиденциальным финансовым данным. Протокол OIDC позволяет включать значение consent_id в параметр объекта запроса openbanking_intent_id. Передача объекта запроса через параметр request служит средством связи процессов аутентификации и согласия. Это гарантирует синхронизацию процесса получения согласия с потоком аутентификации, обеспечивая, что конкретное согласие Пользователя (которое уже определено) будет получено в контексте безопасного сеанса аутентификации.
Предотвращение несанкционированного доступа и контроль согласия
Связь намерения с процессом аутентификации помогает предотвратить несанкционированный доступ к данным Пользователя и гарантирует, что согласие будет получено контролируемым и проверяемым способом. Consent_id облегчает проверку, предоставляя точку отсчета для отслеживания истории действий и решений, связанных с согласием, что позволяет более точно и безопасно управлять процессом получения и использования согласия.
Пример демонстрирует включение openbanking_intent_id в следующие claims:
{
"kid": "S1a01AAV",
"alg": "GOST341012"
}
{
"response_type": "code id_token",
"state": "98d6691382344e7fb03c853739d0a988",
"scope": "openid accounts offline_access",
"nonce": "642c0152a40a46bbb82bfda4e0799990",
"exp": 1618760589,
"max_age": 86400,
"claims": {
"userinfo": {
"openbanking_intent_id": {
"value": "0c9df54a-b926-4853-acc2-e318c9bd7c33",
"essential": true
}
},
"id_token": {
"openbanking_intent_id": {
"value": "0c9df54a-b926-4853-acc2-e318c9bd7c33",
"essential": true
},
"acr": {
"values": ["urn:rubanking:sca", "urn:rubanking:ca"],
"essential": true
}
},
"participant": {
"tax_id": {
"value": "6148127514"
},
"tax_type": {
"value": "583501001"
}
}
},
"aud": "https://sb-as.openbankingrussia.ru/sandbox/as/aft",
"iss": "4abd59d5970247969965a4f317a8f817",
"client_id": "4abd59d5970247969965a4f317a8f817",
"redirect_uri": "https://localhost.ru/cb"
}Параметр login_hint используется для передачи серверу авторизации подсказки о том, какого Пользователя необходимо аутентифицировать. Значения параметра, представленные в виде JSON-объекта, необходимо передавать как URL-кодированную строку.
Пример преобразования JSON-объекта {"taxId":"7728240000","taxType":"991230001"} в URL-кодированную строку:
%7B%22taxId%22%3A%227728240000%22%2C%22taxType%22%3A%22991230001%22%7DПри проектировании сервера авторизации необходимо учитывать, что данный параметр является подсказкой, а для целевого указания необходимо включать информацию о Пользователе в заявленные свойства объекта запроса, используя запрашиваемые claims добавлять элемент participant.
Пример запроса:
https://sb-as.openbankingrussia.ru/sandbox/as/aft/connect/authorize?client_id=4abd59d5970247969965a4f317a8f817&response_type=code%20id_token&state=98d6691382344e7fb03c853739d0a988&redirect_uri=https://localhost.ru/cb&nonce=642c0152a40a46bbb82bfda4e0799990&scope=openid%20accounts%20offline_access&request=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJyZXNwb2...&login_hint=%7B%22taxId%22%3A%227728240000%22%2C%22taxType%22%3A%22991230001%22%7D| Параметр | Описание | Обязательность | Пример |
|---|---|---|---|
| code | Код авторизации, полученный после успешной аутентификации. | Обязательный | 10e5ded165a96d423aaa42a678cb9c09460963245 |
| id_token | ID токен, содержащий информацию о Пользователе и времени аутентификации. | Обязательный | eyJhbGciOiJSUzI1NiIsImtpZCI6IkQwM0I4NkE4MEJBNjBCQjM0... |
| state | Состояние, переданное в запросе аутентификации, возвращается для проверки. | Обязательный | 98d6691382344e7fb03c853739d0a988 |
| session_state | Состояние сеанса на сервере авторизации. | Опциональный | G6rAVS56SipMpkdgSH-ZM3nJggTXo9MQ74sK8VE3n3o29c1bf0fa |
Параметр session_state
session_state — опциональный параметр, возвращаемый в ответе на запрос авторизации и используемый для определения состояния сеанса Пользователя между клиентом и сервером авторизации. Он позволяет клиенту отслеживать изменения состояния сеанса, включая его завершение, разрыв соединения или повторную аутентификацию.
Пример успешного ответа
https://localhost.ru/cb#code=10e5ded165a96d423aaa42a678cb9c09460963245
&id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6IkQwM0I4NkE4MEJBNjBCQjM0...
&scope=openid%20accounts%20offline_access
&state=98d6691382344e7fb03c853739d0a988
&session_state=G6rAVS56SipMpkdgSH-ZM3nJggTXo9MQ74sK8VE3n3o29c1bf0faПример ошибки
https://localhost.ru/cb#error=invalid_request
&error_description=Invalid+request+parameters
&state=98d6691382344e7fb03c853739d0a988
&session_state=G6rAVS56SipMpkdgSH-ZM3nJggTXo9MQ74sK8VE3n3o29c1bf0fa| Параметр | Описание | Обязательность | Пример значения |
|---|---|---|---|
| iss | Эмитент токена. Значение URI сервера авторизации. | Обязательный | https://sb0.openbankingrussia.ru/sandbox0/as/aft |
| sub | Уникальный идентификатор субъекта, выданный сервером авторизации конечному Пользователю; регистрозависимая строка длиной не более 255 символов ASCII. | Обязательный | 1e3a7d4a-d213-416d-b4d3-ac8000f9d1d0 |
| aud | Идентификатор субъекта, представленного сервером авторизации, для которого выдается ID токен (должно быть равно значению "client_id" клиента). | Обязательный | a8cadb2f65944ce2b3b92ba21336ad53 |
| exp | Период актуальности токена; определяется ПУ при условии, что выбранное значение не влияет на качество сервисов, предоставляемых через Открытые программные интерфейсы. | Обязательный | 1607716325 |
| iat | Метка времени выпуска токена. | Обязательный | 1607716025 |
| auth_time | Метка времени события аутентификации Пользователя; обязательный при включении параметра "max_age". | Зависит от контекста | 1607716014 |
| nonce | Случайное значение, используемое в качестве условного идентификатора сессии обмена сообщениями. | Обязательный | 642c0152a40a46bbb82bfda4e0799990 |
| acr | Идентификатор типа контекста аутентификации. | Опциональный | urn:rubanking:sca |
| s_hash | Хэш-значение параметра; строковое значение, которое вычисляется сервером авторизации и проверяется клиентом как Base64url кодирование левой половины значения хэш-функции ГОСТ Р 34.11-2012 октетов ASCII представления значения параметра state, полученного в составе запроса аутентификации. | Обязательный | nVDApI-dUj2qei-oU9QeUw |
| at_hash | Хэш-значение токена доступа; вычисляется сервером авторизации и проверяется клиентом как Base64url кодирование левой половины значения хэш-функции ГОСТ Р 34.11-2012 октетов ASCII представления значения access token. | Опциональный | V1e8eU_GTK0-Z1_WF7n_JA |
| c_hash | Хэш-значение кода авторизации; строковое значение, которое вычисляется сервером авторизации и проверяется клиентом как Base64url кодирование левой половины значения хэш-функции ГОСТ Р 34.11-2012 октетов ASCII представления значения параметра code. | Обязательный | OATPHzlrPpzO3PpMPLNknQ |
| nbf | Время, до которого ID токен не должен приниматься к обработке. | Опциональный | 1607716025 |
| openbanking_intent_id | Идентификатор ресурса, к которому запрашивается авторизация. | Опциональный | 1726c4f8-af35-41ef-bd84-569fb4647e1a |
| amr | Массив строк в формате JSON, чувствительных к регистру. | Опциональный | ["password"] |
| alg | Идентификатор криптографического алгоритма цифровой подписи. | Обязательный | GOST341012 |
{
"alg": "GOST341012",
"type": "JWT"
}
{
"nbf": 1607716025,
"exp": 1607716325,
"iss": "https://sb0.openbankingrussia.ru/sandbox0/as/aft",
"aud": "a8cadb2f65944ce2b3b92ba21336ad53",
"iat": 1607716025,
"nonce": "642c0152a40a46bbb82bfda4e0799990",
"c_hash": "OATPHzlrPpzO3PpMPLNknQ",
"s_hash": "nVDApI-dUj2qei-oU9QeUw",
"sub": "1e3a7d4a-d213-416d-b4d3-ac8000f9d1d0",
"auth_time": 1607716014,
"openbanking_intent_id": "1726c4f8-af35-41ef-bd84-569fb4647e1a",
"amr": ["password"]
}Для обеспечения безопасности и подлинности ID токена необходимо выполнять следующие проверки в соответствии с разделом 6.7.2 МР OIDC по следующей последовательности шагов (ссылки указаны на разделы МР OIDC):
Если клиент получил ID токен, который не прошел проверку, то клиент прекращает текущий процесс аутентификации, не использует полученные данные и может инициировать повторную аутентификацию.
После успешной аутентификации Пользователя на сервере авторизации поставщика услуг, проверки ответа аутентификации и получения кода авторизации клиент использует запрос к конечной точке токена (POST /token) с разрешением на доступ (grant_type) authorization_code в сочетании с assertions и jwt_bearer для получения токена доступа и ID токен в обмен на код авторизации. Данный тип доступа поддерживается при аутентификации клиента на сервере авторизации поставщика услуг с использованием механизма аутентификации private_key_jwt (в соответствии с разделом 7.3 МР OIDC).
| Параметр | Описание | Обязательность | Пример значения |
|---|---|---|---|
| grant_type | Тип доступа. В данном случае указывается значение authorization_code. | Обязательный | authorization_code |
| code | Код доступа, полученный в запросе аутентификации. | Обязательный | dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4... |
| client_assertion_type | Тип client_assertion, определяющий, что клиент использует JWT для аутентификации. Значение: urn:ietf:params:oauth:client-assertion-type:jwt-bearer. |
Обязательный | urn:ietf:params:oauth:client-assertion-type:jwt-bearer |
| client_assertion | JWT, используемый для аутентификации клиента на сервере авторизации. | Обязательный | eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ... |
| code_verifier | Сохраненное при запросе аутентификации (раздел 6.2.3 ФАПИ.СЕК) подтверждение кода по технологии PKCE. | Опциональный | yJpc3MiOiJGdkldk61qWE1aas |
Пример запроса с обязательными параметрами grant_type=authorization_code, code, redirect_uri и client_id:
POST /sandbox/as/aft/connect/token HTTP/1.1
Host: sb-as.test.openbankingrussia.ru
Content-Type: application/x-www-form-urlencoded
---
grant_type=authorization_code
&code=40ac728b26bf06a078538a65c1f18f89a9e8554899cb45a2ff2c918dc7742fe7
&redirect_uri=https://localhost.ru/cb
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI0YmEzYjk4YTRjN m...Ссылка на описание параметров успешного ответа представлены в разделе "API - post /token".
Пример успешного ответа
{
"id_token": "eyJhbGciOiJSUzI1NiIsI...",
"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjU...",
"expires_in": 3600,
"token_type": "Bearer",
"refresh_token": "13e29519e3a09bca92ca9c3f41a886ca"
}Клиент может получить информацию о Пользователе, либо извлекая ее из параметров ID токена, либо с помощью запроса к конечной точке UserInfo сервера авторизации.
Клиент может отправить запрос конечной точке UserInfo, используя токен доступа, полученный при аутентификации на сервере авторизации и содержащий область, требуемую для данного метода область доступа (scope). Значения параметров в ответ возвращаются в виде JSON объекта, который содержит набор пар имя и значение параметра. Набор доступных клиенту параметров информации о Пользователе определяется в спецификации сервера авторизации.
Конечная точка UserInfo и id_token оба предоставляют информацию о Пользователе, но использование UserInfo имеет ряд преимуществ:
Таким образом, использование конечной точки UserInfo предпочтительно в сценариях, где требуется актуальная и безопасная передача информации о Пользователе, а также при необходимости минимизировать нагрузку на сервер авторизации.
Таким образом, использование конечной точки UserInfo предпочтительно в сценариях, где требуется актуальная и безопасная передача информации о Пользователе, а также при необходимости минимизировать нагрузку на сервер авторизации.
Сервер авторизации должен поддерживать использования токенов доступа, связанных с клиентским сертификатом TLS (MTLS-bound access tokens), как предусмотрено в пункте 6.3.1.2 ФАПИ.СЕК. Связывание токена доступа с MTLS сертификатом клиента осуществляется путем добавления в токен хэш-кода сертификата клиента. Этот механизм гарантирует, что только клиент, владеющий соответствующим сертификатом, может использовать токен доступа для выполнения запросов к защищенным ресурсам.
Привязка к сертификату происходит следующим образом:
Для проверки токена, связанного с MTLS сертификатом, сервер ресурсов должен убедиться, что клиент, предъявляющий токен, использует тот же сертификат, который был связан с этим токеном на этапе его выдачи. Проверка включает следующие шаги:
Пример включения хэш-кода сертификата клиента в декодированный токен доступа:
{
... ,
"cnf": {
"x5t#St256": "значение хэша TLS сертификата клиента"
}
}При получении запроса на выдачу токена доступа сервер авторизации выполняет ряд проверок, в зависимости от запрашиваемого типа доступа (значение параметра grant_type).
Цель: Предоставить токен на основе авторизационного кода, полученного Пользователем после успешного прохождения процесса аутентификации.
Цель: Предоставить токен доступа клиенту без участия Пользователя, для доступа к защищенным ресурсам.
Цель: Обновить токен доступа, используя ранее выданный refresh token.
Сервер авторизации обязан возвращать параметр scope в ответе на запрос токена только если выданный токен доступа имеет меньше прав (более узкую область доступа), чем клиент запрашивал. Если предоставленная область доступа полностью соответствует области доступа запроса, scope может быть не возвращаться. В случае запроса токена с типом доступа refresh_token область доступа запроса определяется как область действия токена обновления.
Сервер авторизации возвращает токен доступа в ответ на успешную аутентификацию клиента. Проверка ответа включает:
При использовании refresh token для обновления токена доступа, проверка ответа включает:
Проверка ответа токена при использовании кода авторизации, включая PKCE (Proof Key for Code Exchange), включает:
Доступ клиента к защищенному ресурсу обеспечивает сервер ресурсов. Выполняя запрос, клиент передает серверу ресурсов полученный от сервера авторизации токен доступа в поле заголовка запроса Authorization с использованием схемы аутентификации Bearer.
Доступ клиента к серверу ресурсов должен осуществляться по защищенному каналу с использованием двухсторонней аутентификации по протоколу TLS.
Сервер ресурсов предоставляет доступ после проверки токена доступа. Проверка может быть проведена на API шлюзе, обеспечивающем доступ к серверу ресурсов, с использованием информации, полученной от сервера авторизации.
Раздел 6.7.5.2 МР OIDC требует выполнения следующих условий:
Токен доступа должен проверяться сервером ресурсов на соответствие схеме безопасности securityScheme, определённой в OpenAPI Specification для вызываемого метода application/json:
При доступе к ресурсам Пользователя в рамках среды Открытых программных интерфейсов сервер ресурсов должен проверить согласия Пользователя и соответствующих разрешений, если они указаны в согласии. Требования к проверкам согласия клиента определяются в прикладных стандартах Открытых программных интерфейсов.
Когда Пользователь отзывает своё согласие на доступ к данным, все связанные с данным согласием токены доступа (access tokens) и токены обновления (refresh tokens) должны быть немедленно отозваны на стороне сервера авторизации с целью предотвращения несанкционированного использования данных.
Если необходимо принудительно аннулировать действующий токен, сервер авторизации может реализовать, а клиент использовать конечную точку отзыва токенов. Сервер авторизации должен заявлять о поддерживаемых методах в своих метаданных.
| Параметр | Описание | Обязательность | Пример значения |
|---|---|---|---|
| token | Токен, который необходимо отозвать. Может быть access_token или refresh_token. | Обязательный | dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4... |
| token_type_hint | Тип токена. Значения: access_token или refresh_token. | Рекомендуемый | refresh_token |
| client_assertion_type | Тип client_assertion. Значение: urn:ietf:params:oauth:client-assertion-type:jwt-bearer. | Обязательный | urn:ietf:params:oauth:client-assertion-type:jwt-bearer |
| client_assertion | JWT для аутентификации клиента. Используется для проверки подлинности отзыва запроса. |
Обязательный | eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ... |
Пример запроса:
POST /sandbox/as/aft/connect/revocation HTTP/1.1
Host: sb-as.openbankingrussia.ru
Content-Type: application/x-www-form-urlencoded
---
token=dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...
&token_type_hint=refresh_token
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ...Спецификация API определяет следующие конечные точки:
| Наименование API | Метод | Путь | Обязательность | Описание |
|---|---|---|---|---|
| Метод авторизации | GET | /authorize | Да | Запрос аутентификации |
| Token | POST | /token | Да | Запрос токена |
| UserInfo | GET | /userinfo | Да | Запрос информации о Пользователе Client Authorization code flow; scopes: obruprofile: Получение информации о Пользователе |
Запрос аутентификации (get /authorize).
Конечная точка, используемая клиентом для получения авторизации от владельца ресурса посредством перенаправления агента Пользователя.
| Наименование | Обязательность | Тип | Описание | Паттерн |
|---|---|---|---|---|
| scope | Да | String | Область действия; определяет свойства защищаемых данных Пользователя, к которым запрошен доступ; в случае использования протокола OpenID Connect параметр должен содержать строку “openid” | /^[\w\W]{1,80}$/ |
| response_type | Да | ResponseType | Тип ответа и сценарий протокола авторизации; в данном сценарии используется следующее значение: – “code id_token”: возвращает код авторизации и ID токен | /^[\w\W]{1,15}$/ |
| redirect_uri | Да | URI; format: uri | URI перенаправления, на который сервер авторизации отправит ответ. Должен точно совпадать с зарегистрированным URI клиента. | |
| state | (Да) | String | Значение, используемое для синхронизации состояния между запросом и обратным вызовом; используется для защиты от атак межсайтовых запросов (CSRF) | /^[\w\W]{27,512}$/ |
| client_id | Да | String | Идентификатор клиента, полученный при регистрации на сервере авторизации | |
| response_mode | Нет | ResponseMode | Значение, которое информирует сервер авторизации об используемом механизме, который возвращает параметры конечной точки авторизации. | /^[\w\W]{1,10}$/ |
| nonce | Да | String | Случайное строковое значение, используемое для привязки сеанса клиента к ID токену и для защиты от атак повторного воспроизведения | /^[\w\W]{27,512}$/ |
| request | Да | RequestParameters | Объект запроса | |
| login_hint | Нет | String | Подсказка серверу авторизации о Пользователе для входа в систему. (Например может содержать ИНН, КПП юридического лица, от имени которого ожидается авторизация пользователя). | /^[\w\W]{1,2048}$/ |
Данный метод API предоставляет следующий тип данных (media types): text/html.
Значение типа данных должно быть передано клиентом в параметре заголовка запроса - Accept: text/html и возвращено продюсером в ответе в виде заголовка - Content-Type: text/html.
| HTTP код | Тип ответа |
|---|---|
| 303 | String |
| 400 | Error |
| 500 | Error |
Запрос токена (post /token).
Получение токена доступа дает возможность получить данные конкретного Пользователя (т.е. получить доступ к защищенному ресурсу). Токены доступа являются кратковременными и по мере достижения срока жизни должны заменяться путем обмена токена обновления на новый токен доступа.
Данный метод API использует следующие типы мультимедиа через заголовок запроса Content-Type: application/x-www-form-urlencoded
| Наименование | Обязательность | Тип | Описание | Паттерн |
|---|---|---|---|---|
| X-Request-ID | Нет | UUID; format: uuid | RFC4122 UID, используемый в качестве идентификатора запроса или корреляции. В случае, если Сервер авторизации поддерживает корреляцию запросов, то он может возвращать обратно значение данного идентификатора в заголовке ответа | X-Request-ID |
| Наименование | Обязательность | Тип | Описание | Паттерн |
|---|---|---|---|---|
| grant_type | Да | GrantType | ||
| client_assertion_type | Да | ClientAssertionType | ||
| client_assertion | Да | String | Утверждение, используемое для аутентификации клиента. Используется формат JWT | /^[\w\W]{32,8192}$/ |
| client_id | Нет | String | Идентификатор сервиса клиента | /^[\w\W]{1,40}$/ |
| code | Нет | String | Код авторизации | /^[\w\W]{27,512}$/ |
| code_verifier | Нет | String | Сохраненное при запросе аутентификации (раздел 6.2.3 ФАПИ.СЕК) подтверждение кода по технологии PKCE | /^[\w\W]{32,128}$/ |
| redirect_uri | Нет | URI; format: uri | URI переадресации, на который будет отправлен ответ; значение этого параметра должно совпадать со значением параметра "redirect_uri" запроса авторизации | /^[\w\W]{1,2048}$/ |
| refresh_token | Нет | String | Токен обновления | /^[\w\W]{32,2048}$/ |
| scope | Нет | String | Область применения | /^[\w\W]{1,40}$/ |
TokenEndpointSuccessfulResponse
Данный метод API предоставляет следующие типы данных (media types): application/json
Значение типа данных должно быть передано клиентом в параметре заголовка запроса Accept: application/json и возвращено продюсером в ответе в виде заголовка Content-Type: application/json.
| HTTP код | Тип ответа |
|---|---|
| 200 | TokenEndpointSuccessfulResponse |
| 400 | Error |
| 429 | |
| 500 | Error |
Запрос информации о Пользователе (get /userInfo).
Конечная точка возвращает подписанную JWS информацию о Пользователе, прошедшем аутентификацию и авторизовавшем предъявленный токен доступа.
| Наименование | Обязательность | Тип | Описание | Паттерн |
|---|---|---|---|---|
| X-Request-ID | Нет | UUID; format: uuid |
RFC4122 UID, используемый в качестве идентификатора запроса или корреляции. В случае, если Сервер авторизации поддерживает корреляцию запросов, то он может возвращать обратно значение данного идентификатора в заголовке ответа X-Request-ID |
String
Данный метод API предоставляет следующие типы данных (media types): application/jwt
Значение типа данных должно быть передано клиентом в параметре заголовка запроса Accept: application/jwt и возвращены продюсером в ответе с указанием в параметре заголовка Content-Type: application/jwt.
| HTTP код | Тип ответа |
|---|---|
| 200 | String |
| 400 | Error |
| 401 | |
| 403 | Error |
| 405 | Error |
Спецификация API определяет типы и форматы данных, значения по умолчанию, перечисления и справочную информацию.
Контейнер с детализацией ошибки
| Наименование | Обязательность | Тип | Описание | Шаблон/Список |
|---|---|---|---|---|
| error | Да | string | Код ошибки | |
| error_description | Нет | string | Некорректный запрос к серверу |
Раздел для указания Essential Claim
| Наименование | Обязательность | Тип | Описание | Шаблон/Список |
|---|---|---|---|---|
| essential | Да | boolean | Указывает, запрашивается ли Claim как Essential Claim. |
Определяет структуру запрашиваемых Claims. Необходимо использовать один из элементов.
| Наименование | Обязательность | Тип | Описание | Шаблон/Список |
|---|---|---|---|---|
| essential | Да | boolean | Указывает, запрашивается ли Claim как Essential Claim. | |
| value | Да | string | Указывает значение запрашиваемого Claim | |
| values | Нет | array[String] | Указывает список значений запрашиваемого Claim |
| Наименование | Обязательность | Тип | Описание | Шаблон/Список |
|---|---|---|---|---|
| exp | Да | integer | Срок действия; время, при наступлении и после наступления которого объект запроса считается недействительным; значением является число в формате JSON, представляющее количество секунд от 1970-01-01T0:0:0Z UTC до соответствующей даты/времени | |
| max_age | Нет | integer | Максимальный срок аутентификации, определяет допустимое время в секундах, прошедшее с момента последней активной аутентификации Пользователя сервером авторизации. Если истекшее время больше этого значения, сервер авторизации должен пытаться активно повторно аутентифицировать Пользователя. Если в запросе аутентификации присутствует параметр <max_age>, возвращаемый ID токен должен включать значение параметра <auth_time> | |
| claims | Да | RequestParameters_claims | ||
| aud | Да | string; format: uri | Идентификатор субъекта, для которого предоставляется объект запроса (содержит URL сервера авторизации) | |
| iss | Да | string | Идентификатор субъекта, выпустившего объект запроса (соответствует client_id клиента, отправляющего запрос) | /^[\w\W]{32,2048}$/ |
| client_id | Да | string | Идентификатор клиента OAuth 2.0, полученный при регистрации на сервере авторизации | /^[\w\W]{4,8192}$/ |
| redirect_uri | Да | string; format: uri | URI переадресации, на который будет отправлен ответ. Должен быть предварительно зарегистрирован на сервере авторизации | |
| response_type | Да | string | Тип ответа, указывающий, что клиент ожидает в ответ (code для кода авторизации) | |
| state | Да | string | Параметр для поддержания состояния между запросом и обратным вызовом | |
| scope | Да | string | Область действия | |
| nonce | Да | string | Случайное значение, используемое в качестве условного идентификатора сессии обмена сообщениями между Сторонним поставщиком и сервером авторизации | |
| code_challenge | Нет | AnyType | ||
| code_challenge_method | Нет | AnyType |
Верхнеуровневый список запрашиваемых параметров claims
| Наименование | Обязательность | Тип | Описание | Шаблон/Список |
|---|---|---|---|---|
| id_token | Нет | Map_Option_RequestIndividualClaim | ||
| userinfo | Нет | Map_Option_RequestIndividualClaim | ||
| participant | Нет | Map_Option_RequestIndividualClaim | Информация об участнике (юридическое или физическое лицо, кто запросил аутентификацию). Используемые значения параметра для запрашиваемых свойств: tax_id – Опциональный - ИНН участника. tax_type – Опциональный - КПП участника. Указывается для юридических лиц только при наличии значения параметра tax_id. |
| Наименование | Обязательность | Тип | Описание | Шаблон/Список |
|---|---|---|---|---|
| access_token | Да | string | Токен доступа | /^[\w\W]{32,4096}$/ |
| id_token | Нет | string | Токен идентификации | /^[\w\W]{32,4096}$/ |
| token_type | Да | TokenType | Тип токена доступа | |
| expires_in | Да | integer; format: int64 | Срок жизни токена в секундах | |
| scope | Нет | string | Область применения | /^[\w\W]{1,40}$/ |
| refresh_token | Нет | string | Токен обновления | /^[\w\W]{32,2048}$/ |
| Наименование | Обязательность | Тип | Описание | Шаблон/Список |
|---|---|---|---|---|
| value | Да | string | Указывает значение запрашиваемого Claim |
| Наименование | Обязательность | Тип | Описание | Шаблон/Список |
|---|---|---|---|---|
| values | Нет | array[String] | Указывает список значений запрашиваемого Claim | |
| essential | Нет | boolean | Указывает, запрашивается ли Claim как Essential Claim. |
Тип утверждения клиента. Имеет значение urn:ietf:params:oauth:client-assertion-type:jwt-bearer
Тип доступа. Сообщает конечной точке токена, что клиент использует тип предоставления кода авторизации
Значение, которое информирует сервер авторизации об используемом механизме, который возвращает параметры конечной точки авторизации. Расширенный профиль безопасности требует fragment
Тип ответа и сценарий протокола авторизации; в данном сценарии используется следующее значение: – “code id_token” (возвращает код авторизации и ID токен).
Тип токена (имеет значение Bearer - токен на предъявителя)