Pubcookie module for Nginx

1. Introduction

1.1. Description

ngx_http_pubcookie_module is a Nginx module, which authorizes users using encrypted cookies. Russian description is available here.

Pubcookie is a third party module and is not included in the Nginx core.

This module is a port of Pubcookie for Apache. You can find description and example settings of Apache module here.

The module provides the following functionality:

  • user authentication via a separate Pubcookie login server
  • per-application authentication session management
  • per-application inactivity and hard timeouts
  • per-application logout
  • logging

This functionality can be configured server-wide or on a per-application basis via the modules run-time configuration directives.

 

1.2. Overview of Operation

When a user whos haven't been authenticated hits a secured web page, pubcookie automatically redirects him or her to a dedicated login server, where the user enters login name and password. After verification the user is redirected back to the original page. The secured web application can fetch the authorized user name from the nginx variable $pubcookie_user (with a little configuration the standard nginx variable $remote_user can be queried too).

The authentication process involves the following components:

  1. A User-Agent (web browser);
  2. Сервер приложений, на котором развернуто приложение, требующее аутентификации, в нашем случае это Apache с модулем Pubсookie и, собственно, защищаемым приложением;
  3. Логин-сервер, в нашем случае это опять же Nginx со стандартным приложением аутентификации и нашими настройками этого приложения;
  4. The external authentication service;

