nginx-krbauth 0.0.5
LDAP + Kerberos authenticator for nginx's auth_request module.
Keywords: ldap kerberos nginx

# nginx-krbauth [![PyPI](https://img.shields.io/pypi/v/nginx-krbauth.svg)](https://pypi.org/project/nginx-krbauth/) [![PyPI - Format](https://img.shields.io/pypi/format/nginx-krbauth.svg)](https://pypi.org/project/nginx-krbauth/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/nginx-krbauth.svg)](https://pypi.org/project/nginx-krbauth/)
LDAP + Kerberos authenticator for nginx's auth_request module.

## Installation

```sh
pip install nginx-krbauth
```

If, for some reason, you want to use the latest code from git:

```sh
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:

```ini
[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:

```nginx
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`:

```nginx
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][limits-storage] supported by the `limits` PyPI package.
Remember to install any dependencies!

## Example `nginx.conf`

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

[limits-storage]: https://limits.readthedocs.io/en/stable/storage.html#storage-scheme