5.4.2. Сценарий аутентификации с генерацией кода авторизации

5.4.2.1. Сценарий протокола аутентификации OpenID Connect с генерацией кода авторизации (режимы 1 и 2 [5]) требует выполнения следующих действий:

1. Клиент генерирует запрос аутентификации и, используя агент пользователя, отправляет запрос аутентификации на конечную точку авторизации сервера авторизации (подпункт 5.4.2.2).

2. Сервер авторизации аутентифицирует конечного пользователя и получает разрешение конечного пользователя на доступ клиента к запрошенным защищенным ресурсам (подпункты 5.4.2.5 и 5.4.2.6).

3. Сервер авторизации генерирует код авторизации и (при необходимости) подпись в формате JARM (режим 2 [5]), перенаправляет агент пользователя на клиента с кодом перенаправления 303, а также передает значение сгенерированного кода авторизации и (при необходимости) подписи в формате JARM (режим 2 [5]) на конечную точку клиента по адресу URI-переадресации <redirect_uri>, указанному в запросе аутентификации (подпункт 5.4.2.9).

4. Клиент запрашивает токен доступа, используя код авторизации, на конечной точке токена сервера авторизации (подпункт 5.4.2.10).

5. Сервер авторизации проверяет запрос токена и формирует ответ, содержащий ID токен, токен доступа и опционально токен обновления (подпункты 5.4.2.11 и 5.4.2.12).

6. Клиент получает ответ, содержащий ID токен, токен доступа и опционально токен обновления (подпункт 5.4.2.13), проверяет ID токен (пункт 6.7.2 [5]) и, если необходимо, получает информацию о конечном пользователе (подпункт 5.4.2.17).

5.4.2.2. Запрос аутентификации клиента включает следующие параметры (подраздел 6.2 [5]):

- <scope>: (обязательный) область запроса; определяет перечень свойств защищаемых данных конечного пользователя, к которым запрошен доступ; параметр <scope> должен содержать значение "openid";

- <response_type>: (обязательный) тип ответа и сценарий протокола авторизации; в данном сценарии используется следующее значение:

- "code" - возвращает код авторизации; используется в сценарии аутентификации с генерацией кода авторизации (режимы 1 и 2 [5]);

- <client_id>: (обязательный) идентификатор клиента, полученный при регистрации на сервере авторизации;

- <redirect_uri>: (обязательный) URI-переадресации, на который будет отправлен ответ;

- <state>: (обязательный) строковое значение, используемое для синхронизации состояния между запросом и обратным вызовом; используется для защиты от атак межсайтовых запросов (CSRF) (пункт 6.2.5 [5]); генерируется как случайная строка длины не менее 20 байт;

- <nonce>: (обязательный) случайное строковое значение, используемое для связывания запроса аутентификации с ID токеном и для защиты от атак повторного воспроизведения; генерируется как случайная строка длины не менее 20 байт;

- <code_challenge>: (обязательный) запрос подтверждения кода по технологии PKCE (подпункт 5.4.2.4);

- <code_challenge_method>: (обязательный) метод вычисления <code_challenge> на основе <code_verifier>; возможное значение: "St256" (подпункт 5.4.2.4);

- <request>: (опциональный) объект запроса; позволяет передавать параметры запроса аутентификации с цифровой подписью или кодом аутентификации клиента в форме JWT (подпункт 5.4.2.3);

- <request_uri>: (опциональный) позволяет передавать параметры запроса аутентификации по ссылке, а не по значению. Значением <request_uri> является URL-адрес, использующий https-схему со ссылкой на ресурс, содержащий значение объекта запроса в форме JWT;

- <response_mode>: (опциональный) сообщает серверу авторизации о механизме, который будет использоваться для возвращения параметров из конечной точки авторизации; значением параметра должно быть одно из значений, указанных в параметре <response_modes_supported> метаданных сервера авторизации (подпункт 5.4.4.1);

- <prompt>: (опциональный) список строк, которые указывают, должен ли сервер авторизации запрашивать у конечного пользователя повторную аутентификацию и согласие на доступ клиента к ресурсу. Определены значения:

- "none" - не требуется интерфейс пользователя,

- "login" - серверу авторизации рекомендуется запросить повторную аутентификацию,

- "consent" - серверу авторизации рекомендуется запросить у пользователя согласие на доступ к ресурсу,

- "select_account" - серверу авторизации рекомендуется запросить у пользователя выбор учетной записи;

- <max_age>: (опциональный) максимальный срок аутентификации, определяет допустимое время в секундах, прошедшее с момента последней активной аутентификации конечного пользователя сервером авторизации. Если истекшее время больше этого значения, сервер авторизации должен пытаться активно повторно аутентифицировать конечного пользователя. Если в запросе аутентификации присутствует параметр <max_age>, возвращаемый ID токен должен включать значение параметра <auth_time>;