The sign-on process (i.e. how a user is initially authenticated) proceeds as follows:

  1. A user makes a request to an application server for a resource (a URL) tied to an application that uses Pubcookie for authentication.

  2. The Pubcookie module intercepts the request and inspects it to determine that the request is not associated with a valid, existing authenticated session for the application and does not carry information from the login server (known as a "granting cookie", see steps 8 and 9) necessary to establish a new session.The Pubcookie module generates a response, including a "redirect" page and two cookies: a "pre-session" cookie scoped to the application, and a "granting request" cookie scoped to reach the login server. Both cookies contain, among other things, a random number generated by the Pubcookie module.

  3. The "redirect" page causes the user's browser to make a request to the Pubcookie login server, including the "granting request" cookie.This is the "granting request". It contains information about the application server, the original resource (URL), the desired type of authentication, etc.

  4. The Pubcookie login server decodes the "granting request" cookie and interprets the contents. In response, it generates a login form page and sends it to the browser, prompting the user to enter username and password.

  5. The user enters his or her username and password into the form and submits it, causing the browser to send the data to the login server.

  6. The Pubcookie login server takes the username and password and sends them to its backend authentication service for verification.

  7. The Pubcookie server receives the verification response.

  8. If verification is successful, the Pubcookie login server generates a response, including a "redirect" page and two new cookies. (If verification fails, another login form page is sent to the user's browser.) One cookie, known as the "granting cookie", contains the authenticated username and some other items, including the random number it received from the application server via the "granting request". The "granting coookie" is protected from tampering by being signed using the private key of the login server, and protected from disclosure by being encrypted using the symmetric key shared by the application server and the login server. It is scoped to reach the application server. The second cookie, known as the "login cookie", is scoped to the login server and will be used on any subsequent visits by the user to the login server.

  9. The "redirect" page causes the user's browser to re-request the original resource (URL) on the application server. This request contains the granting cookie set by the login server and the "pre-session" cookie set earlier by the application server.

  10. The Pubcookie module on the application server again intercepts the request, as in step 2. This time it finds the "granting cookie" which it decrypts using the shared symmetric key. It then verifies the signature using the login server's public key and matches the random number found in the "granting cookie" with the random number found in the "pre-session" cookie. If verification succeeds, the Pubcookie module supplies the authenticated username to the application along with the rest of the original request. It also generates a valid "session cookie" for subsequent requests by the user to the application. Having successfully authenticated the user, the application can finally send the original resource to the user. The Pubcookie module makes sure that the application's response is accompanied by the new "session cookie"

If, in step 4, the "granting request" is accompanied by a previously established, valid "login cookie" (as set in step 8), then steps 5, 6, and 7 are skipped, and the login server proceeds to step 8, issuing a "granting cookie" using the username as found in the "login cookie". This provides the "single sign-on" experience for the user, allowing him or her to request resources tied to other Pubcookie-authenticated resources without having to re-enter a password as long as the "login cooke" is still valid (e.g. for 8 hours after the intial sign-on).

2. Development

2.1. News

Release 0.5 — Nov 4 2011

  • Fix "No granting cookie" in /PubCookie.reply if Google Chrome 12+ is used (issue 207)
  • Build module with latest Nginx 1.0.9

Release 0.4 — Jun 13 2011

Upgraded to Pubcookie 3.3.5 and fixed bugs:

  • Post method fails with Google Chrome (issue 194)
  • Nested locations with pubcookie directives crash Nginx (issue 197)
  • FreeBSD build fails due to "readlink -f" (issue 193)
  • Logout does not work on Ubuntu (issue 195)
  • Build fails on FreeBSD due to undefined struct utsname (issue 201)
  • Directive pubcookie_post shall be disabled for main and server contexts (issue 196)
  • Directive pubcookie_add_request should be renamed to pubcookie_addl_request (issue 198)
  • Create ubuntu debs for pubcookie and nginx with pubcookie (issue 200)

Release 0.2 — Jan 16 2011

  • Fixed: Sometimes module returned HTTP status 400 instead of 200

Release 0.1 — Nov 1 2010

  • First working release

2.2. Status

The module is actively developed. It has been tested for several months on production server set up with Nginx 0.8.54 and CentOS 5.5.

You can browse the module source code here: https://svn.vitki.net/viewvc/repos/pubcookie/trunk/.

2.3. Known Issues

Up-to-date list of project issues can be found on the project issue tracker.

2.4. Authors

Send your bug reports, feature requests and comment by email: vitkinet @ gmail.com

3. Installation

This section just briefly covers the module setup and configuration. For detailed instructions please refer to pubcookie project documentation.

You can find a binary RPM of Nginx with build-in Pubcookie module for CentOS 5 x86 in the project YUM repository. For other architectures than x86, other CentOS versions, for RedHat Linux or Fedora you can rebuild the appropriate Nginx source RPM. The latest RPM specification file nginx.spec is available from the code repository.

Binary RPM with Pubcookie CGI application, key server and login page templates built for CentOS 5 x86 can be also downloaded from the YUM repository, or you can rebuild the Pubcookie source RPM (the subverion repository has an appropriate RPM specification pubcookie.spec).

A quick way to add the vitki.net YUM repository to your system and install latest binary RPMs of Pubcookie and Nginx on CentOS 5 x86 is:

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

Binary DEB packages with Pubcookie application and modified Nginx server with Pubcookie module for Ubuntu 10.04 Lucid and Ubuntu 10.10 Maverick can be obtained from my ppa:vitkinet/ceobuntu (available at https://launchpad.net/~vitkinet/+archive/ceobuntu) as follows:

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

The source packages are also available from the vitkinet/ceobuntu PPA and can be rebuilt if needed.

3.1. Building

3.1.1. Build Nginx with Pubcookie

If you need a custom Nginx build, get the latest module sources from the subversion repository:

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

Download stable Nginx sources from the official site and extract the tarball. Follow the official build instructions, adding the Pubcookie module option to the configuration command line:

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

Warning: the root directory of the Pubcookie source tree contains the Apache module. For Nginx builds the --add-module argument should point to the src/nginx subdirectory instead.

For CentOS builds I use the following configuration flags (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

At first try Nginx refused to build with such flags because its build system invokes the gcc compiler with the "-Werror" flag, which aborts compilation after every warning. As a fix, open the auto/cc/gcc script and comment out the Werror-line (патч):

CFLAGS="$CFLAGS -Werror"

3.1.2. Building Pubcookie Binaries

Build the Pubcookie CGI application from the same source tree:

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

On my CentOS I had to create a symbolic link to Apache build scripts, otherwise the build failed:

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

Originally the CGI, key server and web page templates were installed under /usr/local/pubcookie, but I prefer to use the path /usr/pubcookie.

3.2. Generation of Keys and Certificates

As pubcookie module and login server exchange encrypted messages, you have to create two pairs of SSL keys.

The session key pair is used by pubcookie module to encrypt authentication requests and by the key server (details below):

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

The granting key pair is used by the Pubcookie CGI application to sign, encrypt and verify granting cookies:

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

In this demo example we self-signed certificates, but in real life you should have a certification authority (CA) key bundle to sign all your certificates. But for demo purposes a CA bundle for self-signed certificates is simply the session certificate by itself:

cp session.crt ca-bundle.crt

Furthermore, as the application web server and login server should use HTTPS for security, we need SSL keys for them. These keys are not dependent on pubcookie at all. For the purposes of this demo we will use a single key pair for all servers:

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

Finally we have the following files: session.crt, session.key, granting.crt, granting.key, ca-bundle.crt, server.crt, server.key.

3.3. Logon Server Configuration

3.3.1. Key Server Configuration

Let the login server be named access.company.com.

The login server runs the key server daemon and the Pubcookie CGI application managed by Nginx.

The key server distributes symmetric keys used for encryption of cookies. It is run from the xinetd daemon, so we add its configuration to /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
}

After xinetd is restarted, the key server becomes available at port 2222. Do not forget to open this port in firewall.

3.3.2. Setup of Authentication Service CGI

The login application is simply a CGI script, which can be accessed via HTTPS. You have to setup a Nginx virtual host for it. As a starting point consider the following Nginx configuration snippet:

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;
    }
}

