Skip to content

Documentation

Jump to bottom
Andreas Vögele edited this page Aug 2, 2023 · 5 revisions

NAME

nginx-auth-saslauthd - Verify web users with Basic authentication and saslauthd

USAGE

location /private/ {
  auth_request /auth;
}

location = /auth {
  internal;
  proxy_pass http://unix:/run/nginx-auth/saslauthd.sock:/auth-basic;
  proxy_pass_request_body off;
  proxy_set_header Content-Length "";
  proxy_set_header X-Realm "Restricted";
}

DESCRIPTION

nginx-auth-saslauthd interfaces the nginx web server with the saslauthd daemon from Cyrus SASL. The service supports Basic authentication and verifies users with LDAP, PAM or other mechanisms supported by the saslauthd daemon. Authentication requests are forwarded from nginx with the auth_request directive.

CONFIGURATION

Create the file /etc/nginx/auth-saslauthd.conf if the default values do not fit.

{
  path    => '/run/saslauthd/mux',
  timeout => 10,
  service => 'nginx',
  realm   => '',
};

  • path

    The path to the communications socket. Defaults to /run/saslauthd/mux, /run/sasl2/mux, /var/run/saslauthd/mux, /var/state/saslauthd/mux or /var/sasl2/mux, depending on the platform.

  • timeout

    A timeout when writing to and reading from the communications socket. Defaults to 10 seconds.

  • service

    The SASL service name. Defaults to "nginx".

  • realm

    The SASL realm the users belong to. Defaults to the empty string. The SASL realm is not the authentication realm.

NGINX

Use the auth_request directive to enable authentication. Set the X-Realm header to the authentication realm. The realm must only contain ASCII characters.

location /private/ {
  auth_request /auth;
}

location = /auth {
  internal;
  proxy_pass http://unix:/run/nginx-auth/saslauthd.sock:/auth-basic;
  proxy_pass_request_body off;
  proxy_set_header Content-Length "";
  proxy_set_header X-Realm "Restricted";
}

CACHING

nginx can be configured to cache authentication requests, but the credentials will be stored in cleartext.

http {
  proxy_cache_path /var/cache/nginx/auth_cache keys_zone=auth_cache:1m;

  server {
    location = /auth {
      proxy_cache auth_cache;
      proxy_cache_key "$http_authorization";
      proxy_cache_valid 200 10m;
    }
  }
}

LOGGING

Configure nginx to log authentication failures.

http {
  map "$status $remote_user" $auth_failed {
    default 0;
    "~^401 ([^-]|..)" 1;
  }

  log_format auth '$status $remote_addr "$remote_user" "$request"
    "$http_user_agent"';

  server {
    access_log
      syslog:server=unix:/dev/log,facility=auth,severity=warn,nohostname
      auth if=$auth_failed;
  }
}

SASLAUTHD

If you use LDAP, create /etc/saslauthd.conf.

touch /etc/saslauthd.conf
chmod 0600 /etc/saslauthd.conf

Add your LDAP settings.

ldap_servers: ldap://ad1.example.com ldap://ad2.example.com
ldap_start_tls: yes
ldap_tls_cacert_file: /etc/ssl/certs/EXAMPLE-ADS-CA.pem
ldap_tls_check_peer: yes
ldap_search_base: OU=Users,DC=EXAMPLE,DC=COM
ldap_filter: (sAMAccountName=%U)
ldap_bind_dn: CN=saslauthd,OU=Users,DC=EXAMPLE,DC=COM
ldap_password: secret

Credential caching can be enabled by passing the -c switch to saslauthd.

OPERATING SYSTEMS

DEBIAN AND UBUNTU

Install the sasl2-bin package. Enable and configure the authentication daemon in /etc/default/saslauthd.

START=yes
MECHANISMS="ldap"
MECH_OPTIONS=""
OPTIONS="-c -m /run/saslauthd"

If you use PAM instead of LDAP, create /etc/pam.d/nginx.

#%PAM-1.0
@include common-auth
@include common-account

FEDORA

Install the cyrus-sasl package. Configure the authentication daemon in /etc/sysconfig/saslauthd.

MECH=ldap
FLAGS="-c"

Read the saslauthd(8) manual page for information on how to run the saslauthd daemon unprivileged as user saslauth.

