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

shibboleth: Модуль запроса аутентификации Shibboleth для NGINX

Установка Debian/Ubuntu

Эти документы применимы к APT-пакету nginx-module-shibboleth, предоставленному репозиторием GetPageSpeed Extras.

  1. Настройте APT-репозиторий, как описано в настройке APT репозитория.
  2. Установите модуль:
sudo apt-get update
sudo apt-get install nginx-module-shibboleth
Показать версии и архитектуры 
| Дистрибутив | Версия            | Компонент   | Архитектуры     |
|-------------|-------------------|-------------|------------------|
| debian      | bookworm          | main        | amd64, arm64     |
| debian      | bookworm-mainline | main        | amd64, arm64     |
| debian      | trixie            | main        | amd64, arm64     |
| debian      | trixie-mainline   | main        | amd64, arm64     |
| ubuntu      | focal             | main        | amd64, arm64     |
| ubuntu      | focal-mainline    | main        | amd64, arm64     |
| ubuntu      | jammy             | main        | amd64, arm64     |
| ubuntu      | jammy-mainline    | main        | amd64, arm64     |
| ubuntu      | noble             | main        | amd64, arm64     |
| ubuntu      | noble-mainline    | main        | amd64, arm64     |

image

Этот модуль позволяет Nginx работать с Shibboleth через FastCGI авторизатор Shibboleth. Для корректной работы этого модуля требуется специальная конфигурация, а также приложение авторизатора FastCGI Shibboleth, доступное в системе. По своему функционалу он стремится быть похожим на части Apache's mod_shib, хотя настройки аутентификации и авторизации Shibboleth настраиваются через shibboleth2.xml вместо конфигурации веб-сервера.

При этом модуле, настроенном в блоке location, входящие запросы авторизуются в Nginx на основе результата подзапроса к FastCGI авторизатору Shibboleth. В этом процессе этот модуль может использоваться для копирования атрибутов пользователя из успешного ответа авторизатора в оригинальный запрос Nginx в виде заголовков или параметров окружения для использования любым бэкенд-приложением. Если авторизация не успешна, статус и заголовки ответа авторизатора возвращаются клиенту, отказывая в доступе или перенаправляя браузер пользователя соответственно (например, на страницу WAYF, если это так настроено).

Этот модуль работает на фазе доступа и поэтому может сочетаться с другими модулями доступа (такими как access, auth_basic) через директиву satisfy. Этот модуль также может быть скомпилирован вместе с ngx_http_auth_request_module, хотя использование обоих этих модулей в одном блоке location не тестировалось и не рекомендуется.

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

Для получения дополнительной информации о том, почему это отдельный модуль, см. https://forum.nginx.org/read.php?2,238523,238523#msg-238523

Директивы

Следующие директивы добавляются в ваши конфигурационные файлы Nginx. Упомянутые ниже контексты показывают, где их можно добавлять.

shib_request \<uri>|off | Контекст: http, server, location
По умолчанию: off

Включает модуль запроса аутентификации Shibboleth и задает URI, который будет запрашиваться для авторизации. Настроенный URI должен ссылаться на блок местоположения Nginx, который указывает на ваш FastCGI авторизатор Shibboleth.

HTTP статус и заголовки ответа, полученного в результате подзапроса к настроенному URI, будут возвращены пользователю в соответствии с спецификацией FastCGI авторизатора. Одно (потенциально значительное) предупреждение: из-за того, как Nginx в настоящее время работает в отношении подзапросов (что эффективно требует авторизатор), тело запроса не будет передаваться авторизатору, и аналогично тело ответа от авторизатора не будет возвращено клиенту.

Настроенные URI не ограничены использованием FastCGI бэкенда для генерации ответа, однако. Это может быть полезно во время тестирования или в других случаях, поскольку вы можете использовать встроенные директивы Nginx return и rewrite, чтобы создать подходящий ответ. Кроме того, этот модуль может использоваться с любой FastCGI авторизацией, хотя его работа может быть затронута вышеупомянутым предупреждением.

[!WARNING] Директива shib_request больше не требует флага shib_authorizer. Его необходимо удалить, чтобы Nginx смог запуститься. Другие изменения не требуются.

shib_request_set \<variable> \<value>
Контекст: http, server, location
По умолчанию: none

Устанавливает variable на указанное value после завершения запроса аутентификации. Значение может содержать переменные из ответа запроса аутентификации. Например, $upstream_http_*, $upstream_status и любые другие переменные, упомянутые в nginx_http_upstream_module документации.