Now you have to configure the CGI application. Edit /usr/pubcookie/config:

# Logging verbosity level
logging_level: 1

# The authentication service used.
# In this example we use an executable script auth.php, which queries a user database.
basic_verifier: verify_fork
verify_exe: /usr/pubcookie/auth.php

# SSL session keypair
ssl_key_file: /usr/pubcookie/keys/session.key
ssl_cert_file: /usr/pubcookie/keys/session.crt

# Granting keypair
granting_key_file: /usr/pubcookie/keys/granting.key
granting_cert_file: /usr/pubcookie/keys/granting.crt 

# Login CGI configuration
login_uri: https://access.company.com/login/index.cgi
login_host: access.company.com
enterprise_domain: .company.com
logout_prog: /logout/index.cgi

# Keyserver configuration
keymgt_uri: localhost:2222
ssl_ca_file: /usr/pubcookie/keys/ca-bundle.crt

# Login cookie lifetime
default_l_expire: 8h

# Custom login page templates, in particular logout messages
app_logout_string-app1.company.com-app1: <b>Logged out from <u>Application1</u></b>

The authentication service can be based on LDAP or Kerberos. As in this example we use the verify_fork mode, the service is simply an external unix program, which reads user name and password from stdin and returns an exit code of 0 or 1 depending on whether authentication was successful or not. Generally the program can query a database or a text file. In our case it is the sample auth.php script available from the source distribution.

Now you have to generate the key to let the login server CGI connect with the key server:

sudo keyclient -P access.company.com

The resulting key is written in the /usr/pubcookie/keys/access.company.com file. This action should be repetaed for each application server host with Pubcookie installed:

sudo keyclient -P app1.company.com

3.3.3. Tuning of Authentication Interface

When keys are ready, restart Nginx on the login server. You should see the login form at https://access.company.com/login/index.cgi.

The login form and other login server pages can be adjusted with templates, found under the login_templates directory.

3.3.4. Configuration of Logout

Sessions can terminated both at the level of web application and on the login server. The most simple way to close a session is to create a Nginx location named logout with two directives:

location /logout {
  pubcookie_end_session clearLogin;
  pubcookie_app_id my_app_id;
}

The my_app_id identifier in this location should match the identifier from the web application location.

3.4. Application Setup

The pubcookie configuration file /usr/pubcookie/config on the application server host should be set up in the same way as on the login server (however the CGI script is not needed here). Certificates and keys created above should be installed under /usr/pubcookie/keys: session.crt, session.key, granting.crt, granting.key, ca-bundle.crt, as well as files keys/app1.company.com и keys/access.company.com required to access the key server.

Also you should build Nginx with Pubcookie module included and add Pubcookie directives to the Nginx configuration files. As a starting point let's consider the following configuration snippet:

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;
    }

  }

}

Settings located above the server block are common to all servers and applications. Since the server app1.company.com uses HTTPS access, the Nginx configuration should contain directives for the key pair server.crt, server.key.

