nginx-krbauth

LDAP + Kerberos authenticator for nginx's auth_request module.

Installation

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

Usage

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, it sets a session cookie and generates a 307 redirect to the URL in the next GET parameter.
• /krbauth/check: The endpoint checks the validity of the session cookie. If valid, it returns 200. Otherwise, it returns 401.

The 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.

Configuration

• KRB5_KTNAME: This is actually a Kerberos setting. It should point to a keytab file that only the user running nginx_krbauth can read containing the Kerberos host principals.
• KRBAUTH_HMAC_KEY (required): This is the HMAC key used to sign cookies. It should be a long random string. Keep it secret!
• KRBAUTH_KEY_DURATION: The duration (in seconds) for which the session cookie is valid. Default: 1 hour.
• KRBAUTH_RANDOM_SIZE: The length of the nonce in the session cookie in bytes. Default: 32.
• KRBAUTH_GSSAPI_NAME: The GSSAPI name for the service. Leave blank if any name in the keytab is fine.
• KRBAUTH_SECURE_COOKIE: This controls whether the session cookie is marked as HTTPS-only. Default: yes. Set to 0 or no to disable.

LDAP

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 LDAP entities for krbPrincipalName and group membership.
• KRBAUTH_LDAP_BIND_DN: The DN used to bind to the LDAP server. Leave blank for anonymous bind.
• KRBAUTH_LDAP_BIND_AUTHTOK: The password used to bind to the LDAP server. Leave blank for anonymous bind.

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. There should be one %s symbol in this string, which will be replaced by the username.

You may also choose to exclusively use LDAP without using any Kerberos or GSSAPI by setting the environment variable KRBAUTH_DISABLE_GSSAPI=yes.

TLS Client Certificate

It'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;

Rate limiting

nginx-krbauth supports rate limiting. The rate limiting frequency can be configured by KRBAUTH_LIMITER_FREQUENCY environment variable. The default is 10 / 5 minute, but you can adjust this as needed.

The rate limiting state is stored in memory. You can use any storage mechanism supported by the limits PyPI package. Remember to install any dependencies!

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