Эта директива может быть использована для введения атрибутов Shibboleth в окружение бэкенд-приложения, таких как \$_SERVER для FastCGI PHP приложения и является рекомендуемым методом. Смотрите документы конфигурации для примера.

shib_request_use_headers on|off | Контекст: http, server, location
По умолчанию: off

[!NOTE] Добавлено в v2.0.0.

Копирует атрибуты из ответа авторизатора Shibboleth в основной запрос как заголовки, делая их доступными для вышестоящих серверов и приложений. Используйте этот параметр только если ваш вышестоящий / приложение не поддерживает серверные параметры через shib_request_set.

С этим параметром включенным, заголовки ответа авторизатора, начинающиеся с Variable-\*, извлекаются, удаляя подстроку Variable- из имени заголовка, и копируются в основной запрос прежде, чем он будет отправлен в бэкенд. Например, заголовок ответа авторизатора такой как Variable-Commonname: John Smith приведёт к добавлению Commonname: John Smith в основной запрос, и соответственно отправится в бэкенд.

Осторожно с подделкой - вы должны убедиться, что ваше бэкенд-приложение защищено от инъекции заголовков. Обратитесь к конфигурации для примера о том, как этого достичь.

Конфигурация

Для получения полных сведений о конфигурировании окружения Nginx/Shibboleth смотрите документацию по адресу https://github.com/nginx-shib/nginx-http-shibboleth/blob/master/CONFIG.rst.

Пример блока server состоит из следующего:

#FastCGI авторизатор для модуля Auth Request
location = /shibauthorizer {
    internal;
    include fastcgi_params;
    fastcgi_pass unix:/opt/shibboleth/shibauthorizer.sock;
}

#FastCGI респондер
location /Shibboleth.sso {
    include fastcgi_params;
    fastcgi_pass unix:/opt/shibboleth/shibresponder.sock;
}

## Используя директиву ``shib_request_set``, мы можем вводить атрибуты как
## переменные окружения для бэкенд-приложения. В этом примере мы
## устанавливаем ``fastcgi_param``, но это может быть любой тип бэкенда Nginx,
## который поддерживает параметры (с использованием соответствующего *_param опции)
#
## Директива ``shib_fastcgi_params`` является опциональным набором параметров по умолчанию,
## доступным в директории ``includes/`` в этом репозитории.
#
## Выбирайте этот тип конфигурации, если ваше бэкенд-приложение
## не поддерживает серверные параметры или требует заголовки.
location /secure-environment-vars {
    shib_request /shibauthorizer;
    include shib_fastcgi_params;
    shib_request_set $shib_commonname $upstream_http_variable_commonname;
    shib_request_set $shib_email $upstream_http_variable_email;
    fastcgi_param COMMONNAME $shib_commonname;
    fastcgi_param EMAIL $shib_email;
    fastcgi_pass unix:/path/to/backend.socket;
}

## Безопасное местоположение. Все входящие запросы запрашивают FastCGI авторизатор Shibboleth.
## Осторожно с проблемами производительности и подделкой!
#
## Выбирайте этот тип конфигурации для приложений ``proxy_pass``
## или бэкендов, которые не поддерживают серверные параметры.
location /secure {
    shib_request /shibauthorizer;
    shib_request_use_headers on;

    # Атрибуты от Shibboleth вводятся как заголовки FastCGI
    # авторизатором, поэтому мы должны предотвратить подделку. Директива
    # ``shib_clear_headers`` является набором директив заголовка по умолчанию,
    # доступным в директории `includes/` в этом репозитории.
    include shib_clear_headers;

    # Добавьте *все* атрибуты, которые использует ваше приложение, включая все
    #варианты.
    more_clear_input_headers 'displayName' 'mail' 'persistent-id';

    # Это бэкенд-приложение будет получать переменные Shibboleth как заголовки запроса
    # (от FastCGI авторизатора Shibboleth)
    proxy_pass http://localhost:8080;
}

Обратите внимание, что мы используем headers-more-nginx-module для очистки потенциально опасных входящих заголовков и предотвращения потенциальной подделки. Последний пример с переменными окружения не подвержен подделке заголовков, при условии, что бэкенд читает данные только из переменных окружения.

Доступна стандартная конфигурация для очистки основных заголовков от авторизатора Shibboleth, но вы должны убедиться, что пишете свои собственные директивы очистки для всех атрибутов, которые использует ваше приложение. Имейте в виду, что некоторые приложения попытаются прочитать атрибут Shibboleth из окружения, а затем перейдут к заголовкам, поэтому просмотрите код вашего приложения, даже если вы не используете shib_request_use_headers.

