(Это автоперевод моей статьи OAuth meets PDP, v1.1)

1. Введение

OAuth 2.0 и традиционные модели авторизации, такие как RBAC, ABAC и ReBAC, решают разные части задачи управления доступом:

  • OAuth описывает, как приложения получают делегированный доступ к защищённым ресурсам. Токены доступа содержат информацию о полномочиях, делегированных клиенту. При этом OAuth не определяет, как ресурсные сервера должны авторизовывать запросы от OAuth-клинетов стандартными механизмами авторизации.

  • С другой стороны, системы авторизации на основе архитектуры PEP/PDP позволяют проверять доступ к ресурсам согласно настроенным политикам. Обычно такие системы ничего не знают про OAuth-клиентов, скоупы и делегирование полномочий (authorization grants).

В этой статье я разбираю вариант связи эти двух миров, не меняя реализацию самого стандартного сервиса авторизации (PDP). В частности:

  • Как выразить OAuth-скоупы в политиках авторизации и токенах доступа.

  • Как представить OAuth-разрешания в традиционной архитектуре PEP/PDP.

  • Как авторизовывать API-запросы с помощью обычного PDP.

Исходные условия:

  • Разработчик не должен менять код универсального PDP.

  • Разработчик контролирует код выпуска токенов и выдачи OAuth-разрешений по согласию пользователя.

Примечание: Последние несколько лет я занимаюсь развитием облачного IAM, и это сильно повлияло на статью. Так что, многое что тут написано - то как видится проблема со стороны cloud-native архитектуры. В общем - это не обучающая статья, скорее описание идеи, в надежде, что она может пригодиться.

2. Как выразить OAuth-скоупы

На картинке ниже собраны части двух миров:

  • [чёрным] OAuth: тройка AS/client/resource API и владелец ресурса, который разрешает клиенту получить токен доступа (AT) с определёнными скоупами.

  • [синим] Архитектура PEP/PDP: API ресурса авторизует каждый внешний запрос через PDP, прежде чем допустить его к ресурсу.

OAuth и архитектура PEP/PDP

OAuth и архитектура PEP/PDP

Можно утверждать, что вызов API ресурсного сервера должен быть разрешён, только если выполняются условия:

  1. OAuth-клиенту разрешён скоуп, необходимый для выполнения запроса.

  2. Субъект, от имени которого действует клиент, имеет доступы, необходимые для выполнения запроса.

Другими словами, запрос должен попадать в пересечение разрешённых клиенту скоупов и фактических доступов субъекта:

Пересечение скоупов клиента и доступов субъекта

Пересечение скоупов клиента и доступов субъекта

Что в таком случае можно назвать скоупом? Обычно PEP, для авторизации запроса, вызывает что-то вроде PDP.Check(subject, operation, resource, ctx). Поэтому естественно представить отдельный скоуп как комбинацию {operation, resource, context}, где каждый элемент может быть опущен.

Из чего состоит скоуп

Из чего состоит скоуп

Если взять операцию как составляющую скоупа, то строительным блоком может быть именованный набор отдельных операций — op-scope. В «классическом» облачном IAM это также называют ролью (не путать с ролями в RBAC).

Пример: op-scope calendar.editor может обозначать именованный набор операций {calendar.event:lists, calendar.event:get, calendar.event:create, …}.

Если использовать и операцию, и ресурс, то скоуп превращается в пару res-scope: {op-scope, resource-filter}. В зависимости от бизнеса требований может быть полезно использовать res-scope вместо простого op-scope: так клиент ограничен не только какие операции он может выполнять от имени пользователя, но и набором ресурсов (resource boundary), за пределы которого он не сможет выйти.

Примеры:

  • OAuth-клиенту разрешено читать несекретные документы: {document.reader, label:unclassified}.

  • OAuth-клиенту разрешено записывать объекты внутри определённой иерархии: {storage.writer, "/foo/bar"}.

Если дополнить res-scope параметрами контекста, скоупы станут гораздо выразительнее, но и реализация системы заметно усложнится. Например, OAuth-клиенту можно разрешить переводить деньги на внешние счета, но только в пределах определённого бюджета.

Примечание: спецификация OAuth Rich Authorization Requests (RAR) предлагает структурированный способ описания детальных требований к авторизации. Но она не определяет, как ресурсный сервер должен обеспечивать выполнение этих требований. Структурированные скоупы в этом разделе — только иллюстрация того, как выразить OAuth-скоупы через политики авторизации, которые поддерживает конкретный PDP.

3. Архитектура где есть OAuth и PDP

В архитектуре PEP/PDP каждый входящий API-запрос перехватывает PEP, который далее обращается к PDP за решением об авторизации. То есть, PEP вызывает метод PDP.Check() и либо продолжает обработку запроса, либо возвращает ошибку авторизации.

