example: provide separate examples for express, koa, standalone

Author: panva

README.md

@@ -76,14 +76,15 @@ of the OpenID Connect™ protocol.
 
 
 ## Get started
-You may follow an example [step by step setup][example-repo] (recommended), or run and experiment with an
-example server that's part of the repo (if you can follow the structure, if not check the step by step).
+You may check the [example folder](/example) or follow a [step by step example][example-repo] to see
+which of those fits your desired application setup.
 
-The example bundled in this repo's codebase is available for you to experiment with [here][heroku-example].
-Dynamic Registration is open, you can literally register any
-client you want there.  
-An example client using this provider is available [here][heroku-example-client]
-(uses [openid-client][openid-client]).
+The examples bundled in this repo's codebase are available for you to experiment with
+[here][heroku-example]. Dynamic Registration is open, you can literally register any client you want
+there.   An example client using this provider is available [here][heroku-example-client] (uses
+[openid-client][openid-client]).
+
+Also be sure to check the available configuration docs section.
 
 
 ## Configuration and Initialization
@@ -104,13 +105,21 @@ const clients = [{
 
 const oidc = new Provider('http://localhost:3000', configuration);
 
+let server;
 (async () => {
   await oidc.initialize({ clients });
-  // oidc.callback => express/nodejs style application callback (req, res)
-  // oidc.app => koa2.x application
-  oidc.listen(3000);
-  console.log('oidc-provider listening on port 3000, check http://localhost:3000/.well-known/openid-configuration');
+  // express/nodejs style application callback (req, res, next) for use with express apps, see ./examples/express.js
+  oidc.callback
+
+  // koa application for use with koa apps, see ./examples/koa.js
+  oidc.app
+
+  // or just expose a server standalone, see ./examples/standalone.js
+  server = oidc.listen(3000, () => {
+    console.log('oidc-provider listening on port 3000, check http://localhost:3000/.well-known/openid-configuration');
+  });
 })().catch((err) => {
+  if (server && server.listening) server.close();
   console.error(err);
   process.exitCode = 1;
 });

example/README.md

@@ -0,0 +1,19 @@
+# Examples
+
+See the following examples
+
+- [Koa](/example/koa.js)
+  - the provider is a part of your Koa application
+- [Express](/example/express.js)
+  - the provider is a part of your express application
+- [Standalone](/example/standalone.js)
+  - the provider is completely standalone
+
+Further resources
+
+- [Configuration](/docs/configuration.md)
+- [Mounting to a path](/docs/configuration.md#mounting-oidc-provider)
+
+Useful to know oidc-provider dependencies
+- [Koa](https://koajs.com/) - web framework oidc-provider uses internally
+- [node-jose](https://github.com/cisco/node-jose) - everything JOSE

example/express.js

@@ -1,17 +1,72 @@
-// You should read the Koa corresponding example (index.js in this directory) to
-// learn about many possible options.
+/* eslint-disable no-console */
 
-const express = require('express'); // eslint-disable-line import/no-unresolved
+const path = require('path');
+const url = require('url');
 
-const Provider = require('../lib');
+const { set } = require('lodash');
+const express = require('express');
+const helmet = require('helmet');
+
+const Provider = require('../lib'); // require('oidc-provider');
+
+const Account = require('./support/account');
+const { provider: providerConfiguration, clients, keys } = require('./support/configuration');
+const { express: routes } = require('./routes');
+
+const { PORT = 3000, ISSUER = `http://localhost:${PORT}`, TIMEOUT } = process.env;
+providerConfiguration.findById = Account.findById;
 
 const app = express();
+app.use(helmet());
 
-const provider = new Provider('http://localhost:3000/op', {
-  formats: { default: 'opaque' },
-});
+app.set('views', path.join(__dirname, 'views'));
+app.set('view engine', 'ejs');
+
+const provider = new Provider(ISSUER, providerConfiguration);
+
+if (TIMEOUT) {
+  provider.defaultHttpOptions = { timeout: TIMEOUT };
+}
+
+let server;
+(async () => {
+  await provider.initialize({
+    adapter: process.env.MONGODB_URI ? require('./support/heroku_mongo_adapter') : undefined, // eslint-disable-line global-require
+    clients,
+    keystore: { keys },
+  });
+
+  if (process.env.NODE_ENV === 'production') {
+    app.enable('trust proxy');
+    provider.proxy = true;
+    set(providerConfiguration, 'cookies.short.secure', true);
+    set(providerConfiguration, 'cookies.long.secure', true);
+
+    app.use((req, res, next) => {
+      if (req.secure) {
+        next();
+      } else if (req.method === 'GET' || req.method === 'HEAD') {
+        res.redirect(url.format({
+          protocol: 'https',
+          host: req.get('host'),
+          pathname: req.originalUrl,
+        }));
+      } else {
+        res.status(400).json({
+          error: 'invalid_request',
+          error_description: 'do yourself a favor and only use https',
+        });
+      }
+    });
+  }
 
-provider.initialize().then(() => {
-  app.use('/op', provider.callback);
-  app.listen(3000);
+  routes(app, provider);
+  app.use(provider.callback);
+  server = app.listen(PORT, () => {
+    console.log(`application is listening on port ${PORT}, check it's /.well-known/openid-configuration`);
+  });
+})().catch((err) => {
+  if (server && server.listening) server.close();
+  console.error(err);
+  process.exitCode = 1;
 });

example/koa.js

@@ -0,0 +1,71 @@
+/* eslint-disable no-console */
+
+const path = require('path');
+
+const { set } = require('lodash');
+const Koa = require('koa');
+const render = require('koa-ejs');
+const helmet = require('koa-helmet');
+const mount = require('koa-mount');
+
+const Provider = require('../lib'); // require('oidc-provider');
+
+const Account = require('./support/account');
+const { provider: providerConfiguration, clients, keys } = require('./support/configuration');
+const { koa: routes } = require('./routes');
+
+const { PORT = 3000, ISSUER = `http://localhost:${PORT}`, TIMEOUT } = process.env;
+providerConfiguration.findById = Account.findById;
+
+const app = new Koa();
+app.use(helmet());
+render(app, {
+  cache: false,
+  viewExt: 'ejs',
+  layout: '_layout',
+  root: path.join(__dirname, 'views'),
+});
+
+if (process.env.NODE_ENV === 'production') {
+  app.keys = providerConfiguration.cookies.keys;
+  app.proxy = true;
+  set(providerConfiguration, 'cookies.short.secure', true);
+  set(providerConfiguration, 'cookies.long.secure', true);
+
+  app.use(async (ctx, next) => {
+    if (ctx.secure) {
+      await next();
+    } else if (ctx.method === 'GET' || ctx.method === 'HEAD') {
+      ctx.redirect(ctx.href.replace(/^http:\/\//i, 'https://'));
+    } else {
+      ctx.body = {
+        error: 'invalid_request',
+        error_description: 'do yourself a favor and only use https',
+      };
+      ctx.status = 400;
+    }
+  });
+}
+
+const provider = new Provider(ISSUER, providerConfiguration);
+if (TIMEOUT) {
+  provider.defaultHttpOptions = { timeout: TIMEOUT };
+}
+
+let server;
+(async () => {
+  await provider.initialize({
+    adapter: process.env.MONGODB_URI ? require('./support/heroku_mongo_adapter') : undefined, // eslint-disable-line global-require
+    clients,
+    keystore: { keys },
+  });
+  app.use(routes(provider).routes());
+  app.use(mount(provider.app));
+  server = app.listen(PORT, () => {
+    console.log(`application is listening on port ${PORT}, check it's /.well-known/openid-configuration`);
+  });
+})().catch((err) => {
+  if (server && server.listening) server.close();
+  console.error(err);
+  process.exitCode = 1;
+});

example/routes/express.js

@@ -0,0 +1,97 @@
+const querystring = require('querystring');
+
+const { urlencoded } = require('express');
+
+const Account = require('../support/account');
+
+const body = urlencoded({ extended: false });
+
+module.exports = (app, provider) => {
+  const { constructor: { errors: { SessionNotFound } } } = provider;
+
+  app.use((req, res, next) => {
+    const orig = res.render;
+    // you'll probably want to use a full blown render engine capable of layouts
+    res.render = (view, locals) => {
+      app.render(view, locals, (err, html) => {
+        if (err) throw err;
+        orig.call(res, '_layout', {
+          ...locals,
+          body: html,
+        });
+      });
+    };
+    next();
+  });
+
+  app.get('/interaction/:grant', async (req, res, next) => {
+    try {
+      const details = await provider.interactionDetails(req);
+      const client = await provider.Client.find(details.params.client_id);
+
+      if (details.interaction.error === 'login_required') {
+        return res.render('login', {
+          client,
+          details,
+          title: 'Sign-in',
+          params: querystring.stringify(details.params, ',<br/>', ' = ', {
+            encodeURIComponent: value => value,
+          }),
+          interaction: querystring.stringify(details.interaction, ',<br/>', ' = ', {
+            encodeURIComponent: value => value,
+          }),
+        });
+      }
+      return res.render('interaction', {
+        client,
+        details,
+        title: 'Authorize',
+        params: querystring.stringify(details.params, ',<br/>', ' = ', {
+          encodeURIComponent: value => value,
+        }),
+        interaction: querystring.stringify(details.interaction, ',<br/>', ' = ', {
+          encodeURIComponent: value => value,
+        }),
+      });
+    } catch (err) {
+      return next(err);
+    }
+  });
+
+  app.post('/interaction/:grant/confirm', body, async (req, res, next) => {
+    try {
+      const result = { consent: {} };
+      await provider.interactionFinished(req, res, result);
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  app.post('/interaction/:grant/login', body, async (req, res, next) => {
+    try {
+      const account = await Account.findByLogin(req.body.login);
+
+      const result = {
+        login: {
+          account: account.accountId,
+          acr: 'urn:mace:incommon:iap:bronze',
+          amr: ['pwd'],
+          remember: !!req.body.remember,
+          ts: Math.floor(Date.now() / 1000),
+        },
+        consent: {},
+      };
+
+      await provider.interactionFinished(req, res, result);
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  app.use((err, req, res, next) => {
+    if (err instanceof SessionNotFound) {
+      // handle interaction expired / session not found error
+    }
+    next(err);
+  });
+};

example/routes/index.js

@@ -0,0 +1,2 @@
+module.exports.koa = require('./koa');
+module.exports.express = require('./express');