Merge pull request #35 from abstractj/KEYCLOAK-2833

[KEYCLOAK-2833] Migrate the Node.js documentation to the official repositories

SUMMARY.adoc

@@ -36,6 +36,8 @@
 
    .. link:topics/oidc/javascript-adapter.adoc[JavaScript Adapter]
 
+   .. link:topics/oidc/nodejs-adapter.adoc[Node.js Adapter]
+
    .. link:topics/oidc/oidc-generic.adoc[Other OpenID Connect libraries]
       {% if book.community %}
       ... link:topics/oidc/mod-auth-openidc.adoc[mod_auth_oidc Apache HTTPD Module]

topics/oidc/nodejs-adapter.adoc

@@ -0,0 +1,134 @@
+[[_nodejs_adapter]]
+=== Node.js Adapter
+
+{{book.project.name}} provides a Node.js adapter built on top of https://github.com/senchalabs/connect[Connect] to protect server side JavaScript apps — the goal was to be flexible enough to integrate with frameworks like https://expressjs.com/[Express.js].
+
+The library can be downloaded directly from https://www.npmjs.com/package/keycloak-connect[ {{book.project.name}} organization] and the source is available at
+https://github.com/keycloak/keycloak-nodejs-connect[GitHub].
+
+To use the Node.js adapter you must first create a client for your application in the {{book.project.name}} Administration Console. The adapter supports public, confidential and bearer-only access type. Which one to choose depends on the use-case scenario.
+
+Once the client is created click on the `Installation` tab select `{{book.project.name}} OIDC JSON` for `Format Option` then click on `Download`. The downloaded `keycloak.json` file should be at the root folder. Exactly, like in https://github.com/keycloak/keycloak-nodejs-connect/tree/master/example[this example].
+
+keycloak.json::
+
+Alongside the `example.js` lives `keycloak.json` obtained from our {{book.project.name}}
+admin console when we provisioned this app.
+
+
+    {
+      "realm": "example-realm",
+      "realm-public-key": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCrVrCuTtArbgaZzL1hvh0xtL5mc7o0NqPVnYXkLvgcwiC3BjLGw1tGEGoJaXDuSaRllobm53JBhjx33UNv+5z/UMG4kytBWxheNVKnL6GgqlNabMaFfPLPCF8kAgKnsi79NMo+n6KnSY8YeUmec/p2vjO2NjsSAVcWEQMVhJ31LwIDAQAB",
+      "auth-server-url": "http://localhost:8080/auth",
+      "ssl-required": "external",
+      "resource": "example-app",
+      "credentials": {
+        "secret": "mysecret"
+      }
+    }
+
+==== Installation
+
+Assuming you've already installed https://nodejs.org[Node.js], create a folder for your application:
+
+    mkdir myapp && cd myapp
+
+Use `npm init` command to create a `package.json` for your application. And now install the {{book.project.name}} connect adapter in the `myapp` folder, saving it in the dependencies list:
+
+    npm install --save keycloak-connect
+
+==== Usage
+Instantiate a Keycloak class::
+
+The `Keycloak` class provides a central point for configuration
+and integration with your application.  The simplest creation
+involves no arguments.
+
+    var keycloak = new Keycloak();
+
+By default, this will locate a file named `keycloak.json` alongside
+the main executable of your application to initialize keycloak-specific
+settings (public key, realm name, various URLs).  The `keycloak.json` file
+is obtained from the {{book.project.name}} Admin Console.
+
+Instantiation with this method results in all of the reasonable defaults
+being used.
+
+Configuring a web session store::
+
+If you wish to use web sessions to manage
+server-side state for authentication, you will need to initialize the
+`Keycloak(...)` with at least a `store` parameter, passing in the actual
+session store that `express-session` is using.
+
+    var session = require('express-session');
+    var memoryStore = new session.MemoryStore();
+
+    var keycloak = new Keycloak({ store: memoryStore });
+
+Passing a custom scope value::
+
+By default, the scope value `openid` will be passed as query parameter to {{book.project.name}}'s login URL but you can add an additional custom value :
+
+    var keycloak = new Keycloak({ scope: 'offline_access' });
+
+==== Install middleware
+
+Once instantiated, install the middleware into your connect-capable app:
+
+    var app = express();
+
+    app.use( keycloak.middleware() );
+
+==== Protect resources
+
+Simple authentication::
+
+To enforce that an user must be authenticated before accessing a resource,
+simply use a no-argument version of `keycloak.protect()`:
+
+    app.get( '/complain', keycloak.protect(), complaintHandler );
+
+Role-based authorization::
+
+To secure a resource with an application role for the current app:
+
+    app.get( '/special', keycloak.protect('special'), specialHandler );
+
+To secure a resource with an application role for a *different* app:
+
+    app.get( '/extra-special', keycloak.protect('other-app:special', extraSpecialHandler );
+
+To secure a resource with a realm role:
+
+    app.get( '/admin', keycloak.protect( 'realm:admin' ), adminHandler );
+
+Advanced authorization::
+
+To secure resources based on parts of the URL itself, assuming a role exists
+for each section:
+
+    function protectBySection(token, request) {
+      return token.hasRole( request.params.section );
+    }
+
+    app.get( '/:section/:page', keycloak.protect( protectBySection ), sectionHandler );
+
+==== Additional URLs
+
+Explicit user-triggered logout::
+
+By default, the middleware catches calls to `/logout` to send the user through a
+{{book.project.name}}-centric logout workflow. This can be changed by specifying a `logout`
+configuration parameter to the `middleware()` call:
+
+    app.use( keycloak.middleware( { logout: '/logoff' } ));
+
+{{book.project.name}} Admin Callbacks::
+
+Also, the middleware supports callbacks from the {{book.project.name}} console to logout a single
+session or all sessions.  By default, these type of admin callbacks occur relative
+to the root URL of `/` but can be changed by providing an `admin` parameter
+to the `middleware()` call:
+
+    app.use( keycloak.middleware( { admin: '/callbacks' } );

topics/overview/supported-platforms.adoc

@@ -21,6 +21,9 @@
 ===== JavaScript (client-side)
 * <<fake/../../oidc/javascript-adapter.adoc#_javascript_adapter,JavaScript>>
 
+===== Node.js (server-side)
+* <<fake/../../oidc/nodejs-adapter.adoc#_nodejs_adapter,Node.js>>
+
 ===== Apache Cordova
 * <<fake/../../oidc/javascript-adapter.adoc#_javascript_adapter,JavaScript>>