In this example we secure only the access to the /secure_app1 directory by placing pubcookie directives inside the location. However we could secure access to the whole virtual server by moving the pubcookie_app_id directive onto the server {...} level. In such a case we could remove the  pubcookie_app_id directive from location /logout_app1, because application identifier would be inherited from the server level.

The expires directive in this example is needed to avoid caching secured pages in the user browser cache and forcibly make the application app1 inaccessible after session termination.

Now restart Nginx and try to access https://app1.company.com/secure_application. If everything is fine, you will be redirected to https://access.company.com/ (with automatic intermediate redirect to https://app1.company.com/Pubcookie.reply), and after completing the login form you will be redirected back to the original page. Please note that application server should accept https connections since pubcookie POST handler by default redirect to port 443.

4. List of Configuration Directives

4.1. pubcookie_inactive_expire

syntax: pubcookie_inactive_expire expire-time-in-seconds
context: main, server, location

The duration of inactivity allowed between a user and an application before the session expires. Expiration due to inactivity causes a loop thru the login server to obtain a new granting cookie.

The default value is 30 minutes which is defined as PBC_DEFAULT_INACT_EXPIRE in pbc_config.h. Minimium inactivity timeout is five minutes.

A value of -1 turns off the check for inactivity.

4.2. pubcookie_hard_expire

syntax: pubcookie_hard_expire expire-time-in-seconds
context: main, server, location

The maximum duration of an application session, regardless of user activity. Expiration due to reaching the hard timeout causes a loop thru the login server to obtain a new granting cookie.

The default value is eight hours which is defined as PBC_DEFAULT_HARD_EXPIRE in pbc_config.h. The minimium is one hour; the maximium is twelve hours.

4.3. pubcookie_app_id

syntax: pubcookie_app_id application-name
context: main, server, location

The name of the application. The default is the directory path.

4.4. pubcookie_dir_depth

syntax: pubcookie_dir_depth depth
context: main, server

This directive causes appIDs to be defined by the depth of the directory path requested. It allows you to limit the length of default appIDs to a specific number of directories.

The depth is the number of directories that the appID will be truncated to. e.g.:

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

Note: pubcookie_dir_depth is overridden by pubcookie_app_id unless pubcookie_catenate_app_ids is enabled.

4.5. pubcookie_catenate_app_ids

syntax: pubcookie_catenate_app_ids on | off
context: main, server

This directive causes appIDs to be constructed by catenating all configured values rather than replacing the value as subsequent configuration is discovered.

When PubcookieCatenateAppIDs is enabled, pubcookie_dir_depth and pubcookie_app_id values are accumulative.

4.6. pubcookie_app_srv_id

Syntax: pubcookie_app_srv_id AppServerID
Context: main, server

Allows you to specify an AppSrvID string, instead of using the default based on your ServerName.

4.7. pubcookie_login

Syntax: pubcookie_login url-of-login-server
Context: main, server

The location of the login cgi on the pubcookie login server.

4.8. pubcookie_login_method

Syntax: pubcookie_login_method GET|POST
Context: main, server

This directive specifies how authentication requests and responses are communicated between the module and the login server.

The default method, GET, is Pubcookie's classic cookie-based messaging method. It communicates the request and response using meta-refresh redirects and cookies scoped to the enterprise domain (see pubcookie_domain).

The newer method, POST, is closer to the industry standard SAML Browser/POST profile. It communicates the request and response using HTTP POST message bodies and uses, but does not require, Javascript to facilitate the process. It requires an additional PubcookiePostURL endpoint to consume the initial response sent by the login server.

All versions of the module prior to 3.2.0 can only use the GET method. Versions 3.2.0 and higher support either method.

4.9. pubcookie_post

Syntax: pubcookie_post
Context: location

This directive should be placed in a location used to consume authentication responses sent from the login server when using the POST pubcookie_login_method. The location should reside on the same virtual server as the secured web application.

Usually it should be defined as "location = /PubCookie.reply { pubcookie_post; }".

The Apache version of this directive is named PubCookiePostURL and has the POST endpoint URL as its parameter. In Nginx the endpoint URL is defined by the location element.

4.10. pubcookie_domain

