# nginx-krbauth [](https://pypi.org/project/nginx-krbauth/) [](https://pypi.org/project/nginx-krbauth/) [](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.
### 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;
```
## 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;
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/quantum5/nginx-krbauth",
"name": "nginx-krbauth",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "ldap kerberos nginx",
"author": "quantum",
"author_email": "quantum2048@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/27/03/372568745aa9c35dcc2c6555a323757554dea26ca1a5158bdfe3db1c967a/nginx_krbauth-0.0.4.tar.gz",
"platform": null,
"description": "# nginx-krbauth [](https://pypi.org/project/nginx-krbauth/) [](https://pypi.org/project/nginx-krbauth/) [](https://pypi.org/project/nginx-krbauth/)\nLDAP + Kerberos authenticator for nginx's auth_request module.\n\n## Installation\n\n```sh\npip install nginx-krbauth\n```\n\nIf, for some reason, you want to use the latest code from git:\n\n```sh\npip install git+https://github.com/quantum5/nginx-krbauth.git\n```\n\n## Usage\n\nLoad `nginx_krbauth:app` into any WSGI compatible server.\nConfiguration is done through environment variables.\n\nExample:\n\n```ini\n[uwsgi]\nprotocol = uwsgi\nsocket = /tmp/krbauth.sock\nmodule = nginx_krbauth:app\nenv = KRB5_KTNAME=FILE:/home/krbauth/.keytab\nenv = KRBAUTH_HMAC_KEY=hunter2\nenv = KRBAUTH_LDAP_SERVER=ldapi:///\nenv = KRBAUTH_LDAP_BIND_DN=cn=http,ou=Apps,dc=example,dc=com\nenv = KRBAUTH_LDAP_BIND_AUTHTOK=hunter2\nenv = KRBAUTH_LDAP_SEARCH_BASE=dc=example,dc=com\n```\n\n`nginx_krbauth` exports two HTTP endpoints:\n\n* `/krbauth`: This endpoint performs SPNEGO authentication. When done, it\n sets a session cookie and generates a 307 redirect to the URL in the `next`\n GET parameter.\n* `/krbauth/check`: The endpoint checks the validity of the session cookie. If\n valid, it returns 200. Otherwise, it returns 401.\n\nThe intention is to use `/krbauth/check` as `auth_request` in your `nginx`\nconfiguration. On 401, `nginx` should be configured to generate a redirect to\n`/krbauth`.\n\n## Configuration\n\n* `KRB5_KTNAME`: This is actually a Kerberos setting. It should point to a\n keytab file that only the user running `nginx_krbauth` can read containing\n the Kerberos host principals.\n* `KRBAUTH_HMAC_KEY` (required): This is the HMAC key used to sign cookies. It\n should be a long random string. Keep it secret!\n* `KRBAUTH_KEY_DURATION`: The duration (in seconds) for which the session cookie\n is valid. Default: 1 hour.\n* `KRBAUTH_RANDOM_SIZE`: The length of the nonce in the session cookie in bytes.\n Default: 32.\n* `KRBAUTH_GSSAPI_NAME`: The GSSAPI name for the service. Leave blank if any\n name in the keytab is fine.\n* `KRBAUTH_SECURE_COOKIE`: This controls whether the session cookie is marked as\n HTTPS-only. Default: yes. Set to `0` or `no` to disable.\n\n### LDAP\n\n`nginx_krbauth` can also optionally check LDAP group membership. It does so by\nlooking up the groups of the LDAP entity whose `krbPrincipalName` attribute\nmatches the name of the Kerberos principal used to authenticate.\n\nThe group is specified through the WSGI environment variable\n`KRBAUTH_LDAP_GROUP`. This could be set through `uwsgi_param`, for example.\n\nThe following environment variables are used to configure `nginx_krbauth`'s\nLDAP support:\n\n* `KRBAUTH_LDAP_SERVER`: The LDAP URI used to connect to the LDAP server.\n* `KRBAUTH_LDAP_SEARCH_BASE`: The root of the subtree to search for LDAP\n entities for `krbPrincipalName` and group membership.\n* `KRBAUTH_LDAP_BIND_DN`: The DN used to bind to the LDAP server. Leave blank\n for anonymous bind.\n* `KRBAUTH_LDAP_BIND_AUTHTOK`: The password used to bind to the LDAP server.\n Leave blank for anonymous bind.\n\nLDAP binding can also be used as a fallback authentication mechanism through\nHTTP Basic authentication. This is useful when SPNEGO is not supported, or when\nthe client does not support Kerberos. To use this, configure:\n\n* `KRBAUTH_LDAP_USER_DN`: A string template to convert usernames into LDAP DNs.\n There should be one `%s` symbol in this string, which will be replaced by the\n username.\n\n### TLS Client Certificate\n\nIt's also possible to use client certificates on machines that have them for\nauthentication purposes instead of using LDAP or Kerberos. To do this, set\nthe environment variable `KRBAUTH_TLS_CERT_AUTH` to `1` or `yes`.\n\nThen, pass the WSGI environment variable `NGINX_SSL_CLIENT_VERIFY` from `nginx`,\nsetting it to the value of `$ssl_client_verify`, like this:\n\n```nginx\nuwsgi_param NGINX_SSL_CLIENT_VERIFY \"$ssl_client_verify\";\n```\n\nYou most likely want to make client certificate verification optional if you\nare using it with `nginx-krbauth`:\n\n```nginx\nssl_client_certificate /path/to/ca.crt;\nssl_verify_client optional;\n```\n\n## Example `nginx.conf`\n\n```nginx\nauth_request /krbauth/check;\nerror_page 401 = @krbauth;\nlocation @krbauth {\n return 307 /krbauth?next=$request_uri;\n}\n\nlocation /krbauth {\n auth_request off;\n error_page 527 error.html; # To cancel out error_page 401 outside.\n uwsgi_pass unix:/tmp/krbauth.sock;\n uwsgi_pass_request_body off;\n uwsgi_param KRBAUTH_LDAP_GROUP \"cn=group,dc=example,dc=com\";\n include uwsgi_params;\n}\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "LDAP + Kerberos authenticator for nginx's auth_request module.",
"version": "0.0.4",
"project_urls": {
"Homepage": "https://github.com/quantum5/nginx-krbauth"
},
"split_keywords": [
"ldap",
"kerberos",
"nginx"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5f1c29e9f31b7cca5ccc31efbddc410343dba0cf87cee172d525c436a9eca66e",
"md5": "71a2afd2cc2427a0e8910630c12f57ad",
"sha256": "14b54e003072cd5d7238ac76e8eb4c120f67b747b0ce0f2439a03f3322568d96"
},
"downloads": -1,
"filename": "nginx_krbauth-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "71a2afd2cc2427a0e8910630c12f57ad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 6645,
"upload_time": "2024-10-08T04:24:15",
"upload_time_iso_8601": "2024-10-08T04:24:15.182928Z",
"url": "https://files.pythonhosted.org/packages/5f/1c/29e9f31b7cca5ccc31efbddc410343dba0cf87cee172d525c436a9eca66e/nginx_krbauth-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2703372568745aa9c35dcc2c6555a323757554dea26ca1a5158bdfe3db1c967a",
"md5": "a42990cc9c77671cc290dd00e176e738",
"sha256": "5939721ef362cbc5600f2d0b1f980e07a441adae3ebf4abe966c77a29c029099"
},
"downloads": -1,
"filename": "nginx_krbauth-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "a42990cc9c77671cc290dd00e176e738",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6434,
"upload_time": "2024-10-08T04:24:16",
"upload_time_iso_8601": "2024-10-08T04:24:16.706745Z",
"url": "https://files.pythonhosted.org/packages/27/03/372568745aa9c35dcc2c6555a323757554dea26ca1a5158bdfe3db1c967a/nginx_krbauth-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-08 04:24:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "quantum5",
"github_project": "nginx-krbauth",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "nginx-krbauth"
}
JSON
