docs: [oidc-middleware]: Update README (#301)

packages/oidc-middleware/README.md

@@ -1,49 +1,55 @@
-# oidc-middleware
+[<img src="https://devforum.okta.com/uploads/oktadev/original/1X/bf54a16b5fda189e4ad2706fb57cbb7a1e5b8deb.png" align="right" width="256px"/>](https://devforum.okta.com/)
 
+[![Support](https://img.shields.io/badge/support-developer%20forum-blue.svg)][devforum]
 [![npm version](https://img.shields.io/npm/v/@okta/oidc-middleware.svg?style=flat-square)](https://www.npmjs.com/package/@okta/oidc-middleware)
 [![build status](https://img.shields.io/travis/okta/okta-oidc-js/master.svg?style=flat-square)](https://travis-ci.org/okta/okta-oidc-js)
 
+# Okta NodeJS OIDC Middleware
+
+* [Release status](#release-status)
+* [Need help?](#need-help)
+* [Getting started](#getting-started)
+* [Usage guide](#usage-guide)
+* [API reference](#api-reference)
+* [Contributing](#contributing)
+
 This package makes it easy to get your users logged in with Okta using OpenId Connect (OIDC).  It enables your Express application to participate in the [authorization code flow][auth-code-docs] flow by redirecting the user to Okta for authentication and handling the callback from Okta.  Once this flow is complete, a local session is created and the user context is saved for the duration of the session.
 
-## :warning: :construction: Alpha Preview :construction: :warning:
+## Release status
+
+This library uses semantic versioning and follows Okta's [library version policy](https://developer.okta.com/code/library-versions/).
+
+:heavy_check_mark: The current stable major version series is: 1.x
+
+| Version | Status                    |
+| ------- | ------------------------- |
+| 1.x     | :heavy_check_mark: Stable |
+| 0.x     | :x: Retired               |
 
-This library is under development and is currently in 0.x version series.  Breaking changes may be introduced at minor versions in the 0.x range.  Please lock your dependency to a specific version until this library reaches 1.x.
+The latest release can always be found on the [releases page][github-releases].
 
-Need help? Contact [[email protected]](mailto:[email protected]) or use the [Okta Developer Forum].
+## Need help?
 
-## Table of Contents
+If you run into problems using the SDK, you can:
 
-- [Installation](#installation)
-- [Prerequisites](#prerequisites)
-- [Usage Example](#usage-example)
-- [ExpressOIDC API](#expressoidc-api)
-  - [new ExpressOIDC(config)](#new-expressoidcconfig)
-  - [oidc.router](#oidcrouter)
-  - [oidc.on('ready', callback)](#oidconready-callback)
-  - [oidc.on('error', callback)](#oidconerror-callback)
-  - [oidc.ensureAuthenticated({ redirectTo?: '/uri' })](#oidcensureauthenticated-redirectto-uri)
-  - [req.isAuthenticated()](#reqisauthenticated)
-  - [req.logout()](#reqlogout)
-  - [req.userContext](#requsercontext)
-- [Customization](#customization)
-  - [Customizing Routes](#customizing-routes)
-  - [Using a Custom Login Page](#using-a-custom-login-page)
-  - [Extending the User](#extending-the-user)
-  - [Using Proxy Servers](#using-proxy-servers)
+* Ask questions on the [Okta Developer Forums][devforum]
+* Post [issues][github-issues] here on GitHub (for code errors)
 
-## Installation
+## Getting started
+
+Installing the Okta Node JS OIDC MIddlware in your project is simple.
 
 ```sh
 npm install --save @okta/oidc-middleware
 ```
 
-## Prerequisites
+You'll also need:
 
-* You will need an Okta Developer Org, you can sign up for an account at <https://developer.okta.com/signup/>.
+* An Okta account, called an _organization_ (sign up for a free [developer organization](https://developer.okta.com/signup) if you need one).
 * An OIDC application in your Org, configured for Web mode.  If you are new to Okta or this flow, we suggest following the [Express.js Quickstart][express-quickstart].
 * This integration depends on sessions to store user information. Ensure the [express-session middleware](https://github.com/expressjs/session) is added before you add `ExpressOIDC`.  By default, the session middleware uses a MemoryStore, which is not designed for production use. Use [another session store](https://github.com/expressjs/session#compatible-session-stores) for production.
 
-## Usage Example
+## Usage guide
 
 Below is a terse Express application that examples the basic usage of this library.  If you'd like to clone a complete example, please see the [Okta Express Samples Repository](https://github.com/okta/samples-nodejs-express-4).
 
@@ -89,9 +95,26 @@ oidc.on('error', err => {
 });
 ```
 
-## ExpressOIDC API
+## API reference
+
+* [ExpressOIDC API](#expressoidc-api)
+  * [new ExpressOIDC(config)](#new-expressoidcconfig)
+  * [oidc.router](#oidcrouter)
+  * [oidc.on('ready', callback)](#oidconready-callback)
+  * [oidc.on('error', callback)](#oidconerror-callback)
+  * [oidc.ensureAuthenticated({ redirectTo?: '/uri' })](#oidcensureauthenticated-redirectto-uri)
+  * [req.isAuthenticated()](#reqisauthenticated)
+  * [req.logout()](#reqlogout)
+  * [req.userContext](#requsercontext)
+* [Customization](#customization)
+  * [Customizing Routes](#customizing-routes)
+  * [Using a Custom Login Page](#using-a-custom-login-page)
+  * [Extending the User](#extending-the-user)
+  * [Using Proxy Servers](#using-proxy-servers)
+
+### ExpressOIDC API
 
-### new ExpressOIDC(config)
+#### new ExpressOIDC(config)
 
 To configure your OIDC integration, create an instance of `ExpressOIDC` and pass options. Most apps will need this basic configuration:
 
@@ -122,7 +145,7 @@ Optional config:
 * **maxClockSkew** - Defaults to 120. This is the maximum difference allowed between your server's clock and Okta's in seconds. Setting this to 0 is not recommended, because it increases the likelihood that valid jwts will fail verification due to `nbf` and `exp` issues.
 * **timeout** - Defaults to 10000 milliseconds. The HTTP max timeout for any requests to the issuer.  If a timeout exception occurs you can catch it with the `oidc.on('error', fn)` handler.
 
-### oidc.router
+#### oidc.router
 
 This should be added to your express app to attach the login and callback routes:
 
@@ -141,7 +164,7 @@ It's required in order for `ensureAuthenticated` and `isAuthenticated` to work a
 * `/login` - redirects to the Okta sign-in page by default
 * `/authorization-code/callback` - processes the OIDC response, then attaches userinfo to the session
 
-### oidc.on('ready', callback)
+#### oidc.on('ready', callback)
 
 The middleware must retrieve some information about your client before starting the server. You **must** wait until ExpressOIDC is ready to start your server.
 
@@ -151,7 +174,7 @@ oidc.on('ready', () => {
 });
 ```
 
-### oidc.on('error', callback)
+#### oidc.on('error', callback)
 
 This is triggered if an error occurs while ExpressOIDC is trying to start.
 
@@ -161,7 +184,7 @@ oidc.on('error', err => {
 });
 ```
 
-### oidc.ensureAuthenticated({ redirectTo?: '/uri' })
+#### oidc.ensureAuthenticated({ redirectTo?: '/uri' })
 
 Use this to protect your routes. If not authenticated, this will redirect to the login route and trigger the authentication flow. If the request prefers JSON then a 401 error response will be sent.
 
@@ -173,7 +196,7 @@ app.get('/protected', oidc.ensureAuthenticated(), (req, res) => {
 
 The `redirectTo` option can be used to redirect the user to a specific URI on your site, after a successful authentication callback.
 
-### req.isAuthenticated()
+#### req.isAuthenticated()
 
 This allows you to determine if a user is authenticated.
 
@@ -187,7 +210,7 @@ app.get('/', (req, res) => {
 });
 ```
 
-### req.logout()
+#### req.logout()
 
 This allows you to end the session.
 
@@ -198,7 +221,7 @@ app.get('/logout', (req, res) => {
 });
 ```
 
-### req.userContext
+#### req.userContext
 
 This provides information about the authenticated user and contains the requested tokens. The `userContext` object contains two keys:
 
@@ -225,9 +248,9 @@ app.get('/', (req, res) => {
 });
 ```
 
-## Customization
+### Customization
 
-### Customizing Routes
+#### Customizing Routes
 
 If you need to modify the default login and callback routes, the `routes` config option is available.
 
@@ -255,7 +278,7 @@ const oidc = new ExpressOIDC({
 * **`callback.path`** - The URI that this library will host the callback handler on. Defaults to `/authorization-code/callback`
 * **`login.path`** - The URI that redirects the user to the authorize endpoint. Defaults to `/login`.
 
-### Using a Custom Login Page
+#### Using a Custom Login Page
 
 By default the end-user will be redirected to the Okta Sign-In Page when authentication is required, this page is hosted on your Okta Org domain.  It is possible to host this experience within your own application by installing the [Okta Sign-In Widget](https://github.com/okta/okta-signin-widget) into a page in your application.  Please refer to the [test example file](test/e2e/harness/views/login.ejs) for an example of how the widget should be configured for this use case.
 
@@ -280,7 +303,7 @@ const oidc = new ExpressOIDC({
 });
 ```
 
-### Extending the User
+#### Extending the User
 
 To add additional data about a user from your database, we recommend adding middleware to extend `req`.
 
@@ -319,7 +342,7 @@ oidc.on('error', err => console.log('could not start', err));
 [express-quickstart]: https://developer.okta.com/quickstart/#/okta-sign-in-page/nodejs/express
 [Okta Developer Forum]: https://devforum.okta.com/
 
-### Using Proxy Servers
+#### Using Proxy Servers
 
 The underlying [openid-client][] library can be configured to use the [request][] library.  Do this by adding these lines to your app, before you call `new ExpressOIDC()`:
 
@@ -335,5 +358,10 @@ const oidc = new ExpressOIDC({
 
 Once you have done that you can read the documentation on the [request][] library to learn which environment variables can be used to define your proxy settings.
 
+[devforum]: https://devforum.okta.com/
 [openid-client]: https://github.com/panva/node-openid-client
 [request]: https://github.com/request/request
+
+## Contributing
+
+We're happy to accept contributions and PRs! Please see the [contribution guide](https://github.com/okta/okta-oidc-js/blob/master/CONTRIBUTING.md) to understand how to structure a contribution.