- <acr_values>: (опциональный) запрашиваемые значения ссылки на класс контекста аутентификации конечного пользователя; значением является разделенная пробелами строка, определяющая значения <acr>, которые сервер авторизации может использовать для обработки данного запроса аутентификации (значения располагаются в порядке предпочтения) в соответствии с [6]; класс контекста аутентификации, которому соответствует выполненная аутентификация пользователя, должен возвращаться в качестве значения параметра <acr> ID токена.

Значения параметра <acr_values> и их толкование должны устанавливаться при проектировании сервера авторизации. Значения параметров должны соответствовать уровням доверия СТО БР БФБО-1.8-2024 [6]. Например, могут использоваться следующие значения этого параметра:

- "urn:rubanking:sca": идентификатор, определяющий контекст аутентификации, указывающий на применение усиленной (двухфакторной) аутентификации пользователя,

- "urn:rubanking:ca": идентификатор, определяющий контекст аутентификации, указывающий на применение однофакторной аутентификации пользователя.

Примечание. Дополнительные сведения по параметрам запроса аутентификации приведены в RFC 6749 (пункт 4.1.1 [16]) и в спецификациях OIDC (подпункт 3.1.2.1 [17]).

5.4.2.3. Также параметры запроса аутентификации могут быть переданы в качестве параметров (claims) JSON объекта запроса - JWT токена (пункт 6.2.4 [5]). JWT токен должен быть подписан и может быть зашифрован. JWT токен передается в кодировании Base64url (раздел 5 [20]) по значению через параметр <request>.

Примечание. Дополнительные сведения по передаче запроса авторизации от клиента к серверу авторизации приведены в пункте 3.1.2 [17] и разделе 6 [17].

5.4.2.4. PKCE

Технология PKCE (Proof Key for Code Exchange, ключ подтверждения передачи кода) предназначена для защиты от атаки копирования кода авторизации вредоносным программным обеспечением устройства, на котором исполняется агент пользователя, с последующим воспроизведением его в ложном запросе токена.

Действия по защите от такой атаки выполняются следующим образом (пункт 6.2.6 [5]):

- при формировании запроса аутентификации клиент генерирует случайную последовательность и формирует ее символьное представление <code_verifier>;

- клиент вычисляет значение параметра <code_challenge> в соответствии с выбранным методом <code_challenge_method>;

- если значение параметра <code_challenge> отсутствует или если сервер авторизации не поддерживает указанный <code_challenge_method>, сервер авторизации должен ответить соответствующим сообщением об ошибке;

- в составе запроса токена клиент передает серверу авторизации сохраненное ранее значение <code_verifier>;

- сервер авторизации, получив запрос токена, сравнивает полученное ранее в запросе аутентификации значение <code_challenge> с вычисленным на основе значения <code_verifier>, полученного в запросе токена;

- при несовпадении этих значений делается вывод о возможном навязывании кода авторизации злоумышленником; клиенту передается сообщение об ошибке.

Примечание. Дополнительные сведения о вычислении и проверке параметров технологии PKCE приведены в RFC7636 [38].

5.4.2.5. Если запрос аутентификации действителен, сервер авторизации пытается аутентифицировать конечного пользователя или определяет, аутентифицирован ли конечный пользователь (подраздел 6.3 [5]). Методы, используемые сервером авторизации для аутентификации конечного пользователя (например, имя пользователя и пароль, файлы cookie-сеанса и так далее), не регламентируются настоящим стандартом.

Сервер авторизации должен запрашивать аутентификацию конечного пользователя в следующих случаях:

- конечный пользователь еще не аутентифицирован;

- в запросе аутентификации указан параметр <max_age> и время, прошедшее с момента аутентификации конечного пользователя, превышает значение <max_age>;

- запрос аутентификации содержит параметр <prompt> со значением "login". В этом случае сервер авторизации должен повторно аутентифицировать конечного пользователя, даже если конечный пользователь уже аутентифицирован.

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

- запрос аутентификации содержит параметр <prompt> со значением "none". В этом случае сервер авторизации должен возвратить ошибку, если конечный пользователь еще не прошел аутентификацию или не может быть аутентифицирован в режиме без вывода сообщений.

При взаимодействии с конечным пользователем сервер авторизации должен использовать соответствующие меры против подделки межсайтовых запросов (CSRF) в соответствии с пунктом 10.2.1 [5] и перехвата кликов (Clickjacking) в соответствии с пунктом 10.3.5 [5].

