Перейти к основному содержимому

Авторизация в APISIX с использованием Casbin

· 5 мин. чтения
Rushikesh Tote
Member of Casbin
Yilia Lin
Apache APISIX Committer

Введение​

Apache APISIX может применять политики авторизации Casbin на шлюзе с помощью встроенного плагина authz-casbin. Плагин использует Lua Casbin и поддерживает модели контроля доступа, такие как ACL, RBAC и ABAC.

Это руководство размещает небольшую политику RBAC на пути запроса APISIX. Вы проверите разрешённые и отклонённые запросы, а затем обновите общую политику через метаданные плагина без изменения маршрута.

Сообщество Casbin изначально предложило интеграцию в APISIX Issue #4674, а APISIX PR #4710 добавил плагин.

Обновление августа 2026

Это руководство было обновлено в августе 2026 года. Примеры были проверены на Apache APISIX 3.17.0. Оригинальный автор 2021 года остаётся указан, а Илия Лин добавлена за обновление 2026 года.

Граница аутентификации

Casbin выполняет авторизацию, а не аутентификацию. В примере используется заголовок запроса user в качестве субъекта только для того, чтобы тест оставался небольшим. В производственной среде не доверяйте заголовку идентификации, предоставляемому непосредственно клиентом. Слой аутентификации или доверенный прокси должны устанавливать личность и удалять или перезаписывать недоверенные значения перед тем, как Casbin оценит запрос.

Предварительные требования и начальное состояние​

Это руководство начинается с одноразового экземпляра Apache APISIX 3.17.0, который уже запущен. Если вам нужен локальный экземпляр, следуйте руководству по развертыванию APISIX Docker и зафиксируйте образ APISIX на версии apache/apisix:3.17.0-debian.

Экземпляр должен иметь:

  • плоскость данных, доступную по адресу http://127.0.0.1:9080;
  • Admin API, доступный по адресу http://127.0.0.1:9180;
  • встроенные плагины authz-casbin и mocking включены.

Вам также потребуются curl и jq. Установите значение переменной admin_key, равное ключу, настроенному для вашего Admin API:

export admin_key='<your-admin-api-key>'

Замените заполнитель перед продолжением работы. Убедитесь, что Admin API доступен, и плагин включён:

curl --fail-with-body \
"http://127.0.0.1:9180/apisix/admin/plugins/list" \
-H "X-API-KEY: $admin_key" | \
jq -e '(["authz-casbin", "mocking"] - .) | length == 0'

Команда должна вывести true. Не публикуйте Admin API в ненадёжной сети и не используйте демонстрационные учётные данные в другой среде.

Определение модели и политики​

Плагин оценивает три значения запроса:

  • sub: субъект из настроенного заголовка запроса;
  • obj: путь URI запроса; и
  • act: HTTP-метод.

Создайте файл model.conf:

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = (g(r.sub, p.sub) || keyMatch(r.sub, p.sub)) && keyMatch(r.obj, p.obj) && keyMatch(r.act, p.act)

Создайте файл policy.csv:

p, *, /anything, GET
p, admin, *, *
g, alice, admin

Эта политика разрешает любому субъекту отправлять запрос GET /anything. Она также назначает роль admin пользователю alice, который может получать доступ к любому пути любым методом.

Хранение общей политики в метаданных плагина​

Загрузите файлы как JSON-строки и запишите их в метаданные плагина APISIX:

jq -n \
--rawfile model model.conf \
--rawfile policy policy.csv \
'{model: $model, policy: $policy}' | \
curl --fail-with-body \
"http://127.0.0.1:9180/apisix/admin/plugin_metadata/authz-casbin" \
-H "X-API-KEY: $admin_key" \
-H "Content-Type: application/json" \
-X PUT \
--data-binary @-

Метаданные плагина предоставляют одну модель и политику маршрутам, которые включают плагин authz-casbin без определения собственной локальной модели и политики для маршрута.

Включение авторизации на маршруте​

Создайте маршрут и укажите плагину считывать субъект из заголовка user:

curl --fail-with-body \
"http://127.0.0.1:9180/apisix/admin/routes/casbin-demo" \
-H "X-API-KEY: $admin_key" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"uri": "/*",
"plugins": {
"authz-casbin": {
"username": "user"
},
"mocking": {
"_meta": {
"priority": 1000
},
"response_status": 200,
"response_example": "{\"message\":\"authorized\"}"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1": 1
}
}
}'

Маршрут использует модель и политику из метаданных плагина, так как он определяет только поле username локально. Локальная модель и политика маршрута, если они настроены, имеют приоритет над метаданными плагина.

Плагин mocking возвращает детерминированный локальный ответ для разрешённых запросов, поэтому пример не зависит от внешнего upstream-сервера. Его локальный приоритет для маршрута ниже, чем у плагина authz-casbin, что обеспечивает выполнение решения об авторизации первым. Таким образом, недоступный upstream-сервер не вызывается. Это переопределение приоритета и мок-ответ являются тестовыми фикстурами, а не рекомендациями для продакшена.

Проверка решений о разрешении и отказе​

Анонимный запрос к общедоступному пути разрешён:

curl -i http://127.0.0.1:9080/anything

Ожидаемый статус:

HTTP/1.1 200 OK
{"message":"authorized"}

У пользователя bob нет роли admin, поэтому запрос к другому пути отклоняется:

curl -i http://127.0.0.1:9080/anything/res -H 'user: bob'

Ожидаемый результат:

HTTP/1.1 403 Forbidden
{"message":"Access Denied"}

У пользователя alice есть роль admin, поэтому тот же запрос разрешается:

curl -i http://127.0.0.1:9080/anything/res -H 'user: alice'

Ожидаемый статус:

HTTP/1.1 200 OK
{"message":"authorized"}

Обновление общей политики​

Добавьте прямое разрешение для пользователя bob в файл policy.csv:

p, *, /anything, GET
p, admin, *, *
p, bob, /anything/res, GET
g, alice, admin

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

curl -i http://127.0.0.1:9080/anything/res -H 'user: bob'

Теперь ожидаемый результат:

HTTP/1.1 200 OK
{"message":"authorized"}

Выбор области конфигурации​

Используйте метаданные плагина, когда несколько маршрутов должны разделять одну модель и политику. Используйте локальную модель и политику маршрута, когда маршруту требуется независимая структура авторизации. Полную схему конфигурации и альтернативу на основе файлов см. в справочнике плагина APISIX authz-casbin.

Очистка​

Удалите тестовый маршрут:

curl --fail-with-body \
"http://127.0.0.1:9180/apisix/admin/routes/casbin-demo" \
-H "X-API-KEY: $admin_key" \
-X DELETE

Удалите общие метаданные плагина:

curl --fail-with-body \
"http://127.0.0.1:9180/apisix/admin/plugin_metadata/authz-casbin" \
-H "X-API-KEY: $admin_key" \
-X DELETE

Comments are powered by giscus and GitHub Discussions. They load from giscus.app and GitHub only after you click the button below.