# 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.
## 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": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "ldap kerberos nginx",
"author": "quantum",
"author_email": "quantum2048@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/11/06/5a193f73ab02887601e5973a9a95f93c824b3336c51e726dff3072a52cc0/nginx_krbauth-0.0.3.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## 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": "",
"summary": "LDAP + Kerberos authenticator for nginx's auth_request module.",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://github.com/quantum5/nginx-krbauth"
},
"split_keywords": [
"ldap",
"kerberos",
"nginx"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0f800be4bbb319df94e1c960215a5164ce05024b4dffead76414da54c235ec56",
"md5": "e5d39b14bd03980be25c527c42893804",
"sha256": "31a16996d82afc4e9b94a5972c6677e4412e1a816b884c6cceae28fdb816410d"
},
"downloads": -1,
"filename": "nginx_krbauth-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e5d39b14bd03980be25c527c42893804",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 6285,
"upload_time": "2023-12-21T08:26:22",
"upload_time_iso_8601": "2023-12-21T08:26:22.875486Z",
"url": "https://files.pythonhosted.org/packages/0f/80/0be4bbb319df94e1c960215a5164ce05024b4dffead76414da54c235ec56/nginx_krbauth-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "11065a193f73ab02887601e5973a9a95f93c824b3336c51e726dff3072a52cc0",
"md5": "d6122377c286bbd98ae79c7dcbc80999",
"sha256": "16b0f03f99a84bc36119b6358782edd02a2a3150379f1bf83d2429d36429e670"
},
"downloads": -1,
"filename": "nginx_krbauth-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "d6122377c286bbd98ae79c7dcbc80999",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6077,
"upload_time": "2023-12-21T08:26:24",
"upload_time_iso_8601": "2023-12-21T08:26:24.384746Z",
"url": "https://files.pythonhosted.org/packages/11/06/5a193f73ab02887601e5973a9a95f93c824b3336c51e726dff3072a52cc0/nginx_krbauth-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-21 08:26:24",
"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
