Nginx with PAM Authentication

As I introduced in last article, Nginx is a lightweight Web and reversed proxy server that is gaining momentum. If you have URLs to be accessed only by authenticated users, you can have many options. In this article, I just introduce a very easy way for the Nginx to leverage the PAM (Pluggable Authentication Module) for user authentication. We will use OS user for authentication (there are many more methods supported by PAM). If you have a valid user with the Linux on which Nginx runs, your request will pass through; otherwise, it would be blocked.

Better than authenticating in Web applications, using Nginx allows multiple Web applications to share same set of user credentials. In some sense, you can think of this as single sign on (SSO).

Lost VMs or Containers? Too Many Consoles? Too Slow GUI? Time to learn how to "Google" and manage your VMware and clouds in a fast and secure HTML5 App.

Before moving forward, make sure you have nginx-extras installed on your system. The command is listed in last article.

Open Access to Nginx User

Because we will use the OS user name and password for user authentication, we need to open the access of the related password file to the user that runs Nginx server which is www-data. One simple Linux command can achieve it as follows:

# usermod -a -G shadow www-data

Change configurations

Within the /etc/pam.d create a new file called nginx. You can change the file name as long as you reference the new name in later configuration file.

# more /etc/pam.d/nginx
@include common-auth

Then, we need to modify the Nginx configuration file: /etc/nginx/nginx.conf

        listen          443;
        ssl             on;
        ### SSL log files ###
        access_log      /var/log/nginx/ssl-access.log;
        error_log       /var/log/nginx/ssl-error.log;
        ### SSL cert files ###
        ssl_certificate      ssl/server.crt;
        ssl_certificate_key  ssl/server.key;
        ### Add SSL specific settings here ###
        ssl_protocols        SSLv3 TLSv1 TLSv1.1 TLSv1.2;
        ssl_ciphers RC4:HIGH:!aNULL:!MD5;
        ssl_prefer_server_ciphers on;
        keepalive_timeout    60;
        ssl_session_cache    shared:SSL:10m;
        ssl_session_timeout  10m;
        location /
            auth_pam    "Secure Zone";
            auth_pam_service_name   "nginx";
            proxy_pass  http://localhost:8080;
            ### force timeouts if one of backend is died ##
            proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504;
            ### Set headers ####
            proxy_headers_hash_max_size 51200;
            proxy_headers_hash_bucket_size 6400;
            proxy_set_header        Accept-Encoding   "";
            proxy_set_header        Host            $host;
            proxy_set_header        X-Real-IP       $remote_addr;
            proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header        X-Forwarded-Proto $scheme;
            add_header              Front-End-Https   on;
            proxy_redirect     off;

Exclude certain URLs

If you, most likely you would, have certain resources to be excluded from user authentication, you can do as the follows. It would open up overview.html and /help/ without user authentication.

    location ~ (/overview\.html|/help/helps\.zip)
        auth_basic off;
        proxy_pass  http://localhost:8000;
        allow all; # Allow all to see content

Nginx is really powerful and flexible. We just scratched the surface in last post and this one. For more info, check out its Web site and the commercial company behind it.

This entry was posted in Applications & Tools and tagged , , , . Bookmark the permalink. Post a comment or leave a trackback: Trackback URL.


  1. Not SSO
    Posted May 22, 2014 at 3:12 pm | Permalink

    This isn’t “Single” Sign On, it is single credential but I still have to login to every vhost separately and there are no cookies to leverage for a “Remember me” kind of functionality.

  2. Bruno
    Posted September 9, 2014 at 7:10 am | Permalink

    Hey!, thanks for the tutorial, it was very useful, I’m actually trying to implement it with google 2 factor authentication, the point is it doesn’t recognize the password and it fails on authentication… everything works perfect with apache and pwauth, but no for nginx, any idea?.


  3. Posted September 9, 2014 at 3:03 pm | Permalink

    Glad you find it useful. I haven’t played with Google 2 factor authentication, so cannot comment. Sorry and good luck.

  4. Posted April 8, 2015 at 8:27 am | Permalink


    I’m concerned about this line:

    usermod -a -G shadow www-data

    If your code is ever subject to a directory traversal attack then the above permissions would allow an attacker to get a full list of all the usernames and password hashes and thereby gain access to your system.

    I’d recommend finding another way of doing this other than allowing your web server processes to access /etc/shadow.



  5. Posted April 8, 2015 at 6:10 pm | Permalink

    Thanks Matt,

    Could you elaborate more on the “another” way? Thanks!


  6. Posted July 4, 2016 at 1:00 am | Permalink

    This results in an all or nothing authentication. There’s no further access control or authorisation controls after NGINX passes the user request through PAM. In fact, after a user passes through PAM, they are executing the arbitrary handler at the proxy passed upstream. Which is most likely setup to run as www-data. A continuation of this technique would be drop privileges and use setuid setgid to the user that was authenticated with PAM at the proxy upstream, this would require passing the uid and gid as proxy headers.

One Trackback

Post a Comment

Your email is never published nor shared. Required fields are marked *


You may use these HTML tags and attributes <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>


    My company has created products like vSearch ("Super vCenter"), vijavaNG APIs, EAM APIs, ICE tool. We also help clients with virtualization and cloud computing on customized development, training. Should you, or someone you know, need these products and services, please feel free to contact me: steve __AT__

    Me: Steve Jin, VMware vExpert who authored the VMware VI and vSphere SDK by Prentice Hall, and created the de factor open source vSphere Java API while working at VMware engineering. Companies like Cisco, EMC, NetApp, HP, Dell, VMware, are among the users of the API and other tools I developed for their products, internal IT orchestration, and test automation.