Авторизация Pubcookie для Nginx

1. Введение

1.1. Описание

ngx_http_pubcookie_module – это модуль для сервера Nginx, который реализует авторизацию пользователей при помощи шифрованных cookie. Pubcookie не входит в стандартную поставку Nginx. Данный модуль – это порт Apache-модуля, описание и пример настроек которого можно найти здесь.

Pubcookie обеспечивает следующие основные функции:

• аутентификация пользователя при помощи отдельного сервера авторизации Pubcookie
• управление сессией аутентификации на уровне приложения
• таймаут неактивности и абсолютный таймаут на уровне приложения
• прекращение сеанса на уровне приложения
• протоколирование

Конфигурационные директивы позволяют настроить данные функции на уровне сервера целиком или на уровне приложения (location).

 

1.2. Схема работы

При заходе на защищенный ресурс нас автоматически редиректят на специальный выделенный логин-сервер, на котором мы авторизуемся и автоматически возвращаемся назад. При этом защищаемое приложение может запросить имя авторизованного пользователя из nginx-переменной $pubcookie_user (а если дополнительно настроить модуль, то и из стандартной nginx-переменной $remote_user).

В процессе аутентификации задействованы следующие компоненты:

1. Клиентский браузер;
2. Сервер приложений, на котором развернуто приложение, требующее аутентификации, в нашем случае это Nginx с модулем Pubсookie и, собственно, защищаемым приложением;
3. Логин-сервер, в нашем случае это опять же Nginx со стандартным приложением аутентификации и нашими настройками этого приложения;
4. Собственно, сервис аутентификации.

Аутентификация производится следующим образом:

1. Пользовательский браузер запрашивает определенный ресурс с сервера приложений, сконфигурированного для использования Pubcookie.
2. Модуль Pubcookie, установленный на сервере приложений, перехватывает запрос и проверяет, что он не связан с валидной текущей сессией и не содержит информацию от логин-сервера (т.н. granting cookie) для создания новой сессии.
   В случае успешной проверки модуль генерирует отклик, содержащий редирект и две куки: presession cookie для приложения и granting request cookie для логин-сервера Обе куки содержат, помимо прочей информации, случайное число, сгенерированное модулем. Все куки передаются в зашифрованном виде.
3. Клиентский броузер выполняет редирект (granting request) к логин-серверу с передачей ему granting request cookie. Данные запроса позволяют серверу доступа определить сервер приложений, для которого запрашивается аутентификация, URL оригинального запроса, тип авторизации и т.д.
4. Логин-сервер декодирует granting request cookie и интерпретирует содержимое. Сервер генерирует форму входа и отсылает ее клиенту.
5. Пользователь вводит свои логин и пароль в форму и отсылает ее на логин-сервер;
6. Логин-сервер получает логин и пароль и отсылает их используемому сервису аутентификации для проверки.
7. Логин-сервер получает результат проверки от сервиса аутентификации.
8. Если проверка прошла успешно, логин-сервер формирует отклик, содержащий редирект и две новых куки. Первая, granting cookie, предназначена для сервера приложений и содержит проверенное имя пользователя и дополнительную информацию, включая случайное число, сгенерированное в пункте 2. Granting cookie подписана приватным ключем сервера доступа и зашифрована симметричным ключем, используемым на сервере приложений и сервере доступа. Вторая, login cookie, предназначена для логин-сервера и используется в случае последующих заходов пользователя на него.
9. Пользовательский браузер повторно запрашивает защищенный ресурс с сервера приложений. Запрос содержит granting cookie и presession cookie.
10. Модуль pubcookie на сервере приложений перехватывает запрос, расшифровывает granting cookie, проверяет подпись и сравнивает случайное число в granting cookie с аналогичным числом в presession cookie. Если все сходится, то имя пользователя передается приложению и выполняется обработка запроса приложением. При этом также генерируется session cookie для последующих обращений к защищенным ресурсам. Отклик, сгенерированный приложением, отсылается пользователю.

В случае, если на шаге 4 granting request содержит также валидную login cookie (установленную на шаге 8), шаги 5, 6 и 7 пропускаются и логин-сервер переходит сразу к шагу 8, генерируя granting cookie использyя имя пользователя, полученное из login cookie. Таким образом, мы получаем вариант технологии Single Sign On для набора веб-приложений: не нужно отдельной авторизации в каждом веб-приложении, достаточно указать свои логин и пароль один раз.

