Перейти к содержанию

Фреймворк авторизации агентов

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

В этом документе описана модель агентской авторизации, призванная дать итоговому Верификатору однозначное понимание того, что именно Пользователь разрешил Агенту сделать. AP2 применяет эту модель применительно к платежам, однако сама модель может быть использована и для более широкого круга задач.

Процесс авторизации разделён на два этапа:

  • Делегирование мандата (Mandate Delegation): Пользователь уполномочивает Агента выполнить некоторое действие (или набор действий) от своего имени. Пользователь утверждает содержимое мандата (Mandate Content) на Доверенной Поверхности (Trusted Surface), после чего результирующий Мандат делегируется Агенту.
  • Авторизация действия (Action Authorization): Верификатор запрашивает у Агента доказательство того, что тот уполномочен выполнить действие от имени Пользователя. Агент предъявляет Верификатору соответствующий Мандат. По завершении Верификатор возвращает Агенту Квитанцию (Receipt).

Делегирование мандата

Делегирование мандата выполняется следующим образом:

  • Агент формирует содержимое мандата, которое должно быть авторизовано Пользователем.
  • Содержимое мандата отображается Пользователю на Доверенной Поверхности.
  • После авторизации и получения согласия Пользователя создаётся Мандат и передаётся обратно Агенту.
  • Агент сохраняет Мандат для последующего использования.

Документ определяет две модели делегирования мандатов:

  • Пользовательское удостоверение (User Credential)
  • Доверенный провайдер агента (Trusted Agent Provider)

Пользовательское удостоверение (User Credential)

Трёхсторонняя модель, включающая:

  • Эмитента пользовательского удостоверения (Issuer)
  • Доверенную Поверхность как Держателя пользовательского удостоверения (Holder)
  • Агента

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

Преимущество подхода — одно пользовательское удостоверение может делегировать мандаты множеству различных агентов без необходимости установления явных доверительных отношений Верификатора с каждым из них.

Делегирование через OpenID4VP

OpenID4VP предоставляет стандартный протокол для предъявления VDC от держателя верификатору. Ключевая возможность — transaction_data, позволяющая держателю цифрового удостоверения одобрить и подписать дополнительную информацию.

Для делегирования через OpenID4VP Агент формирует Authorization Request, в котором массив transaction_data содержит base64url-закодированные JSON-объекты. Объект делегирования мандата ДОЛЖЕН содержать:

  • type — строка "delegate"
  • format — требуемый формат VDC возвращаемого мандата
  • delegate_payload — массив с содержимым мандатов в виде JSON-объектов
  • delegate_disclosures (опционально) — массив выборочных раскрытий

Рекомендация

Для делегирования через OpenID4VP рекомендуется использовать Digital Credentials API там, где он доступен — это обеспечивает более высокий уровень безопасности и лучшее качество пользовательского опыта.

Доверенный провайдер агента (Trusted Agent Provider)

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

Шаги:

  • Агент формирует содержимое мандата и передаёт его на Доверенную Поверхность, контролируемую Провайдером Агента.
  • Доверенная Поверхность отображает содержимое пользователю и получает необходимую авторизацию и согласие.
  • Провайдер Агента использует безопасно хранимый ключ подписи для создания Мандата.

Провайдер Агента ОБЯЗАН гарантировать, что Агент не имеет доступа к ключу подписи и не может использовать его в обход Доверенной Поверхности.

Структура мандата

Мандаты образуют криптографически верифицируемую цепочку — от исходного мандата, утверждённого пользователем, до закрытого мандата, авторизующего конкретное действие у Верификатора.

Мандаты могут находиться в двух состояниях:

  • Закрытый (Closed): Мандат привязан к конкретной транзакции у Верификатора. Агент создаёт Key Binding JWT (Proof-of-Possession) с использованием ключа, подтверждённого в атрибуте cnf открытого мандата.
  • Открытый (Open): Мандат ещё не привязан к конкретной транзакции. Содержит набор ограничений (constraints) на допустимое содержимое закрытого мандата и привязан к конкретному Агенту, которому разрешено его использовать.

Открытые мандаты необходимы для обеспечения автономных действий Агента от имени Пользователя, сохраняя при этом надлежащий контроль над его поведением.

Мандаты на основе SD-JWT VC

SD-JWT предоставляют удобную структуру для криптографической защиты JSON и обладают рядом полезных свойств для мандатов:

  • Механизм Key Binding позволяет Агенту предоставить Proof-of-Possession и привязку к транзакции, когда пользователь уже не присутствует.
  • Выборочное раскрытие (Selective Disclosure) позволяет сохранить конфиденциальность пользователя, раскрывая лишь применимые части ограничений.

Содержимое мандата для SD-JWT включает следующие атрибуты:

  • vct (обязательный) — строка, уникально идентифицирующая тип мандата.
  • constraints (опциональный) — массив расширяемых объектов с ограничениями на допустимое содержимое закрытого мандата.
  • cnf (опциональный) — метод подтверждения, идентифицирующий ключ Proof-of-Possession согласно RFC7800. Обязателен, если мандат всё ещё открыт.

Правила верификации и обработки

  1. Проверить и обработать цепочку SD-JWT согласно Delegate SD-JWT.
  2. Извлечь атрибуты из содержимого открытого мандата и удостовериться, что закрытый мандат содержит те же значения без изменений.
  3. Извлечь каждое ограничение (Constraint) из содержимого каждого открытого мандата и оценить их относительно содержимого закрытого мандата на основе типа ограничения. Неизвестные ограничения должны трактоваться как не пройденная проверка.

Авторизация действия (Action Authorization)

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

  1. Верификатор и Агент взаимодействуют до момента, когда Верификатору требуется доказательство авторизации от человека.
  2. Верификатор запрашивает предъявление Мандата.
  3. Агент выбирает подходящий Мандат и предъявляет его. Если Мандат открытый — Агент использует ключ, подтверждённый этим Мандатом, для привязки к транзакции.
  4. Верификатор проверяет целостность Мандата и то, что его содержимое разрешает Агенту выполнить запрашиваемое действие.

При приёме или отклонении Мандата Верификатор ОБЯЗАН вернуть подписанную Квитанцию о мандате (Mandate Receipt) — JWT со следующими свойствами:

  • iss (обязательный) — эмитент JWT (Верификатор)
  • result (обязательный) — перечисление ["success", "error"]
  • reference (обязательный) — base64url-закодированный хеш полученного мандата
  • error (опциональный) — код ошибки (при result: "error")
  • error_description (опциональный) — человекочитаемое описание ошибки

Коды ошибок

  • invalid_credential — мандат не прошёл верификацию (терминальная ошибка)
  • unresolved_constraint — мандат содержит неизвестное ограничение или Верификатор не может проверить соответствие закрытого мандата ограничениям
  • invalid_mandate — предоставленный мандат не разрешает запрошенное действие (терминальная ошибка)
  • mandates_not_supported — Верификатор не поддерживает мандаты для данного действия

Нормативные ссылки