Syntax: pubcookie_domain domain
Context: main, server

The DNS domain used to scope the cookies that carry the messages in Pubcookie's classic cookie-based messaging method. It must be at least a second level domain.

Note: Sites can use the POST-based messaging method to avoid DNS domain issues entirely. Sites in country code top-level domains (e.g. example.ca) must do so, since browsers don't allow cookies to be set to second level domains within country code top-level domains. See pubcookie_login_method.

4.11. pubcookie_granting_cert_file

Syntax: pubcookie_granting_cert_file filename
Context: main, server

The name of the file containing the login server's certificate used to verify granting cookies.

The default is /usr/local/pubcookie/pubcookie_granting.cert which is defined as PBC_G_CERTFILE in pbc_config.h.

4.12. pubcookie_session_key_file

Syntax: pubcookie_session_key_file filename
Context: main, server

The name of the file containing the private key for session cookies.

The default is /usr/local/pubcookie/pubcookie_session.key which is defined as PBC_S_KEYFILE in pbc_config.h.

4.13. pubcookie_session_cert_file

Syntax: pubcookie_session_cert_file filename
Context: main, server

The name of the file containing the certificate for session cookies.

The default is /usr/local/pubcookie/pubcookie_session.cert which is defined as PBC_S_CERTFILE in pbc_config.h.

4.14. pubcookie_crypt_key_file

Syntax: pubcookie_crypt_keyfile filename
Context: main, server

The name of the file containing the symmetric encryption key obtained from your keyserver for encrypting/decrypting private data.

The default is /usr/local/pubcookie/c_key which is defined as PBC_CRYPT_KEYFILE in pbc_config.h.

4.15. pubcookie_end_session

Syntax: pubcookie_end_session redirect | clearLogin | on | off
Context: location

This directive is used to end an application session. It should be placed in a child directory or explicitly have the same pubcookie_app_id as the application it is going to affect. (E.g., if /webapp/ defines the AuthType directive, then /webapp/logout/ would typically be used to define PubcookieEndSession.)

With arguments on, redirect, and clearLogin the session cookie is cleared. Re-requesting the resource will require a trip to the login server to retrieve a new granting cookie. Note: session cookies of other applications are not cleared by the PubcookieEndSession directive, only the session cookie applicable to the scope of the current application.

After clearing the session cookie, the redirect and clearLogin arguments redirect the browser back to the login server which generates a response page. The clearLogin argument also causes the login server to clear the user's login cookie.

The off argument turns off all PubcookieEndSession functionality.

4.16. pubcookie_encryption

Syntax: pubcookie_encryption AES | DES | AES+DOMAIN
Context: main, server

This directive defines the encryption algorithm used by the module to encrypt and decrypt private cookie data, including pre-session and session cookies as well as the type of encryption it asks for and expects from the login server for granting cookies and messages.

In version 3.3.0 and higher, AES encryption is the default (unless the module has been built with the --enable-default-des option). The only encryption method supported in earlier versions is DES. Therefore, you must set this directive to use DES encryption to interoperate with login servers earlier than version 3.3.0.

The AES+DOMAIN setting enables the module's wildcard subdomain capability.

4.17. pubcookie_session_reauth

Syntax: pubcookie_session_reauth on | off | grace-time-in-seconds
Context: main, server, location

When set to on, the PubcookieSessionCauseReAuth directive causes the user to be reauthenticated, thus overriding single sign-on. Users must re-enter valid credentials to establish an application session.

Use a grace-time-in-seconds to indicate a grace time wherein no reauthentication is necessary (e.g., 1800 for 30 minutes of grace time). This feature allows an application to establish an acceptable balance between convenience and risk.

4.18. pubcookie_auth_type_names

Syntax:
Context:

This directive is not used in the Nginx version of the pubcookie module. A similar directvive PubcookieAuthTypeNames is used in the Apache pubcookie module to associate authentication flavors with Apache authorization types

Note: for compatibility with Apache module, the Nginx module exports the $pubcookie_auth_type variable, but its value is always WebISO for successful authentications and a null string when not authenticated.

4.19. pubcookie_no_prompt

Syntax: pubcookie_no_prompt on | off
Context: main, server, location