5.4.2.6. После аутентификации конечного пользователя сервер авторизации должен получить его разрешение об авторизации доступа к запрошенному ресурсу, прежде чем предоставлять информацию клиенту (пункт 6.3.2 [5]). В случае если это определено параметрами запроса, разрешение может быть получено одним из следующих способов:

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

- путем установления согласия с помощью условий обработки запроса;

- другими способами (например, с помощью предыдущего административного согласования).

5.4.2.7. После успешной аутентификации конечного пользователя и получения его разрешения на доступ клиента к защищенному ресурсу сервер авторизации генерирует код авторизации и передает его на конечную точку клиента, указанную в параметре <redirect_uri> запроса аутентификации (подраздел 6.4 [5]). Параметры успешного ответа на запрос аутентификации:

- <code>: (обязательный) значение кода авторизации;

- <state>: (обязательный) значение параметра <state> запроса аутентификации, полученного от клиента.

При использовании технологии JARM (режим 2 [5]) ответ формируется и проверяется в соответствии с пунктом 5.4.5.

5.4.2.8. В случае ошибки при проверке запроса аутентификации либо в процессе аутентификации конечного пользователя сервер авторизации отвечает клиенту с указанием информации об ошибке. Подробнее параметры и коды сообщения об ошибке приведены в пункте 6.4.2 [5].

5.4.2.9. Получив успешный ответ на запрос аутентификации (пункт 6.4.3 [5]), клиент, в частности, проверяет, что значение параметра <state>, полученное в составе ответа, совпадает со значением параметра <state> в запросе аутентификации, переданном клиентом.

5.4.2.10. В случае успешной проверки ответа сервера авторизации клиент формирует и отправляет на адрес конечной точки токена запрос токена (пункт 6.5.1 [5]). Параметры запроса токена:

- <grant_type>: (обязательный) тип разрешения на доступ; в данном случае значением должна быть строка "authorization_code";

- <code>: (обязательный) значение кода авторизации, полученное от сервера авторизации;

- <redirect_uri>: (обязательный) URI-переадресации, на который будет отправлен ответ;

- <client_id>: (обязательный) идентификатор клиента, зарегистрированный сервером авторизации;

- <code_verifier>: (обязательный) сохраненное ранее подтверждение кода по технологии PKCE (подпункт 5.4.2.4).

Помимо запроса токена, серверу авторизации при этом должна быть передана информация, аутентифицирующая клиента в соответствии с выбранным методом аутентификации.

Примечание. Дополнительные сведения по запросу токена и процедурам его формирования и проверки указаны в пункте 4.1.3 [16] и подпункте 3.1.3.1 [17].

5.4.2.11. Сервер авторизации должен проверить запрос токена следующим образом (пункт 6.5.2 [5]):

- аутентифицировать клиента в соответствии с подразделом 5.5;

- убедиться, что код авторизации был выдан данному аутентифицированному клиенту;

- убедиться, что код авторизации действителен;

- убедиться, что код авторизации не использовался ранее;

- проверить, что значение <code_verifier> соответствует ранее полученному значению параметра <code_challenge> (пункт 6.2.8 [5] и подпункт 5.4.2.4);

- проверить, что значение параметра <redirect_uri> совпадает со значением параметра <redirect_uri>, которое было включено в начальный запрос аутентификации;

- убедиться, что использованный код авторизации был выдан в ответ на запрос аутентификации OpenID Connect.

5.4.2.12. Получив и успешно проверив запрос токена, сервер авторизации генерирует ID токен, токен доступа, а также, если необходимо, токен обновления и возвращает их клиенту как JSON-объекты в теле HTTP-ответа с кодом состояния 200 (ОК) по адресу <redirect_uri> (пункт 6.6.1 [5]). В ответе используется тип содержимого "application/json". Ответ должен включать следующие поля и значения заголовка HTTP-ответа:

Cache-Control: no-store

Pragma: no-cache

Параметры JSON структуры ответа на запрос токена:

- <access_token>: (обязательный) токен доступа;

- <token_type>: (обязательный) тип токена доступа; может иметь значение "Bearer";

- <expires_in>: (обязательный) срок действия токена доступа в секундах;

- <refresh_token>: (опциональный) токен обновления;

- <scope>: (опциональный) область свойств токена доступа; определяет подмножество области доступа запроса авторизации <scope>, к которому разрешен доступ сервером авторизации;

- <id_token>: (обязательный) ID токен, связанный с фактом разрешения на доступ к ресурсу.

В случае ошибки проверки запроса токена сервер авторизации должен ответить сообщением об ошибке. Параметры и формат сообщения об ошибке приведены в подпункте 5.4.2.8. В теле HTTP-ответа используется тип содержимого "application/json" с HTTP-ответом с кодом состояния 400.

Примечание. Дополнительные сведения по параметрам ответа на запрос токена и процедурам работы с ними (подпункты 3.1.3.3 и 3.1.3.4 [17]).