chgrp saslauth /etc/saslauthd.conf
chmod 0640 /etc/saslauthd.conf

If you use PAM instead of LDAP, create /etc/pam.d/nginx.

#%PAM-1.0
auth    include system-auth
account include system-auth

MAGEIA

Install the cyrus-sasl package. Configure the authentication daemon in /etc/sysconfig/saslauthd.

SASL_AUTHMECH=ldap
SASLAUTHD_OPTS="-c"

If you use PAM instead of LDAP, create /etc/pam.d/nginx.

#%PAM-1.0
auth    include system-auth
account include system-auth

OPENSUSE

Install the cyrus-sasl-saslauthd package. Configure the authentication daemon in /etc/sysconfig/saslauthd.

SASLAUTHD_AUTHMECH=ldap
SASLAUTHD_PARAMS="-c"

If you use PAM instead of LDAP, create /etc/pam.d/nginx.

#%PAM-1.0
auth    include common-auth
account include common-account

START SASLAUTHD

Enable and start the service.

systemctl enable saslauthd.service
systemctl restart saslauthd.service

AUTHENTICATION TEST

Check your setup with testsaslauthd.

unset HISTFILE
/usr/sbin/testsaslauthd -s nginx -u $USER -p 'your password'

SELINUX

Put the nginx-auth-saslauthd daemon into the web server's SELinux context and allow the daemon to use SASL.

semanage fcontext -a -t httpd_exec_t /usr/local/sbin/nginx-auth-saslauthd
restorecon /usr/local/sbin/nginx-auth-saslauthd
setsebool -P httpd_use_sasl on

SYSTEMD

Install the package libnss-systemd on Debian-based systems.

Users, who do not use systemd in nsswitch.conf, need to omit DynamicUser from the service file and create a system user.

useradd -r -M -d / -s /sbin/nologin -U nginx-auth

Create /etc/systemd/system/nginx-auth-saslauthd.service. The example below is for Debian-based systems. On RPM-based systems, the group is nginx instead of www-data. Use the supplementary group saslauth on operating systems from Red Hat. Other systems may not require a supplementary group to communicate with the saslauthd daemon.

[Unit]
Description=Basic authentication with saslauthd
After=network.target saslauthd.service
Before=nginx.service

[Service]
Type=simple
DynamicUser=yes
User=nginx-auth
Group=www-data
SupplementaryGroups=sasl
RuntimeDirectory=nginx-auth
RuntimeDirectoryMode=0750
UMask=0007
ExecStart=/usr/local/sbin/nginx-auth-saslauthd daemon -m production -l http+unix://%%2Frun%%2Fnginx-auth%%2Fsaslauthd.sock
CapabilityBoundingSet=
DevicePolicy=closed
IPAddressDeny=any
LockPersonality=yes
MemoryDenyWriteExecute=yes
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
PrivateNetwork=yes
PrivateTmp=yes
PrivateDevices=yes
PrivateUsers=yes
ProtectHostname=yes
ProtectClock=yes
ProtectKernelTunables=yes
ProtectKernelModules=yes
ProtectKernelLogs=yes
ProtectControlGroups=yes
ProtectProc=invisible
ProcSubset=pid
RestrictAddressFamilies=AF_UNIX
RestrictNamespaces=yes
RestrictRealtime=yes
RestrictSUIDSGID=yes
RemoveIPC=yes
SystemCallArchitectures=native
SystemCallFilter=@system-service
SystemCallFilter=~@privileged
SystemCallFilter=~@resources

[Install]
WantedBy=multi-user.target

Start the service.

systemctl --now enable nginx-auth-saslauthd.service

Test the running service.

curl -v --unix-socket /run/nginx-auth/saslauthd.sock \
     -H "X-Realm: hello, world" http://localhost/auth-basic

DEPENDENCIES

Requires Mojolicious 7.27 or later and the saslauthd daemon from Cyrus SASL.

INCOMPATIBILITIES

None.

BUGS AND LIMITATIONS

Basic authentication doesn't encrypt the credentials. Protect your site with HTTPS.

SEE ALSO

Mojolicious, Mojolicious::Guides::Cookbook, saslauthd(8), auth_request

AUTHOR

Andreas Vögele

LICENSE AND COPYRIGHT

Copyright (C) 2017-2023 Andreas Vögele

Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Clone this wiki locally