doc

README.md

@@ -149,28 +149,47 @@ Edge does not require any configuration. But the browser ask the credentials to
 
 The API is automatically documented with [typedoc](https://github.com/TypeStrong/typedoc).
 
-
 **[Access to the detailed API document](./doc/api/README.md)**. 
 
-Note: you should read all the [sso source code](./src). You will see how powerfull the `api.sspi`, and `api.adsi` can bring to you.
+You should read all the [sso source code](./src). You will see how powerfull the native primitive exposed in `api.sspi`, and `api.adsi` can bring to you.
 
 You can also read the `mocha` [unit tests](./test) to see small examples.
 
-#### Typescript
+## Typescript
 
-This module is also integrated with Typescript.
+This module is written in two part: one native in C++ (Windows toolchain) and the other one in Typescript.
+So anything else is needed to use this module in typescript code.
 
 [Typescript example](./doc/typescript.md)
 
-#### NTLM
+## Authentication protocols
+
+### Kerberos
+
+Kerberos is recommanded for production running. For running with Kerberos protocol, both client and server needs to be joined on a [Windows Domain](https://en.wikipedia.org/wiki/Windows_domain).
+
+3 conditions must be met for running Kerberos:
+- The node server, running `node-expose-sspi` needs to be run as a domain user with service principal name (SPN) declared in Active Directory.
+- The client browser needs to be run on a windows domain account.
+- The website url needs to be declared in a white list of intranet website.
+
+[You can find more detail in the Kerberos dedicated documentation](./doc/Kerberos.md).
+
+### NTLM
+
+If you are not on a Windows Domain, `node-expose-sspi` will use the NLTM authentication protocol.
+
+If both the server and the client are on a Windows Domain, NTLM will be used if the Kerberos conditions are not met. [See the Kerberos chapter of this README](#Kerberos).
+
+The NTLM protocol is less secure than Kerberos and not secure at all if you are not under an HTTPS connection. This is because both login and password hash go on the HTTP request, just encoded in base64...
 
-If you are not on a Microsoft Windows Active Directory Domain, it will use the NLTM authentication protocol.
+Another thing bad in NTLM is that browsers sometimes popup a dialog box to ask credentials to the user. Your users don't like that. This is a bad user experience.
 
-Note: the NTLM protocol is not very secure, so be sure to be above HTTPS.
+## Production running
 
-#### Kerberos
+### Server behind a reverse proxy
 
-You should see [this Node Expose SSPI Kerberos dedicated documentation](./doc/Kerberos.md).
+[Example: node server behind an IIS proxy](./doc/use-case/production-windows.md)
 
 ## Examples
 

doc/use-case/production-windows.md

@@ -0,0 +1,122 @@
+# Node server behind a IIS reverse proxy
+
+In this example, we discuss how to setup a production system using a
+[reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy) with [SSL offloading](https://en.wikipedia.org/wiki/TLS_termination_proxy).
+
+Purpose is to expose the website `http://kiki` or `http://kiki.jlg.local` that will be in fact `http://musette:3000`.
+
+## Infrastructure
+
+You need to have many hosts:
+- `reverse-proxy-host`: A Windows Server OS running the following features:
+  - AD DS (Active Directory Domain Controller)
+  - DNS
+  - IIS
+- `server-host`: A Windows 10 OS running:
+  - nodejs and npm
+  - a server running `node-expose-sspi`
+- `client-host`: A Windows 10 OS running
+  - Chrome, or Firefox, or Edge
+
+For this example, let say the domain name is:
+- jlg.local (NETBIOS: JLG)
+
+Suppose we have two window domain accounts:
+- `[email protected]`: a user account for client.
+- `[email protected]`: a user account for server.
+Please create the above accounts on the domain controller (AD DS).
+
+For this example, let say that all host have a name:
+- `reverse-proxy-host`: `jlgdc01` (`192.168.1.216`)
+- `server-host`: `musette`
+- `client-host`: `chouchou`
+
+
+## Configuring server-host
+
+```
+mkdir myserver
+cd myserver
+npm init -y
+npm i node-expose-sspi express
+```
+
+create a `server.js` file in the `myserver` directory:
+```js
+const express = require('express');
+const { sso } = require('node-expose-sspi');
+
+const app = express();
+
+app.use(sso.auth());
+
+app.use((req, res) => {
+  res.json({
+    method: req.sso.method,
+    displayName: req.sso.user.displayName,
+  });
+});
+
+app.listen(3000, () =>
+  console.log('Server started on port 3000')
+);
+```
+
+You need to be connected as a Window Domain user.
+
+Start the server:
+```cmd
+node server.js
+```
+
+Test the server locally:
+```cmd
+start chrome http://musette:3000
+```
+
+## Configuring reverse-proxy-host
+
+You need to configure the DNS via an app called *DNS Manager*:
+- add a Host(A) rule: `kiki` -> `192.168.1.216`
+
+It means that `jlgdc01` and `kiki` means the same machine: the reverse-proxy-host.
+
+You need to configure IIS as a reverse proxy via *IIS Manager*:
+- look at this [microsoft documentation](https://docs.microsoft.com/fr-fr/archive/blogs/friis/setup-iis-with-url-rewrite-as-a-reverse-proxy-for-real-world-apps)
+- install `URL Rewrite`
+- add a reverse proxy rule to redirect `http://kiki` to `http://musette:3000`.
+
+It is better to use *Kerberos*, so you need to add a *Service Principal Name* to the `[email protected]` user. Open `Active Directory Users and Computers`:
+- make sure you have the *Advanced Features* view.
+- open the `[email protected]` user.
+- open the *Attribute Editor* tab. and edit the *Service Principal Name*:
+  - add `HTTP/kiki` and `HTTP/kiki.jlg.local` SPN.
+
+## Testing from client-host
+
+Login to the Window machine as `[email protected]`.
+
+Both below commands should work:
+
+```cmd
+start chrome http://kiki.jlg.local
+```
+
+```cmd
+start chrome http://kiki
+```
+
+You should see something like this:
+```cmd
+{
+  "method": "Kerberos",
+  "displayName": "marcel"
+}
+```
+
+If Kerberos is not well configured, then the browser will try to connect using *NTLM*. In this case, you will probably have a dialog box asking for credentials, which is bad user experience...
+
+
+## Author
+
+Jean-Louis GUENEGO <[email protected]>