2. Разработка

2.1. Новости

Версия 0.5 — 4 Ноя 2011

• Исправлена ошибка "No granting cookie", возникающая при использовании Google Chrome 12+ (issue 207)
• Модуль теперь собирается с последней версией Nginx 1.0.9

Версия 0.4 — 13 Июн 2011

• Добавлена поддержка переменной pubcookie_user и директивы pubcookie_set_remote_user (issue 205)
• Исправлен крэш модуля при использовании директивы "end_session on" (issue 204)
• Удалена директива "granting_key_file" (issue 203)
• Модуль теперь собирается с последней версией Nginx 1.0.4 (issue 206)

Версия 0.3 — 22 Мар 2011

Теперь базируемся на исходниках Pubcookie 3.3.5, а также исправлены ошибки:

• Метод POST не работал в Google Chrome (issue 194)
• Вложенные locations с директивами pubcookie приводили к краху процессов Nginx (issue 197)
• Сборка во FreeBSD обрывалась из-за "readlink -f" (issue 193)
• Завершение сессии Logout не работало в Ubuntu (issue 195)
• Сборка во FreeBSD обрывалась из-за неопределенной struct utsname (issue 201)
• Директива pubcookie_post должна быть разрешена только внутри location (issue 196)

Версия 0.2 — 16 Янв 2011.

• Исправлены HTTP-статусы: в некоторых случаях модуль возвращал 400 вместо 200.

Версия 0.1 — 1 Ноя 2010.

• Первая работоспособная версия.

2.2. Статус

Модуль находится в активной разработке. Upgrade for another pubcookie release is being prepared.

Модуль тестировался на реальном сервере на базе CentOS 5 с установленным Nginx 0.8.54 в течение нескольких месяцев (в июне 2011 произведено обновление до Nginx 1.0.4).

Исходный код модуля можно просмотреть здесь: https://svn.vitki.net/viewvc/repos/pubcookie/trunk/.

2.3. Известные проблемы

Текущий список проблем можно найти на трекере проекта.

2.4. Обратная связь

Сведения об ошибках, запросы новых фич и комментарии посылайте на почту vitkinet @ gmail . com

3. Установка

Детальные инструкции по установке (на английском) можно найти на сервере проекта pubcookie, а на данной странице приводится лишь краткий пример.

Бинарный RPM сервера Nginx с включенным модулем Pubcookie для CentOS 5 x86 можно найти в YUM-репозитории проекта. Для архитектур, отличных от x86, прочих версий CentOS, RedHat Linux или Fedora можно пересобрать RPM с исходным кодом Nginx. Последний файл спецификации nginx.spec доступен из svn-репозитория.

Бинарный RPM с приложеним авторизации Pubcookie, сервером ключей и шаблонами для CentOS 5 x86 также можно скачать из YUM-репозитория, или можно пересобрать RPM с исходным кодом Pubcookie (в subverion имеется файл спецификации pubcookie.spec).

Наиболее быстро подключить YUM-репозиторий vitki.net и установить последнии версии Pubcookie и Nginx в CentOS 5 x86 можно так:

  rpm -ivh http://rpm.vitki.net/pub/centos/5/noarch/vitki-net-release-5-3.vitki01.el5.noarch.rpm
yum update
yum install nginx pubcookie  