Наша цель — выразить OAuth-сценарии средствами обычного PDP, не меняя его реализацию. Для этого понадобится OAuth-aware PDP — компонент, который понимает специфику OAuth и работает как умный прокси к обычному PDP.

Итак, OAuth-aware PDP будет:

  • Реализовывать метод Check(access_token, operation, resource, context).

  • Проверять валидность access_token.

  • Интерпретировать содержимое access_token и преобразовывать его в последовательность вызовов метода Check() стандартного PDP.

OAuth-aware PDP перед обычным PDP

OAuth-aware PDP перед обычным PDP

4. Как отобразить OAuth-сценарии на PEP/PDP

Рассмотрим следующие сценарии OAuth с точки зрения механики авторизации на стороне PEP/PDP:

  1. [UC.1] OAuth-клиент делает API-запрос, а выданный ему grant сохранён в системе.

  2. [UC.2] Администратор организации заранее разрешает OAuth-клиенту определённые скоупы для всех пользователей своего тенанта.

  3. [UC.3] OAuth-клиент делает API-запрос, при этом grant-ы представлены только в токене.

4.1 [UC.1] Grant, сохранённый в системе

4.1.1 Сохранение grants

Типичный OAuth flow можно представить как последовательность шагов:

AS/oauth/authorize?client_id={cid}?scopes… → пользователь выдаёт grant → Client/callback?code → access_token

Детали зависят от конкретного flow. Для нас здесь важны авторизация пользователем скоупов клиента и выпуск access_token.

Чтобы сохранить скоупы, разрешенные пользователем конкретному клиенту в системе, OAuth Authorization Server должен обратиться к PAP и создать политики, которые выражают скоупы, разрешённые конкретным grant-ом. Для этого

  • Создадим новый синтетический субъект в виде пары {subject, client} — субъект u+c на картинке ниже. Этот субъект не может аутентифицироваться, получать токены доступа и будет существовать только в конфигурации PDP, конечные пользователи его не увидят.

  • Зададим политику доступа, которая выражает разрешённые скоупы для субъекта u+c. Например, политика может быть набором биндингов доступу в виде троек (subject, role, resource).

Сохранение OAuth-grant через PAP

Сохранение OAuth-grant через PAP

Замечание по реализации 1: В зависимости от модели авторизации, поддерживаемой PDP, синтетический субъект можно явно регистрировать в системе, либо представить только как часть отношения авторизации. Важно, чтобы у него был детерминированный ID, который OAuth AS и OAuth-aware PDP могут получить из одних и тех же входных параметров. Например, для конструирования ID можно использовать схему delegation:{client_id}:{subject_id}.

Замечание по реализации 2: Поскольку OAuth AS должен создавать политики авторизации через универсальный PAP, у него окажется больше привилегий, чем необходимо. Это может быть или не быть проблемой в зависимости границ доверия, внутри самой системы. Чтобы улучшить архитектуру безопасности, я бы рекомендовал добавить OAuth-aware PAP. Он должен будет аутентифицировать OAuth AS и разрешать создание политик только для субъектов делегирования (u+c).

4.1.2 Содержимое токена

В этом сценарии, для авторизации токену доступа достаточно содержать sub и client_id. Скоупов в токене нет. Мы также предполагаем неявный контракт: отсутствие поля scopes в токене означает, что токен представляет сохранённые в системе полномочия, выданные OAuth-клиенту по умолчанию.

4.1.3 Процесс авторизации

Чтобы авторизовать входящий API-запрос, OAuth-aware PDP должен:

  • Выполнить все необходимые проверки для токена доступа.

  • Извлечь sub и client_id из токена и восстановить ID субъекта u+c по паре (sub, client_id).

  • Выполнить две проверки в стандартном PDP:

    • Check(u+c, operation, resource) — проверить, разрешают ли выданные пользователем скоупы текущий API-запрос.

    • Check(sub, operation, resource) — проверить фактические доступы конечного пользователя.

    • Обе проверки должны вернуть ALLOW.

Авторизация с сохранённым grant

Авторизация с сохранённым grant

4.2 [UC.2] Сохранённый административный grant

В этом сценарии администратор тенанта разрешает OAuth-клиенту скоупы по умолчанию для всех пользователей тенанта. Например, администратор даёт приложению CRM доступ к API календаря для всех пользователей организации. Так пользователям организации не придётся отдельно разрешать эти скоупы CRM-клиенту при входе.

Примечание: Я считаю, что Enterprise OAuth заслуживает отдельного подробного исследования. Use-case, описываемый в этой секции иллюстрирует идею основную идею относительно хранения разрешений и только.