С помощью shib_request_set доступен файл стандартных параметров, который вы можете использовать как include в nginx, чтобы убедиться, что все основные переменные Shibboleth передаются от FastCGI авторизатора к приложению. В него включено множество стандартных атрибутов, поэтому уберите ненужные вашего приложения и добавьте атрибуты Федерации или IDP, которые вам нужны. Этот файл стандартных параметров можно повторно использовать для вышестоящих, которые не являются FastCGI, просто изменив директивы fastcgi_param на uwsgi_param, scgi_param и так далее.

Подводные камни

  • Подзапросы, такие как запрос аутентификации Shibboleth, не обрабатываются через фильтры заголовков. Это означает, что встроенные директивы, такие как add_header, не будут работать, если настроены как часть блока /shibauthorizer. Если вам нужно манипулировать заголовками подзапроса, используйте more_set_headers из модуля headers-more.

См. https://forum.nginx.org/read.php?29,257271,257272#msg-257272.

Поведение

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

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

  • Если подзапрос авторизатора возвращает статус 200, доступ разрешается.

Если shib_request_use_headers включен, заголовки ответа начинающиеся с Variable-\* извлекаются, удаляя подстроку Variable- из имени заголовка и копируются в основной запрос. Другие заголовки ответа авторизатора, не имеющие префикса Variable- и тело ответа игнорируются. Спецификация FastCGI требует, чтобы пары имя-значение Variable-* были включены в окружение FastCGI, но мы делаем их заголовками, чтобы они могли использоваться с любым бэкендом (таким как proxy_pass) и не ограничиваться только FastCGI приложениями. Передавая данные Variable-* в виде заголовков, мы в конечном итоге следуем поведению ShibUseHeaders On в mod_shib для Apache, который передает эти атрибуты пользователя в виде заголовков.

Чтобы передавать атрибуты в виде переменных окружения (эквивалент ShibUseEnvironment On в mod_shib), атрибуты должны быть вручную извлечены с помощью директив shib_request_set для каждого атрибута. Это не может (в данный момент) быть сделано массово для всех атрибутов, поскольку каждый бэкенд может принимать параметры по-разному (fastcgi_param, uwsgi_param и т.д.). Pull requests приветствуются для автоматизации этого поведения.

  • Если подзапрос авторизатора возвращает любой другой статус (включая перенаправления или ошибки), статус и заголовки ответа авторизатора возвращаются клиенту.

Это означает, что в случае 401 Unauthorized или 403 Forbidden доступ будет откажен, и заголовки (такие как WWW-Authenticate) от авторизатора будут переданы клиенту. Все остальные ответы авторизатора (такие как перенаправления 3xx) также передаются клиенту, включая статус и заголовки, что позволяет перенаправлениям, таким как на страницы WAYF и на респондер Shibboleth (Shibboleth.sso), работать правильно.

Спецификация FastCGI требует, чтобы тело ответа возвращалось клиенту, но поскольку Nginx в настоящее время не поддерживает буферизацию ответов подзапросов (NGX_HTTP_SUBREQUEST_IN_MEMORY), тело ответа авторизатора фактически игнорируется. Решением этой проблемы может быть наличие у Nginx своей собственный страницы с ошибкой, например:

location /secure {
   shib_request /shibauthorizer;
   error_page 403 /shibboleth-forbidden.html;
   ...
}

Это будет обслуживать указанную страницу с ошибкой, если авторизатор Shibboleth отказывает пользователю в доступе к этому местоположению. Без указанной error_page Nginx будет обслуживать свои общие страницы ошибок.

Обратите внимание, что это не относится к респондеру Shibboleth (обычно размещенному на Shibboleth.sso), поскольку это FastCGI респондер, и Nginx полностью совместим с этим, так как подзапросы не используются.

Для получения дополнительных сведений см. https://forum.nginx.org/read.php?2,238444,238453.

Хотя этот модуль ориентирован специфически на FastCGI авторизатор Shibboleth, он, вероятно, будет работать с другими авторизаторами, принимая во внимание вышеупомянутые отклонения от спецификации.

Тесты

Тесты автоматически выполняются на GitHub Actions (с использованием этой конфигурации) всякий раз, когда в репозиторий вносятся новые коммиты или когда открываются новые pull-запросы. Если что-то сломалось, вам будет отправлено уведомление, и результаты будут представлены на GitHub.

