1Nginx module for HTTP SPNEGO auth 2================================= 3 4This module implements adds [SPNEGO](http://tools.ietf.org/html/rfc4178) 5support to nginx(http://nginx.org). It currently supports only Kerberos 6authentication via [GSSAPI](http://en.wikipedia.org/wiki/GSSAPI) 7 8 9Prerequisites 10------------- 11 12Authentication has been tested with (at least) the following: 13 14* Nginx 1.2 through 1.7 15* Internet Explorer 8 and above 16* Firefox 10 and above 17* Chrome 20 and above 18* Curl 7.x (GSS-Negotiate), 7.x (SPNEGO/fbopenssl) 19 20The underlying kerberos library used for these tests was MIT KRB5 v1.8. 21 22 23Installation 24------------ 25 261. Download [nginx source](http://www.nginx.org/en/download.html) 271. Extract to a directory 281. Clone this module into the directory 291. Follow the [nginx install documentation](http://nginx.org/en/docs/install.html) 30and pass an `--add-module` option to nginx configure: 31 32 ./configure --add-module=spnego-http-auth-nginx-module 33 34Note that if it isn't clear, you do need KRB5 (MIT or Heimdal) header files installed. On Debian based distributions, including Ubuntu, this is the krb5-multidev, libkrb5-dev, heimdal-dev, or heimdal-multidev package depending on your environment. On other Linux distributions, you want the development libraries that provide gssapi_krb5.h. 35 36Configuration reference 37----------------------- 38 39You can configure GSS authentication on a per-location and/or a global basis: 40 41These options are required. 42* `auth_gss`: on/off, for ease of unsecuring while leaving other options in 43 the config file 44* `auth_gss_keytab`: absolute path-name to keytab file containing service 45 credentials 46 47These options should ONLY be specified if you have a keytab containing 48privileged principals. In nearly all cases, you should not put these 49in the configuration file, as `gss_accept_sec_context` will do the right 50thing. 51* `auth_gss_realm`: Kerberos realm name. If this is specified, the realm is only passed to the nginx variable $remote_user if it differs from this default. To override this behavior, set *auth_gss_format_full* to 1 in your configuration. 52* `auth_gss_service_name`: service principal name to use when acquiring 53 credentials. 54 55If you would like to authorize only a specific set of users, you can use the 56`auth_gss_authorized_principal` directive. The configuration syntax supports 57multiple entries, one per line. 58 59 auth_gss_authorized_principal <username>@<realm> 60 auth_gss_authorized_principal <username2>@<realm> 61 62The remote user header in nginx can only be set by doing basic authentication. 63Thus, this module sets a bogus basic auth header that will reach your backend 64application in order to set this header/nginx variable. The easiest way to disable 65this behavior is to add the following configuration to your location config. 66 67 proxy_set_header Authorization ""; 68 69A future version of the module may make this behavior an option, but this should 70be a sufficient workaround for now. 71 72If you would like to enable GSS local name rules to rewrite usernames, you can 73specify the `auth_gss_map_to_local` option. 74 75Basic authentication fallback 76----------------------------- 77 78The module falls back to basic authentication by default if no negotiation is 79attempted by the client. If you are using SPNEGO without SSL, it is recommended 80you disable basic authentication fallback, as the password would be sent in 81plaintext. This is done by setting `auth_gss_allow_basic_fallback` in the 82config file. 83 84 auth_gss_allow_basic_fallback off 85 86These options affect the operation of basic authentication: 87* `auth_gss_realm`: Kerberos realm name. If this is specified, the realm is 88 only passed to the nginx variable $remote_user if it differs from this 89 default. To override this behavior, set *auth_gss_format_full* to 1 in your 90 configuration. 91* `auth_gss_force_realm`: Forcibly authenticate using the realm configured in 92 `auth_gss_realm` or the system default realm if `auth_gss_realm` is not set. 93 This will rewrite $remote_user if the client provided a different realm. If 94 *auth_gss_format_full* is not set, $remote_user will not include a realm even 95 if one was specified by the client. 96 97 98Troubleshooting 99--------------- 100 101### 102Check the logs. If you see a mention of NTLM, your client is attempting to 103connect using [NTLMSSP](http://en.wikipedia.org/wiki/NTLMSSP), which is 104unsupported and insecure. 105 106### Verify that you have an HTTP principal in your keytab ### 107 108#### MIT Kerberos utilities #### 109 110 $ KRB5_KTNAME=FILE:<path to your keytab> klist -k 111 112or 113 114 $ ktutil 115 ktutil: read_kt <path to your keytab> 116 ktutil: list 117 118#### Heimdal Kerberos utilities #### 119 120 $ ktutil -k <path to your keytab> list 121 122### Obtain an HTTP principal 123 124If you find that you do not have the HTTP service principal, 125are running in an Active Directory environment, 126and are bound to the domain such that Samba tools work properly 127 128 $ env KRB5_KTNAME=FILE:<path to your keytab> net ads -P keytab add HTTP 129 130If you are running in a different kerberos environment, you can likely run 131 132 $ env KRB5_KTNAME=FILE:<path to your keytab> krb5_keytab HTTP 133 134### Increase maximum allowed header size 135 136In Active Directory environment, SPNEGO token in the Authorization header includes 137PAC (Privilege Access Certificate) information, which includes all security groups 138the user belongs to. This may cause the header to grow beyond default 8kB limit and 139causes following error message: 140 141 400 Bad Request 142 Request Header Or Cookie Too Large 143 144For performance reasons, best solution is to reduce the number of groups the user 145belongs to. When this is impractical, you may also choose to increase the allowed 146header size by explicitly setting the number and size of Nginx header buffers: 147 148 large_client_header_buffers 8 32k; 149 150Debugging 151--------- 152 153The module prints all sort of debugging information if nginx is compiled with 154the `--with-debug` option, and the `error_log` directive has a `debug` level. 155 156 157NTLM 158---- 159 160Note that the module does not support [NTLMSSP](http://en.wikipedia.org/wiki/NTLMSSP) 161in Negotiate. NTLM, both v1 and v2, is an exploitable protocol and should be avoided 162where possible. 163 164Help 165---- 166 167If you're unable to figure things out, please feel free to open an 168issue on Github and I'll do my best to help you. 169