В рамках этого дизайна предполагаем следующее:

  • Администратор тенанта разрешает OAuth-клиенту скоупы для всех пользователей тенанта.

  • Если отдельный пользователь разрешил OAuth-клиенту скоупы, работают оба grant: и на уровне тенанта, и персональный.

  • Администратор может запретить пользователям авторизовывать дополнительные скоупы OAuth-клиентам.Этот запрет будет работать на этапе выдачи grant, а не при авторизации API-запроса.

4.2.1 Сохранение grants

Протокол выдачи административного grant может быть разным:

  • Это может быть часть Authorization Code Grant, где у администратора явно спрашивают, выдаёт ли он доступ всему тенанту или только себе.

  • Отдельный flow установления доверия между OAuth-клиентом и тенантом/организацией, со своим control plane.

Чтобы представить OAuth grants, разрешённые на уровне тенанта, OAuth AS должен:

  • Создать специальный субъект для пары {tenant, client} — t+c. Этот субъект не может аутентифицироваться, получать токены доступа и будет скрыт от конечных пользователей.

  • Задать политику доступа, которая выражает разрешённые скоупы для t+c. Это может быть набор биндингов доступа в виде троек (subject, role, resource), вероятно — (subject, role, tenant).

4.2.2 Содержимое токена

Как и в UC.1: sub, client_id.

Токен также может явно содержать tenant ID, если система не умеет определять его по ID субъекта.

Для простоты по-прежнему считаем, что других скоупов в токене нет.

4.2.3 Процесс авторизации

Процесс похож на UC.1, но учитывает более сложный сценарий: у клиента могут быть grants как на уровне всего тенанта, так и от отдельных пользователей.

Чтобы авторизовать входящий API-запрос, OAuth-aware PDP должен:

  • Выполнить все необходимые проверки для токена доступа.

  • Извлечь sub и client_id из токена и восстановить ID субъекта u+c по паре (sub, client_id).

  • Восстановить ID субъекта t+c по паре (tenant_id, client_id), где tenant_id либо получен из токена, либо определён по субъекту.

  • Выполнить два этапа проверки в обычном PDP:

    • Проверить разрешённые скоупы: Check(t+c, operation, resource) OR Check(u+c, operation, resource).

    • Проверить доступы пользователя: Check(sub, operation, resource).

    • Оба пункта должны вычислиться в ALLOW.

Авторизация с административным и персональным grants

Авторизация с административным и персональным grants

4.3 [UC.3] Авторизация со скоупами из токена

Если система не сохраняет grant, разрешённые скоупы нужно положить в токен.

4.3.1 Содержимое токена

Для OAuth-aware авторизации необходимы следующие поля: sub, client_id, scopes. В зависимости от бизнес требований, scopes может быть представлен в форме op-scope или res-scope.

Например, токен, похожий на JWT, может выглядеть так:

{
	"sub": {subject_id},
	"client_id": {client_id},
	"scopes": [
		{
			"scope": {op-scope-name-1},
			"resource": {resource-filter-1}
		},
		...
	]
}

4.3.2 Процесс авторизации

Некоторые современные PDP позволяют PEP передавать временные политики, которые считаются доверенными в контексте конкретного запроса. Пример такой функциональности — OpenFGA Contextual Tuples.

Если система использует PDP, поддерживающий эфемерные политики, OAuth-aware PDP должен:

  • Выполнить все необходимые проверки для токена доступа.

  • Сформировать новый синтетический субъект token-sub, который представляет именно скоупы из токена.

    • Для ID субъекта можно выбрать схему delegation:token:{jti}, если у токена есть поле jti, или использовать другой идентификатор токена, например его fingerprint.

    • Главное — синтетические субъекты, полученные из токена, никогда не должны быть получателями grants, сохранённых в системе.

  • Извлечь scopes из токена и преобразовать их в эфемерную политику — набор доступов для token-sub.

  • Выполнить две проверки в обычном PDP:

    • Check(token-sub, operation, resource, ephemeral policy) — проверить, разрешают ли скоупы токена текущий API-запрос.

    • Check(sub, operation, resource) — проверить фактические доступы конечного пользователя.

    • Обе проверки должны вернуть ALLOW.

Авторизация с эфемерной политикой

Авторизация с эфемерной политикой

Примечание 1: Здесь нельзя использовать субъект u+c вместо token-sub, так как в этом случае стандартный PDP не сможет отличить сохранённые grants от временных, пришедших из токена. В результате токен потенциально получит больше полномочий, чем предполагал его создатель.

Примечание 2: Зтот способ предполагает, что стандартный PDP реализует временные политики через объединение сохранённых политик и временных, переданных в контексте запроса.

