LDAP + Kerberos authenticator for nginx's auth_request module.
MIT License
LDAP + Kerberos authenticator for nginx's auth_request module.
pip install nginx-krbauth
If, for some reason, you want to use the latest code from git:
pip install git+https://github.com/quantum5/nginx-krbauth.git
Load nginx_krbauth:app
into any WSGI compatible server.
Configuration is done through environment variables.
Example:
[uwsgi]
protocol = uwsgi
socket = /tmp/krbauth.sock
module = nginx_krbauth:app
env = KRB5_KTNAME=FILE:/home/krbauth/.keytab
env = KRBAUTH_HMAC_KEY=hunter2
env = KRBAUTH_LDAP_SERVER=ldapi:///
env = KRBAUTH_LDAP_BIND_DN=cn=http,ou=Apps,dc=example,dc=com
env = KRBAUTH_LDAP_BIND_AUTHTOK=hunter2
env = KRBAUTH_LDAP_SEARCH_BASE=dc=example,dc=com
nginx_krbauth
exports two HTTP endpoints:
/krbauth
: This endpoint performs SPNEGO authentication. When done, itnext
/krbauth/check
: The endpoint checks the validity of the session cookie. IfThe intention is to use /krbauth/check
as auth_request
in your nginx
configuration. On 401, nginx
should be configured to generate a redirect to
/krbauth
.
KRB5_KTNAME
: This is actually a Kerberos setting. It should point to anginx_krbauth
can read containingKRBAUTH_HMAC_KEY
(required): This is the HMAC key used to sign cookies. ItKRBAUTH_KEY_DURATION
: The duration (in seconds) for which the session cookieKRBAUTH_RANDOM_SIZE
: The length of the nonce in the session cookie in bytes.KRBAUTH_GSSAPI_NAME
: The GSSAPI name for the service. Leave blank if anyKRBAUTH_SECURE_COOKIE
: This controls whether the session cookie is marked as0
or no
to disable.nginx_krbauth
can also optionally check LDAP group membership. It does so by
looking up the groups of the LDAP entity whose krbPrincipalName
attribute
matches the name of the Kerberos principal used to authenticate.
The group is specified through the WSGI environment variable
KRBAUTH_LDAP_GROUP
. This could be set through uwsgi_param
, for example.
The following environment variables are used to configure nginx_krbauth
's
LDAP support:
KRBAUTH_LDAP_SERVER
: The LDAP URI used to connect to the LDAP server.KRBAUTH_LDAP_SEARCH_BASE
: The root of the subtree to search for LDAPkrbPrincipalName
and group membership.KRBAUTH_LDAP_BIND_DN
: The DN used to bind to the LDAP server. Leave blankKRBAUTH_LDAP_BIND_AUTHTOK
: The password used to bind to the LDAP server.LDAP binding can also be used as a fallback authentication mechanism through HTTP Basic authentication. This is useful when SPNEGO is not supported, or when the client does not support Kerberos. To use this, configure:
KRBAUTH_LDAP_USER_DN
: A string template to convert usernames into LDAP DNs.%s
symbol in this string, which will be replaced by theIt's also possible to use client certificates on machines that have them for
authentication purposes instead of using LDAP or Kerberos. To do this, set
the environment variable KRBAUTH_TLS_CERT_AUTH
to 1
or yes
.
Then, pass the WSGI environment variable NGINX_SSL_CLIENT_VERIFY
from nginx
,
setting it to the value of $ssl_client_verify
, like this:
uwsgi_param NGINX_SSL_CLIENT_VERIFY "$ssl_client_verify";
You most likely want to make client certificate verification optional if you
are using it with nginx-krbauth
:
ssl_client_certificate /path/to/ca.crt;
ssl_verify_client optional;
nginx.conf
auth_request /krbauth/check;
error_page 401 = @krbauth;
location @krbauth {
return 307 /krbauth?next=$request_uri;
}
location /krbauth {
auth_request off;
error_page 527 error.html; # To cancel out error_page 401 outside.
uwsgi_pass unix:/tmp/krbauth.sock;
uwsgi_pass_request_body off;
uwsgi_param KRBAUTH_LDAP_GROUP "cn=group,dc=example,dc=com";
include uwsgi_params;
}