5.4.2.13. Клиент должен проверить правильность ответа на запрос токена следующим образом (пункт 6.6.2 [5]):

- клиент должен игнорировать нераспознанные параметры ответа;

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

- клиент должен проверить длины параметров с установленными в системе;

- клиент должен проверить правильность ID токена согласно пункту 6.7.2 [5].

5.4.2.14. ID токен - JSON веб-токен (JWT) (подраздел 5.7), который содержит параметры аутентификации конечного пользователя сервером авторизации.

ID токен включает по крайней мере следующие параметры (пункт 6.7.1 [5]):

- <iss>: (обязательный) идентификатор эмитента (сервера авторизации), источника ответа;

- <sub>: (обязательный) уникальный идентификатор субъекта, выданный сервером авторизации конечному пользователю;

- <aud>: (обязательный) аудитория, для которой предназначен данный ID токен; должна содержать идентификатор <client_id>;

- <exp>: (обязательный) срок действия; время, при наступлении и после наступления которого ID токен не должен приниматься к обработке;

- <nbf>: (опциональный) время, до которого ID токен не должен приниматься к обработке;

- <iat>: (обязательный) время, когда был выпущен ID токен; значением является число в формате JSON, представляющее количество секунд от 1970-01-01T0:0:0Z UTC до соответствующей даты/времени;

- <auth_time>: (обязательный, если в запросе аутентификации присутствует значение параметра <max_age>) время, когда выполнена аутентификация конечного пользователя;

- <nonce>: (обязательный в ответе на запрос токена) строковое значение, равное значению параметра <nonce> в запросе аутентификации;

- <acr>: (опциональный) регистрозависимая строка символов, определяющая класс контекста аутентификации в соответствии с [6], которому соответствует выполненная аутентификация конечного пользователя; значение этого параметра должно выбираться из списка, указанного в <acr_values> запроса аутентификации; сторонам, использующим этот параметр, следует согласовывать смысл используемых значений, которые могут зависеть от контекста; параметр <acr> должен присутствовать в ID токене, если в запросе аутентификации указано значение параметра <acr_values>;

- <c_hash>: (обязательный) хэш-значение кода авторизации;

- <s_hash>: (обязательный в ответе на запрос аутентификации) хэш-значение параметра <state>;

- <at_hash>: (обязательный в ответе на запрос токена) хэш-значение токена доступа;

- <azp>: (опциональный) идентификатор клиента, для которого был выпущен ID токен.

Примечание. Дополнительные сведения об использовании ID токена (раздел 2 [17]).

5.4.2.15. Токен доступа (access token) (пункт 6.7.3 [5]) - свидетельство, подтверждающее факт авторизации доступа к определенному ресурсу, выданное определенному клиенту сервером авторизации с одобрения владельца ресурса. Токен доступа указывает на конкретные области данных (<scope>), к которым разрешен доступ, длительность доступа и другие параметры. Токен доступа рассматривается как символьная строка, не несущая смысловой нагрузки для клиента и сервера авторизации. Требования и рекомендации по безопасному применению приведены в пунктах 10.3.2, 10.3.3 и 10.3.4 [5].

Примечание. Дополнительные сведения и рекомендации по безопасному применению токенов доступа (подраздел 16.18 [17]) (подраздел 3.1 и пункт 5.1.5 [53]).

5.4.2.16. Токен обновления (refresh token) (пункт Б.10 [5]) - символьная строка, используемая для получения токенов доступа. Токен обновления выдается клиенту сервером авторизации и используется для получения нового токена доступа, когда текущий токен доступа становится недействительным, или истекает его срок действия, или для получения дополнительных токенов доступа с идентичной или более узкой областью действия (раздел 12 [17]).

Данная функциональность не регламентируется настоящим документом и определяется на этапе разработки сервера авторизации исходя из его прикладных целей и задач.

5.4.2.17. Клиент может получить информацию о конечном пользователе либо с помощью извлечения ее из параметров ID токена, либо с помощью запроса к конечной точке UserInfo сервера авторизации (пункт Б.6 [5]).

Чтобы получить значения параметров информации о конечном пользователе, клиент может отправить запрос конечной точке UserInfo, используя токен доступа, полученный при аутентификации на сервере авторизации. Значения параметров в ответ возвращаются в виде JSON-объекта, который содержит набор пар - имя и значение параметра.

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

Примечания:

1. Настоящий документ не регламентирует функциональность уточнения информации о конечном пользователе. В случае ее реализации должен быть проведен анализ безопасности в соответствии с установленным законодательством Российской Федерации порядком.

2. Дополнительные сведения об алгоритмах работы в конечной точке UserInfo представлены в подразделе 5.3 [17].