Если PDP не поддерживает временные/эфемерные политики, OAuth-aware PDP, вероятно, придётся эмулировать это поведение. Такой подход потребует от OAuth-aware PDP знания структуры ресурсов и политик, а также хотя бы частичного дублирования логики стандартного PDP. Такая реализация будет архитектурным компромиссом.

Авторизация без поддержки временных политик в обычном PDP

Авторизация без поддержки временных политик в обычном PDP

4.3.3 Отзыв grants

В отличие от UC.1 и UC.2, где grants реализованы как сохранённые политики авторизации, grants в токене действуют до истечения его срока или явного отзыва токена. Поэтому при реализации нужно решить, потребуется ли досрочный отзыв. Возможные подходы — проверять jti токена по списку отзыва или просто использовать короткоживущие токены доступа.

4.4 Собираем картинку целиком

Теперь можно собрать все три сценария в одну картинку. На деле картинок будет две — в зависимости от того, содержит ли токен конкретные скоупы.

Класс сценария: Токен не содержит скоупов.
Контракт между OAuth-aware и ванильным PDP: по схеме из пункта 4.2.3

Класс сценария: Токен содержит скоупы
Контракт между OAuth-aware и ванильным PDP: по схеме из пункта 4.3.2

Будет полезно, если бы OAuth-aware PDP возвращал разные причины отказа для неуспешной проверки OAuth grant и проверки доступов субъекта — зелёные и чёрные стрелки на схемах. Это позволит PEP отличать недостаточные OAuth-скоупы от недостаточных доступов самого субъекта.

Итоговая архитектура выглядит так: в общем случае нужны и OAuth-aware PDP, и OAuth-aware PAP(для взаимодействия с OAuth AS). PEP может быть универсальным, особенно если OAuth-aware PDP реализует стандартный API, например AuthZEN.

Итоговая архитектура

Итоговая архитектура

4.5 Какую еще пользу можно извлечь из современных PDP

При проверке доступов субъекта OAuth-aware PDP всегда должен передавать в стандартный PDP client_id из аутентифицированного токена как доверенный атрибут контекста. Например:

PDP.Check(sub, operation, resource, ctx.client_id = {token.client_id})

Это открывает полезные возможности на стороне обычного PDP, если он их поддерживает:

  • Условные политики доступа: администратор может выдать пользователям определённые доступы, которые работают только при обращении к конкретному API через одобренный OAuth-клиент.

  • DENY-правила: запретить некоторым OAuth-клиентам доступ к чувствительным ресурсам.

  • Эфемерные политики + условные политики доступа: такой выразительности может хватить для авторизации OAuth RAR grants, включенных в токен доступа.

  • Obligations: PDP может вернуть условное решение об авторизации, которое требует дополнительных действий на стороне PEP или пользователя, для того чтобы доступ был окончательно разрешён. Облигации могут быть сгенерированы как при проверке OAuth grants, так и при авторизации доступов конечного пользователя.

5. Что дальше?

В этой статье я не рассматриваю client credentials, token exchange, многостороннюю авторизацию и другие полезные сценарии делегирования. Мне кажется, здесь есть хорошие перспективы для дальнейшего исследования.

Ближайшая идея, которой я хочу заняться, — сочетание ограничивающих и разрешающих структур в токенах. На мой взгляд, чтобы полноценно работать с PDP, OAuth-токены могли бы выглядеть так:

{
	actor: {active-actor},
	scopes: [
		{
			scope: {permissions-scope},
			resource: {resource-filter}
		},
		...
	],
	delegations: [
		{
			delegator_subject: {sub-1}
			scope: {permission-scope},
			resource: {resource-filter}
		},
		...
	],
	...
}

При таком дизайне можно было бы конструировать токены, которые одновременно ограничены по скоупам/ресурсам и содержат активные делегации от нескольких субъектов. Это позволило бы выполнять транзакции над сложными ресурсами, которыми управляют разные стороны. И, потенциально — поддержать сценарии использования ресурсов, выходящие за пределы одного административного домена/тенанта.

6. Заключение

В статье предложен архитектурный паттерн для OAuth-aware авторизации в архитектуре PEP/PDP. У паттерна есть несколько полезных свойств:

  • Не нужно менять реализацию стандартного/ванильного PDP, если его модель политик поддерживает необходимую семантику авторизации.

  • Делегированные OAuth-скоупы можно моделировать как обычные доступы, которые можно выразить политиками конкретного PDP.

  • Отзыв можно реализовать изменением сохранённой политики, без отзыва токенов доступа.

  • Подход работает с разными моделями авторизации, если OAuth AS / OAuth-aware PDP выполняют необходимую работу по отображению скоупов в существующую модель.