Тесты написаны с использованием комбинации простого Bash-скрипта для компиляции нашего модуля с различными версиями и конфигурациями Nginx и тестовой структуры Test::Nginx на Perl для интеграционного тестирования. Обратитесь по предыдущей ссылке для получения информации о том, как расширить тесты, а также ознакомьтесь с основной документацией Test::Base по таким аспектам, как blocks() функция.

Интеграционные тесты запускаются автоматически CI, но также могут быть запущены вручную (требуется установка Perl и CPAN):

cd nginx-http-shibboleth
cpanm --notest --local-lib=$HOME/perl5 Test::Nginx
## nginx должен быть в PATH и скомпилирован с отладочными символами
PERL5LIB=$HOME/perl5/lib/perl5 prove

Помощь и поддержка

Запросы на поддержку конфигурации Shibboleth и настройки Nginx или веб-сервера должны направляться на список рассылки пользователей сообщества Shibboleth. Смотрите https://www.shibboleth.net/community/lists/ для получения деталей.

Отладка

Из-за сложной природы стека nginx/FastCGI/Shibboleth отладка конфигурационных проблем может быть сложной. Вот несколько ключевых моментов:

  1. Убедитесь, что nginx-http-shibboleth успешно скомпилирован и установлен в Nginx. Вы можете проверить это, выполнив команду nginx -V и осмотрев вывод на наличие --add-module=[path]/nginx-http-shibboleth или --add-dynamic-module=[path]/nginx-http-shibboleth.

  2. Если вы используете динамические модули для nginx, убедитесь, что вы использовали директиву load_module для загрузки этого модуля. Использование shib_request и других директив будет неудачным, если вы забыли загрузить модуль.

  3. Если вы используете версию nginx, которая отличается от тех, с которыми мы тестируем или если вы используете другие сторонние модули, вам следует запустить тестовый набор выше, чтобы подтвердить совместимость. Если любые тесты провалятся, проверьте вашу конфигурацию или подумайте о обновлении версии nginx.

  4. Конфигурация Shibboleth: проверьте ваш shibboleth2.xml и связанную конфигурацию, чтобы убедиться, что ваши хосты, пути и атрибуты правильно предоставляются. Пример конфигурации может помочь вам выявить ключевые "подводные камни" при конфигурировании shibboleth2.xml для работы с FastCGI авторизатором.

  5. Уровень приложения: в вашем коде всегда начинайте с самого простого возможного вывода для отладки (например, вывод окружения запроса) и постепенно усложняйте. Если вы хотите создать базовое, автономное приложение, ознакомьтесь с Bottle конфигурацией на вики.

  6. Отладка внутренних модулей: если вы внимательно проверили все вышеперечисленное, вы также можете отладить поведение этого модуля. Вам нужно будет скомпилировать nginx с поддержкой отладки (через ./auto/configure --with-debug ...) и при запуске nginx будет легче, если вам удастся запустить его в реальном времени с включенной отладочной записью. Добавьте следующее в ваш nginx.conf:

    daemon off;
error_log stderr debug;

    и запустите nginx. При запуске nginx вы должны увидеть строки, содержащие [debug] и, если вы делаете запросы, консольная запись будет продолжаться. Если этого не происходит, проверьте вашу конфигурацию nginx и процесс компиляции.

    Когда вы в конечном итоге делаете запрос, который попадает (или должен вызвать) блок shib_request, вы увидите в выводе такие строки:

    [debug] 1234#0: shib request handler
[debug] 1234#0: shib request set variables
[debug] 1234#0: shib request authorizer handler
[debug] 1234#0: shib request authorizer allows access
[debug] 1234#0: shib request authorizer copied header: "AUTH_TYPE: shibboleth"
[debug] 1234#0: shib request authorizer copied header: "REMOTE_USER: john.smith@example.com"
...

    Если вы не видите такие строки, содержащие shib request ..., или если вы видите некоторые из строк выше, но не там, где заголовки/переменные копируются, тогда проверьте вашу конфигурацию nginx. Если вы по-прежнему не можете найти проблему, вы можете добавить свои собственные строки отладки в исходный код (следуя примерам этого модуля), чтобы в конечном итоге определить, что идет не так и когда. Если вы делаете это, не забудьте перекомпилировать nginx и/или nginx-http-shibboleth, когда вы вносите изменения.

Если вы считаете, что нашли ошибку в основном коде модуля, пожалуйста, создайте проблему.

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