Бинарные версии приложения авторизации Pubcookie и сервера Nginx с модулем Pubcookie для Ubuntu 10.04 Lucid и Ubuntu 10.10 Maverick можно получить из моего ppa:vitkinet/ceobuntu (находится по адресу https://launchpad.net/~vitkinet/+archive/ceobuntu):

add-apt-repository ppa:vitkinet/ceobuntu
apt-get update
apt-get install nginx-plus pubcookie

Дебиан пакеты с исходным кодом также находятся в PPA. При необходимости, их можно пересобрать.

3.1. Компиляция

3.1.1. Сборка Nginx с модулем Pubcookie

Если требуется собственная сборка Nginx из исходников, забираем последнюю версию модуля из репозитория subversion:

svn checkout https://svn.vitki.net/svn/repos/pubcookie/trunk/ pubcookie

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

./configure …YourNginxOptions… --add-module=path/to/unpacked/archive/src/nginx
make
make install

Внимание: корневой каталог распакованного дистрибутива содержит Apache-версию модуля. В --add-module надо указать путь не к ней, а к поддиректории src/nginx.

На CentOS я использую следующий комплект конфигурационных флагов (download build script):

./configure \
  --user=nginx --group=nginx --prefix=/usr/share/nginx \
  --sbin-path=/usr/sbin/nginx --conf-path=/etc/nginx/nginx.conf \
  --error-log-path=/var/log/nginx/error.log --http-log-path=/var/log/nginx/access.log \
  --http-client-body-temp-path=/var/lib/nginx/tmp/client_body \
  --http-proxy-temp-path=/var/lib/nginx/tmp/proxy \
  --http-fastcgi-temp-path=/var/lib/nginx/tmp/fastcgi \
  --pid-path=/var/run/nginx.pid --lock-path=/var/lock/subsys/nginx \
  --with-http_ssl_module --with-http_realip_module --with-http_addition_module \
  --with-http_sub_module --with-http_dav_module --with-http_flv_module \
  --with-http_gzip_static_module --with-http_stub_status_module \
  --with-mail --with-mail_ssl_module \
  --with-cc-opt="-O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 \
                 -fexceptions -fstack-protector --param=ssp-buffer-size=4 \
                 -m32 -march=i386 -mtune=generic -fasynchronous-unwind-tables" \
  --add-module=/root/pubcookie/svn/trunk/src/nginx

С ними Nginx поначалу не собрался, поскольку по умолчанию его обертка над gcc использует довольно жесткий флаг "-Werror", останавливающий сборку при любом warning'е. Чтобы избавиться от него, открываем файлик auto/cc/gcc и комментируем Werror-строку (патч):

CFLAGS="$CFLAGS -Werror"

3.1.2. Сборка Pubcookie

Из того же архива собирается CGI-скрипт для сервера авторизации:

cd /path/to/pubcookie
./configure --prefix=/usr/pubcookie --enable-login --enable-apache \
            --disable-default-des --disable-krb5 --disable-shadow \
            --disable-uwsecurid --disable-unsafe-relay --disable-ldap 
make
make install

В CentOS мне пришлось перед сборкой создать символическую ссылку на скрипты сборки Apache, а в противном случае сборка обрывалась:

ln -s /usr/lib/httpd/build /etc/httpd/build

По умолчанию скрипт, сервер ключей и шаблоны страницы авторизации устанавливаются в каталог /usr/local/pubcookie, но в примере выше мы используем путь /usr/pubcookie.

3.2. Генерация ключей и сертификатов

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

Первая пара, session key pair, используется приложением pubcookie для шифрования запросов, а также сервером ключей (о нем ниже):

openssl req -new -x509 -out session.crt -newkey rsa:1024 -nodes -keyout session.key

Вторая пара, granting key pair, используется приложением CGI на сервере для подписи и проверки granting cookies:

openssl req -new -x509 -out granting.crt -newkey rsa:1024 -nodes -keyout granting.key

Пример чисто демонстрационный, мы используем self-signed сертификаты, в реальности же все может быть сложнее: должна существовать certification authority (CA), ключем которой подписаны все наши пары. Соответственно в нашем примере игрушечный CA bundle для самоподписанных сертификатов это просто сам session-сертификат:

cp session.crt ca-bundle.crt

Кроме того, nginx-сервер приложений и nginx-сервер авторизации, гед работает CGI-приложения pubcookie, используеют HTTPS, и нам необходимы пары ключей для них. Эти ключи уже независимы от pubcookie. В нашем демонстрационном примере для всех серверов мы будем использовать одну и ту же пару ключей:

 openssl req -new -x509 -out server.crt -newkey rsa:1024 -nodes -keyout server.key  

В результате получаем файлы: session.crt, session.key, granting.crt, granting.key, ca-bundle.crt, server.crt, server.key.

3.3. Настройка сервера авторизации

3.3.1. Настройка сервера ключей

Пусть сервер авторизации называется access.company.com .

На сервере доступа выполняются сервер ключей и приложение аутентификации под управлением веб-сервера.

Сервер ключей распространяет симметричные ключи, использующиеся для шифрования содержимого кук. Он запускается под xinetd, соответственно, прописываем его в /etc/xined.d/pubcookie_keyserver:

service keyserver
{
  type                 = UNLISTED
  protocol             = tcp
  port                 = 2222
  disable              = no
  socket_type          = stream
  wait                 = no
  user                 = root
  group                = tty
  server               = /usr/pubcookie/keyserver
}

После перезапуска xinetd сервер ключей становится доступен на порту 2222. Не забудьте открыть этот порт в фаерволле.

3.3.2. Настройка CGI-приложения авторизации

Приложение аутентификации — это обычное CGI-приложение, которое должно быть доступно по https. Соответственно, для него необходимо настроить virtual host. В качестве отправной точки можно использовать следующий отрывок из файла конфигурации:

server {
    server_name access.company.com;
    listen 443 ssl;
    ssl_certificate /usr/pubcookie/keys/server.crt;
    ssl_certificate_key /usr/pubcookie/keys/server.key;  
    if ( $ssl_protocol = "" ) { rewrite . https://$host$uri permanent; }

    location /login {
        alias /usr/pubcookie/login;
        index index.cgi;
    }

    location = /login/index.cgi {
        root /usr/pubcookie/login;
        fastcgi_pass unix:/var/run/fcgiwrap.sock;
        fastcgi_param SCRIPT_FILENAME /usr/pubcookie/login/index.cgi;
        fastcgi_param SCRIPT_NAME /login/index.cgi;
        fastcgi_param HTTPS on;
        fastcgi_param HTTP_COOKIE $http_cookie;
        include /etc/nginx/fastcgi.inc;
    }
}

Теперь надо сконфигурировать сам pubcookie. Правим файл /usr/pubcookie/config:

# Уровень детализации логов
logging_level: 1

# Используемый сервис аутентификации. 
# В нашем примере мы используем пользовательский скрипт auth.php, 
# который обращается к базе данных.
basic_verifier: verify_fork
verify_exe: /usr/pubcookie/auth.php

# Пара ключей SSL
ssl_key_file: /usr/pubcookie/keys/session.key
ssl_cert_file: /usr/pubcookie/keys/session.crt

# Пара granting ключей 
granting_key_file: /usr/pubcookie/keys/granting.key
granting_cert_file: /usr/pubcookie/keys/granting.crt 

# Логин-сервер (CGI)
login_uri: https://access.company.com/login/index.cgi
login_host: access.company.com
enterprise_domain: .company.com
logout_prog: /logout/index.cgi

# Сервер ключей
keymgt_uri: localhost:2222
ssl_ca_file: /usr/pubcookie/keys/ca-bundle.crt

# Срок жизни сессии
default_l_expire: 8h

# Параметры шаблонов логин-сервера, в частности, сообщение о закрытии сессии.
app_logout_string-app1.company.com-app1: Разлогинились из app1

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

В нашем случае это php-скрипт, который может, например, обратиться в базе данных или текстовому файлу, вместе с тем, поддерживаются и другие режимы, например, работа с LDAP и Kerberos. Пример такого скрипта, auth.php, можно среди исходников модуля.

Теперь генерируем ключ, позволяющий логин-серверу соединиться с сервером ключей:

sudo keyclient -P access.company.com

Сгенерированный ключ будет записан в файл keys/access.company.com. Эту операцию необходимо выполнить для каждого хоста и сервера приложений, использующего Pubcookie:

 sudo keyclient -P app1.company.com 

3.3.3. Настройка пользовательского интерфейса сервера доступа

После выполнения всех этих манипуляций по адресу https://access.company.com/login/index.cgi мы должны увидеть форму логина.

Внешний вид формы логина и служебных страниц логин-сервера можно настроить с помощью шаблонов, которые лежат в каталоге login_templates. Для использования русского языка в формах желательно использовать кодировку UTF-8. В моей версии Pubcookie исходный файл index.cgi.c уже пропатчен соответвующим образом.

3.3.4. Настройка logout

Закрытие сессии может быть выполнено как в отдельном приложении, так и на логин-сервере. Самый простой способ сделать это — создать location с именем logout, содержащим две директивы:

location /logout {
  pubcookie_end_session clearLogin;
  pubcookie_app_id my_app_id;
}

Идентификатор my_app_id в этом location должен соответствовать идентификатору в location приложения.

3.4. Настройка сервера приложений

На сервере приложения настраиваем конфигурационный файл pubcookie так же, как и на сервере доступа (CGI-скрипт тут уже не нужен). Ключи и сертификаты, созданные ранее, должны быть установлены в /usr/pubcookie/keys: session.crt, session.key, granting.crt, granting.key, ca-bundle.crt, а также файлы keys/app1.company.com и keys/access.company.com для доступа к серверу ключей.

Помимо этого, необходимо собрать Nginx с модулем Pubcookie и добавить в настройки Nginx конфигурацию Pubcookie. В качестве отправной точки рассмотрим отрывок из файла конфигурации:

http {

  ...
  pubcookie_super_debug        off;
  pubcookie_granting_cert_file /usr/pubcookie/keys/granting.crt;
  pubcookie_session_key_file   /usr/pubcookie/keys/session.key;
  pubcookie_session_cert_file  /usr/pubcookie/keys/session.crt;
  pubcookie_key_dir            /usr/pubcookie/keys/;
  pubcookie_domain             .company.com;
  pubcookie_login              https://access.company.com/login/index.cgi;
  pubcookie_login_method       POST;
  pubcookie_encryption         AES;
  ...

  server {
    server_name app1.company.com;
    listen 443 ssl;
    ssl_certificate /usr/pubcookie/keys/server.crt;
    ssl_certificate_key /usr/pubcookie/keys/server.key;  

    ...

    location /secure_app1 {
      expires -1;
      pubcookie_app_id my_app_1;
      pubcookie_set_remote_user on;
    }

    location /logout_app1 {
      pubcookie_end_session clearLogin;
      pubcookie_app_id my_app_1;
    }

    location = /PubCookie.reply {
      pubcookie_post;
    }

  }

}

Та часть настроек, которая расположена до конфигурации сервера, является общей для всех серверов и приложений. Если сервер app1.company.com использует HTTPS для доступа, то в nginx должна быть сконфигурирована пара ключей server.crt, server.key.

В примере мы закрыли доступ только к каталогу /secure_app1, расположив директиву внутри location, однако мы могли бы закрыть доступ ко всему виртуальному серверу, для чего достаточно вынести директиву pubcookie_app_id на уровень server {...}. Кстати, в этом случае директиву pubcookie_app_id можно убрать из location /logout_app1, поскольку идентификатор приложения будет наследоваться с вышестоящего уровня сервера.

Директива expires в примере выше используется затем, чтобы после завершения пользователем сессии приложение app1 немедленно стало недоступно, и его страницы не остались в кеше браузера.

Теперь перезапускаем Nginx, и если все нормально, то при заходе на https://app1.company.com/secure_application нас должно перебросить на https://access.company.com/ (c автоматическим промежуточным перебросом через https://app1.company.com/Pubcookie.reply), где мы авторизуемся и автоматически возвращаемся обратно. Обратите внимание, что сервер приложений должен поддерживать соединения https, поскольку pubcookie-обработчик POST по умолчанию перенаправляет на порт 443.

4. Список конфигурационных директив

4.1. pubcookie_inactive_expire

Синтаксис: pubcookie_inactive_expire expire-time-in-seconds
Контекст: main, server, location

Длительность периода, в течение которого пользователь не обращается к приложению, после которого сессия автоматически завершается. Обращение к приложению после завершения сессии приводит к повторному перенаправлению пользователя на сервер авторизации для получения нового granting cookie.

Значение параметра по умолчанию равно 30 минутам и определено как PBC_DEFAULT_INACT_EXPIRE в файле pbc_config.h. Минимальное значение равно 5 минутам.

Значение, равное -1, отключает проверку неактивности.

4.2. pubcookie_hard_expire

Синтаксис: pubcookie_hard_expire expire-time-in-seconds
Контекст: main, server, location

Максимальная длительность пользовательской сессии в приложении, независимо от наличия активности пользователя. Завершение сессии вследствие достижения максимального времени вызывает перенаправление на сервер авторизации и получение нового granting cookie.

Значение по умолчанию равно 8 часам и задается параметром PBC_DEFAULT_HARD_EXPIRE в файле pbc_config.h. Минимальное значение - 1 час, максимальное - 12 часов.

4.3. pubcookie_app_id

Синтаксис: pubcookie_app_id application-name
Контекст: main, server, location

Имя приложения. По умолчанию оно такое же, как путь к его каталогу.

4.4. pubcookie_dir_depth

Синтаксис: pubcookie_dir_depth depth
Контекст: main, server

Эта директива определяет, что идентификатор приложения appID определяется заданным числом вложенных директорий в пути к веб-приложению, что позволяет ограничить длину идентификатора appIDs по умолчанию заданным числом директорий.

Глубина вложенности - это количество каталогов, на которое будет обрезан идентификатор приложения appID, например:

/	0
/blah/	1
/blah/asdf/	2

Примечание: если параметр pubcookie_catenate_app_ids не разрешен, то вместо значения pubcookie_dir_depth будет использоваться pubcookie_app_id.

4.5. pubcookie_catenate_app_ids

Синтаксис: pubcookie_catenate_app_ids on | off
Контекст: main, server

Если эта директива разрешена, то идентификатор веб-приложения appID будет строиться путем соединения всех сконфигурированных значений (на уровне сервера и вложенных директорий). В противном случае будет использоваться самое последнее сконфигурированное значение.

Если pubcookie_catenate_app_ids разрешено, то значения pubcookie_dir_depth и pubcookie_app_id будут аккумулироваться.

4.6. pubcookie_app_srv_id

Синтаксис: pubcookie_app_srv_id AppServerID
Контекст: main, server

Эта директива позволяет явно задать значение AppSrvID (по умолчанию используется значение, основанное на имени сервера ServerName).

4.7. pubcookie_login

Синтаксис: pubcookie_login url-of-login-server
Контекст: main, server

Задает расположение CGI-скрипта авторизации pubcookie на сервере авторизации.

4.8. pubcookie_login_method

Синтаксис: pubcookie_login_method GET|POST
Контекст: main, server

Эта директива определяет, каким образом модуль и сервер авторизации будут обмениваться запросами и ответами авторизации.

По умолчанию используется классический метод GET с использованием cookie. При этом запрос и ответ используют HTML-перенаправления при помощи директивы "META refresh", а все cookie ограничиваются доменом, заданным в директиве pubcookie_domain.

Более новый метод POST по сути более близок к профилю Browser/POST стандарта SAML. Отправка запросов и ответов происходит в сообщениях HTTP POST и использует, но не требует Javascript. Для реализации этого метода на сервере необходим дополнительный location, задаваемый директивой pubcookie_post, который перехватывает начальный запрос авторизации, отправленный из веб-приложения.

Версии модуля 3.2.0 и ниже поддерживают только метод GET. Все последующие версии поддерживают оба метода.

4.9. pubcookie_post

Синтаксис: pubcookie_post_url post-reply-url
Контекст: location

Данная директива должна быть указана внутри location, которое будет использоваться как промежуточная точка редиректа в методе POST (метод определяется директивой pubcookie_login_method). Точка должна располагаться на том же виртуальном сервере, что и использующее авторизацию веб-приложение.

По умолчанию это должен быть "location = /PubCookie.reply { pubcookie_post; }".

В версии для Apache директива называлась PubCookiePostURL и в качестве параметра использовала путь к точке POST. В Nginx путь задается самим элементом location.

4.10. pubcookie_domain

Синтаксис: pubcookie_domain domain
Контекст: main, server

Задает DNS-домен, которым ограничены cookie в рамках классического метода GET. Домен должен быть, как минимум, второго уровня.

Примечание: при использовании метода POST все ограничения, связанные с использованием единого домена и с его уровнем полностью снимаются. См. директиву pubcookie_login_method.

4.11. pubcookie_granting_cert_file

Синтаксис: pubcookie_granting_cert_file filename
Контекст: main, server

Имя файла с сертификатом, используемым сервером авторизации для проверки подписи granting cookies.

По умолчанию используется имя /usr/pubcookie/pubcookie_granting.crt, заданное в параметром PBC_G_CERTFILE в файле pbc_config.h.

4.12. pubcookie_session_key_file

Синтаксис: pubcookie_session_key_file filename
Контекст: main, server

Имя файла с секретным ключем, используемым для подписи session cookies.

По умолчанию используется имя /usr/pubcookie/pubcookie_session.key, заданное параметром PBC_S_KEYFILE в файле pbc_config.h.

4.13. pubcookie_session_cert_file

Синтаксис: pubcookie_session_cert_file filename
Контекст: main, server

Имя файла с сертификатом, используемым для проверки подписи session cookies.

По умолчанию используется имя /usr/pubcookie/pubcookie_session.crt, заданное параметром PBC_S_CERTFILE в файле pbc_config.h.

4.14. pubcookie_crypt_key_file

Синтаксис: pubcookie_crypt_keyfile filename
Контекст: main, server

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

По умолчанию используется имя /usr/pubcookie/c_key, заданное параметром PBC_CRYPT_KEYFILE в файле pbc_config.h.

4.15. pubcookie_end_session

Синтаксис: pubcookie_end_session redirect | clearLogin | on | off
Контекст: location

Эта директива используется для завершения пользовательской сессии. Она должна быть размещена в дочернем location по отношению к location веб-приложения, либо в location с явно указанным идентификатором веб-приложения pubcookie_app_id. Например, для некоторого веб-приложения /webapp/ типичной точкой выхода может быть /webapp/logout/, в location которой и размещается данная директива.

Если задан один из аргументов on, redirect или clearLogin, то session cookie будет очищено. Новое обращение к ресурсу потребует захода на сервер авторизации и получения нового granting cookie. Примечание: очищается только session cookie в рамках заданного приложения, а все прочие приложения не будут затронуты.

Если задан аргумент redirect или clearLogin, то после очистки session cookie браузер будет перенаправлен на страницу результатов на сервере авторизации. Если задан аргумент clearLogin, то дополнительно будет очищен login cookie.

Значение аргумента off полностью деактивирует описанные выше функции.

4.16. pubcookie_encryption

Синтаксис: pubcookie_encryption AES | DES | AES+DOMAIN
Контекст: main, server

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

В версиях 3.3.0 и последущих по умолчанию используется шифрование AES (если модуль не был скомпилирован с опцией --enable-default-des). В более ранних версиях поддерживался только метод шифрования DES. Таким образом, для корректного взаимодействия с серверами авторизаций более ранних версий, чем 3.3.0, этот параметр следует установить в DES.

Значение AES+DOMAIN позволяет модулю использовать так называемые wildcard поддомены.

4.17. pubcookie_session_reauth

Синтаксис: pubcookie_session_reauth on | off | grace-time-in-seconds
Контекст: main, server, location

Если данное значение выставлено в on, директива pubcookie_session_cause_reauth будет приводить к повторным авторизациям пользователя. Пользователю придется повторно вводить пароль, чтобы восстановить сессию с приложением.

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

4.18. pubcookie_auth_type_names

Синтаксис:  —
Контекст: —

Аналогичная директива PubcookieAuthTypeNames применяется в Apache-версии модуля для привязки к типам авторизации. В nginx-версии директива не используется.

Примечание: для совместимости с Apache, Nginx-версия модуля экспортирует переменную $pubcookie_auth_type, но ее значение всегда равно WebISO при наличии авторизации и пустой строке, если авторизация не получена.

4.19. pubcookie_no_prompt

Синтаксис: pubcookie_no_prompt on | off
Контекст: main, server, location

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

Если у пользователя уже имеется валидный login cookie, ему будет предоставлен доступ к приложению и предоставлен session cookie. Если же валидного login cookie нет, пользователю без дополнительных запросов и сообщений будет предоставлен доступ к приложению и выдан session cookie с пустым идентификатором.

Переменная $pubcookie_user будет содержать непустой идентификатор, только если у пользователя уже имеется валидный login cookie. Если валидного login cookie нет (в случае неавторизованного запроса), эта переменная будет содержать пустую строку.

Примечание: пользователь, у которого еще нет авторизации, может решить, что страницы веб-приложения, где используется данная опция, ведут себя некорректно. Кроме того, поскольку в момент первого обращения такого пользователя к защищенному ресурсу будет создан session cookie с пустым идентификатором, сессия пользователя будет оставаться анонимной в течение своего времени жизни, даже если пользователь зарегистрируется впоследствии.

4.20. pubcookie_on_demand

Синтаксис: pubcookie_on_demand key directive1 directive2...
Контекст: main, server, location

Эта директива управляет так-называемым классом функций "по-требованию".

Функции (директивы) "по-требованию" по умолчанию отключены. Их может активировать только наличие cookie активации с именем OnDemandKey и значением, равным key. Тогда все связанные директивы активируются, а переменная окружения $pubcookie_on_demand_key получает значение активного ключа (key). Активирующее cookie должно содержаться в каждом запросе к защищаемому "по-требованию" ресурсу.

Только перечисленные ниже директивы могут быть использованы "по-требованию":

• pubcookie_inactive_expire
• pubcookie_hard_expire
• pubcookie_app_id
• pubcookieEndSession
• pubcookie_session_cause_reauth
• pubcookie_addl_request
• pubcookie_no_prompt

Активные директивы "по-требованию" имеют приоритет над аналогичными директивами, заданными обычным образом.

Примечание: cookie активации OnDemandKey и его значение представляют, по сути, простой текст. Веб-приложение должно проверять значение переменной окружения $pubcookie_demand_key, чтобы убедиться, что пользователь авторизован согласно особым правилам "по-требованию". В том числе, приложение должно учитывать случай, когда переменные $pubcookie_user и $pubcookie_demand_key содержать пустую строку или не имеют значения.

4.21. pubcookie_addl_request

Синтаксис: pubcookie_addl_request opt1=val1 [opt2=val2...]
Контекст: main, server, location

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

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

4.22. pubcookie_no_obscure_cookies

Синтаксис: pubcookie_no_obscure_cookies on | off
Контекст: main, server

Этот параметр управляет доступностью session cookie для прочих модулей сервера Nginx и выполняемых в сервере CGI-приложений. По умолчанию он установлен в значение on, и session cookies доступны всем модулям и приложениям. Если выставить значение off, то модуль pubcookie будет удалть session cookies из внутренних структур Nginx после первого обращения, так что прочие модули и приложения не смогут к ним обращаться. Такая настройка повышает общую секретность, но в отдельных случаях (например, при обращении к защищенному ресурсу из браузера Chrome) может приводить к сбоям авторизации.

4.23. pubcookie_no_clean_creds

Синтаксис: pubcookie_no_clean_creds on | off
Контекст: main, server

По умолчанию модуль pubcookie удаляет все данные авторизации по окончании процессов проверки. Если выставить значение on, данные авторизации (credentials) очищаться не будут. Это может быть необходимо, если приложение использует модуль pubcookie только для авторизации, а управление сессией производится самим приложением.

4.24. pubcookie_egd_device

Синтаксис: pubcookie_egd_device location
Контекст: main, server

Задает путь к сокету EGD (например, /dev/egd-pool) для получения энтропии.

4.25. pubcookie_no_blank

Синтаксис: pubcookie_no_blank
Контекст: main, server

Эта директива исключена из Pubcookie начиная с версии 3.2.1. Вместо нее следует использовать директиву pubcookie_no_obscure_cookies.

4.26. pubcookie_super_debug

Синтаксис: pubcookie_super_debug on | off
Контекст: main

Этот параметр по умолчанию отключен. Если Вы испытываете проблемы с настройками модуля, установите значение параметра в "on". После перезапуска модуль будет выводить подробную информацию в error-log nginx, обычно /var/log/nginx/error.log.

4.27. pubcookie_set_remote_user

Синтаксис: pubcookie_set_remote_user on | off
Контекст: main, server, location

По умолчанию этот параметр отключен, и имя авторизованного пользователя (или пустая строка, если авторизация отсутствует) будет регистрироваться только в переменной $pubcookie_user. Если выставить этот параметр в значение "on", то имя пользователя также будет регистрироваться в стандартной переменной $remote_user.