This directive prevents the login server from displaying the login page, while still allowing single sign-on to the resource if the user has already logged in.

If the user already has a valid login cookie they will be logged in normally: i.e., returned to the application and given a standard session cookie. If, on the other hand, they do not have a valid login cookie they will be silently returned to the application (i.e., they won't be prompted to log in) and given a session cookie with a blank id.

The $pubcookie_user environment variable will be set only if the user has a valid login cookie, thus taking advantage of the no-prompt option and single sign-on. These environment variables will not be set (just like any other unauthenticated request) if the user has no valid login cookie.

Notes: Users may find sites behave inconsistently when the no-prompt option is in use, not realzing that the behavior depends on whether they've already logged in. Also, because a session cookie with the blank id is established when the user hasn't already logged in, the session will remain anonymous for the duration of the session, even if the user subsequently logs in elsewhere.

4.20. pubcookie_on_demand

Syntax: pubcookie_on_demand key directive1 directive2...
Context: main, server, location

This directive controls the module's on-demand functionality.

Directives used on demand are normally quiescent and have no effect. Only the presence of the activation cookie, OnDemandKey, with a value matching the key, activates the associated on-demand directives (directive1, directive2...) and sets the environment variable $pubcookie_on_demand_key to the active on-demand key. The activation cookie must accompany each request for resource to be protected on demand.

The following directives can be used on demand (i.e. can be tied to, and activated by, an on-demand key):

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

Activated PubcookieOnDemand directives will overrule any equivalent directives specified elsewhere.

Notes: The activation cookie, OnDemandKey, and its key value are plain text. Applications must query the $pubcookie_on_demand_key environment variable to make sure the remote user is authenticated and authorized according to the desired on-demand key. Therefore, applications must also allow for, and adjust to, missing or null $pubcookie_user and $pubcookie_on_demand_key environment variables.

4.21. pubcookie_addl_request

Syntax: pubcookie_addl_request opt1=val1 [opt2=val2...]
Context: main, server, location

This directive allows the application to give arbitrary requests to the login server. The directive causes the following options to be sent to the login server along with authentication requests.

Currently, it is site-defined what options cause what sort of responses from the login server and how these responses are returned. Eventually, there will be a standardized mechanism for returning answers. Likely they will be returned in extensions to the granting response and set as environment variables.

4.22. pubcookie_no_obscure_cookies

Syntax: pubcookie_no_obscure_cookies on | off
Context: main, server

This directive controls whether pubcookie session cookies are available to other Nginx modules and CGI applications. By default this parameter is set to on, so that session cookies are available to all modules and applications. If you set this to "off", session cookies will be obscured by the module before being exposed to other handlers. This setting increases total security, but in particular cases (e.g. sometimes when a secure resources is accessed from Google Chrome) it can result in authentication failures.

4.23. pubcookie_no_clean_creds

Syntax: pubcookie_no_clean_creds on | off
Context: main, server

By default mod_pubcookie runs a cleanup at the end of the request to remove all credentials left by flavor_getcred. With this directive enabled all credentials are left in place. This would be needed for an application having running mod_pubcookie for authentication only, and leaving all session handling to the application itself, thus not having mod_pubcookie in the handler stack.

4.24. pubcookie_egd_device

syntax: pubcookie_egd_device location
context: main, server

Location of EGD socket (e.g. /dev/egd-pool) if your system lacks entropy.

4.25. pubcookie_no_blank

syntax: pubcookie_no_blank
context: main, server

This directive is deprecated in versions 3.2.1 and higher. Use the pubcookie_no_obscure_cookies directive instead.

4.26. pubcookie_super_debug

syntax: pubcookie_super_debug on | off
Context: main

This parameter is turned off by default. If you experience configuration problems, set this to "on". After nginx restart the module will print defailed logs in the nginx error log, usually /var/log/nginx/error.log.

4.27. pubcookie_set_remote_user

syntax: pubcookie_set_remote_user on | off
Context: main, server, location

This parameter is off by default, so that authorized user name (or a blank string, if not authorized) is stored in the $pubcookie_user Nginx variable. When this is set to "on", the user name will be additionally stored in the standard Nginx variable $remote_user.

Attachments