README.md
1# websspi
2
3[](https://godoc.org/github.com/quasoft/websspi) [](https://travis-ci.org/quasoft/websspi) [](https://coveralls.io/github/quasoft/websspi?branch=master) [](https://goreportcard.com/report/github.com/quasoft/websspi)
4
5`websspi` is an HTTP middleware for Golang that uses Kerberos/NTLM for single sign-on (SSO) authentication of browser based clients in a Windows environment.
6
7It performs authentication of HTTP requests without the need to create or use keytab files.
8
9The middleware implements the scheme defined by RFC4559 (SPNEGO-based HTTP Authentication in Microsoft Windows) to exchange security tokens via HTTP headers and uses SSPI (Security Support Provider Interface) to authenticate HTTP requests.
10
11## How to use
12
13The [examples directory](https://github.com/quasoft/websspi/tree/master/examples) contains a [simple web server](https://github.com/quasoft/websspi/blob/master/examples/server_windows.go) that demonstrates how to use the package.
14Before trying it, you need to prepare your environment:
15
161. Create a separate user account in active directory, under which the web server process will be running (eg. `user` under the `domain.local` domain)
17
182. Create a service principal name for the host with class HTTP:
19 - Start Command prompt or PowerShell as domain administrator
20 - Run the command below, replacing `host.domain.local` with the fully qualified domain name of the server where the web application will be running, and `domain\user` with the name of the account created in step 1.:
21
22 setspn -A HTTP/host.domain.local domain\user
23
243. Start the web server app under the account created in step 1.
25
264. If you are using Chrome, Edge or Internet Explorer, add the URL of the web app to the Local intranet sites (`Internet Options -> Security -> Local intranet -> Sites`)
27
285. Start Chrome, Edge or Internet Explorer and navigate to the URL of the web app (eg. `http://host.domain.local:9000`)
29
306. The web app should greet you with the name of your AD account without asking you to login. In case it doesn't, make sure that:
31
32 - You are not running the web browser on the same server where the web app is running. You should be running the web browser on a domain joined computer (client) that is different from the server. If you do run the web browser at the same server SSPI package will fallback to NTLM protocol and Kerberos will not be used.
33 - There is only one HTTP/... SPN for the host
34 - The SPN contains only the hostname, without the port
35 - You have added the URL of the web app to the `Local intranet` zone
36 - The clocks of the server and client should not differ with more than 5 minutes
37 - `Integrated Windows Authentication` should be enabled in Internet Explorer (under `Advanced settings`)
38
39## Security requirements
40
41- SPNEGO over HTTP provides no facilities for protection of the authroization data contained in HTTP headers (the `Authorization` and `WWW-Authenticate` headers), which means that the web server **MUST** enforce use of HTTPS to provide confidentiality for the data in those headers!
42
){kind=link}
){kind=link}
){kind=link}