feat: new endpoints and bundle OIDC simulation environment

chore: agenda and getting started for README.md

fix: typo

fix: link for README.md

fix: signout and sample API for README.md

fix: comment for post logout and gitignore

fix: space to horizontally aligh variables of key/value

fix: README.md

fix: image of make watch

chore: add a node when Keycloak container isn't working

feat: advanced example of proxy server

chore: fix typo and add a note for two examples for reverse proxy configuration

Author: shawndotkim

.gitignore

@@ -0,0 +1,8 @@
+*.crt
+*.key
+*.jwt
+refresh_tokens.json
+oidc*.json
+oidc_credentials.conf
+.DS_Store
+docker/build-context/data

Makefile

@@ -0,0 +1,21 @@
+.PHONY: start ps watch down stop clean
+
+start:
+	docker-compose up -d
+
+ps:
+	docker ps --format "table {{.ID}}\t{{.Image}}\t{{.Ports}}\t{{.Names}}"
+
+watch:
+	watch 'docker ps --format "table {{.ID}}\t{{.Image}}\t{{.Ports}}\t{{.Names}}"'
+
+down:
+	docker-compose down
+
+stop:
+	docker-compose down
+
+clean: 
+	docker kill $$(docker ps -q) 2> /dev/null || true
+	docker system prune -a
+	docker volume rm $(docker volume ls -qf dangling=true)

README.md

@@ -2,6 +2,23 @@
 
 Reference implementation of NGINX Plus as relying party for OpenID Connect authentication
 
+- [Description](#description)
+  - [Refresh Tokens](#refresh-tokens)
+  - [User Information & Login](#user-information--login)
+  - [Logout](#logout)
+  - [Multiple IdPs](#multiple-idps)
+- [Getting Started](#🏠-getting-started)
+  - [Step 1. Quick Starting Guide](#step-1-quick-starting-guide)
+  - [Step 2. Detailed Starting Guide](#step-2-detailed-starting-guide)
+- [Installation](#installation)
+- [Configuring your IdP](#configuring-your-idp)
+- [Configuring NGINX Plus](#configuring-nginx-plus)
+- [Session Management](#session-management)
+- [Real time monitoring](#real-time-monitoring)
+- [Troubleshooting](#troubleshooting)
+- [Support](#support)
+- [Changelog](#changelog)
+
 ## Description
 
 This repository describes how to enable OpenID Connect integration for [NGINX Plus](https://www.nginx.com/products/nginx/). The solution depends on NGINX Plus components ([auth_jwt module](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html) and [key-value store](http://nginx.org/en/docs/http/ngx_http_keyval_module.html)) and as such is not suitable for [open source NGINX](http://www.nginx.org/en).
@@ -32,18 +49,45 @@ For more information on OpenID Connect and JWT validation with NGINX Plus, see [
 
 ### Refresh Tokens
 
-If a [refresh token](https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens) was received from the IdP then it is also stored in the key-value store. When validation of the ID Token fails (typically upon expiry) then NGINX Plus sends the refresh token to the IdP. If the user's session is still valid at the IdP then a new ID token is received, validated, and updated in the key-value store. The refresh process is seamless to the client.
+If a [refresh token](https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens) was received from the IdP then it is also stored in the key-value store. When validation of the ID Token fails (typically upon expiry) then NGINX Plus sends the refresh token to the IdP. If the user's session is still valid at the IdP then new ID token and access token are received, validated, and updated in the key-value store. The refresh process is seamless to the client. The ID token is used for user authentication with login and logout, and the access is used for API authorization before proxing to IdP endpoint such as `/userinfo` or custom backend APIs.
+
+### User Information & Login
+
+The `/userinfo` endpoint is used for the following purposes by validating access token via your IdP(s):
+
+- When connecting a frontend app for the first time, the landing page can be shown with `Login` button without user information.
+- The frontend app periodically calls the `/userinfo` endpoint, and it returns the status code of `401` as the access token is invalid before clicking `Login` button.
+- When an End-User clicks `Login` button, the frontend app calls `/login` endpoint, and the ID token, access token, and refresh token are issued by the IdP and stored in the key-value store of NGINX Plus.
+- NGINX Plus successfully redirects to the frontend landing page with session cookie after successful login.
+- In the meantime, the user information is shown in the frontend app as the `userinfo` endpoint returns the user data with the status code of `200` by validating access token with the IdP.
 
 ### Logout
 
 Requests made to the `/logout` location invalidate both the ID token and refresh token by erasing them from the key-value store. Therefore, subsequent requests to protected resources will be treated as a first-time request and send the client to the IdP for authentication. Note that the IdP may issue cookies such that an authenticated session still exists at the IdP.
 
+To avoid breaking changes of API endpoints to customers, the `/v2/logout` location is added to interact with the IdP's `end_session_endpoint` which is to handle [OIDC RP-Initiated Logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout) as the spec of OpenID Connect. The `$post_logout_return_uri` is the URI to which the RP is requesting that the End-User's User Agent be redirected after a logout has been performed. When setting up an IdP, `/v1/_logout` is used in this example, and you can change it per your preference.
+
 ### Multiple IdPs
 
 Where NGINX Plus is configured to proxy requests for multiple websites or applications, or user groups, these may require authentication by different IdPs. Separate IdPs can be configured, with each one matching on an attribute of the HTTP request, e.g. hostname or part of the URI path.
 
 > **Note:** When validating OpenID Connect tokens, NGINX Plus can be configured to read the signing key (JWKS) from disk, or a URL. When using multiple IdPs, each one must be configured to use the same method. It is not possible to use a mix of both disk and URLs for the `map…$oidc_jwt_keyfile` variable.
 
+## 🏠 Getting Started
+
+Start by following [step 1](#step-1-quick-starting-guide) if you want to quickly learn and test NGINX Plus OIDC locally. Otherwise skip step 1, and follow the [step 2](#step-2-detailed-starting-guide).
+
+### Step 1. Quick Starting Guide
+
+- 📚 [**How To Set Up and Locally Test NGINX Plus OIDC**](./docs/01-oidc-local-test.md)
+
+### Step 2. Detailed Starting Guide
+
+- [Installation](#installation)
+- [Configuring your IdP](#configuring-your-idp)
+- [Configuring NGINX Plus](#configuring-nginx-plus)
+- [Real time monitoring](#real-time-monitoring)
+
 ## Installation
 
 Start by [installing NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). In addition, the [NGINX JavaScript module](https://www.nginx.com/blog/introduction-nginscript/) (njs) is required for handling the interaction between NGINX Plus and the OpenID Connect provider (IdP). Install the njs module after installing NGINX Plus by running one of the following:
@@ -100,6 +144,8 @@ When NGINX Plus is deployed behind another proxy, the original protocol and port
   - Obtain the URL for `jwks_uri` or download the JWK file to your NGINX Plus instance
   - Obtain the URL for the **authorization endpoint**
   - Obtain the URL for the **token endpoint**
+  - Obtain the URL for the **end session endpoint**
+  - Obtain the URL for the **user info endpoint**
 
 ## Configuring NGINX Plus
 
@@ -110,7 +156,8 @@ Manual configuration involves reviewing the following files so that they match y
 - **openid_connect_configuration.conf** - this contains the primary configuration for one or more IdPs in `map{}` blocks
 
   - Modify all of the `map…$oidc_` blocks to match your IdP configuration
-  - Modify the URI defined in `map…$oidc_logout_redirect` to specify an unprotected resource to be displayed after requesting the `/logout` location
+  - Modify the URI defined in `map…$oidc_logout_redirect` to specify an unprotected resource to be displayed after requesting the `/logout` location for customers who has been using R28.
+  - Modify the URI defined in `map…$oidc_logout_redirect_uri` to specify an unprotected resource to be displayed after requesting the `/v2/_logout` location for customers who start using R29 and wants to change from `map…$oidc_logout_redirect` to `map…$oidc_logout_redirect_uri` to use the feature of `OIDC RP-Initiated Logout` which is interact with IdP's `end_session_endpoint`.
   - Set a unique value for `$oidc_hmac_key` to ensure nonce values are unpredictable
   - If NGINX Plus is deployed behind another proxy or load balancer, modify the `map…$redirect_base` and `map…$proto` blocks to define how to obtain the original protocol and port number.
 
@@ -121,6 +168,19 @@ Manual configuration involves reviewing the following files so that they match y
   - Modify the severity level of the `error_log` directive to suit the deployment environment
   - Comment/uncomment the `auth_jwt_key_file` or `auth_jwt_key_request` directives based on whether `$oidc_jwt_keyfile` is a file or URI, respectively
 
+  > Note: Two configuration examples are provided as follows.
+  >
+  > - 1. Basic Example. Landing page starts OIDC flow without a login button
+  >
+  > - 2. Advanced Example. Landing page, login/logout button to start/finish OIDC workflow
+  >   - Landing page with `login` button
+  >   - `login` button to start OIDC flow by validating `id token` with the JWK of IdP.
+  >   - Landing page calls the `/userinfo` endpoint to show user information by validating `access token` with the JWK of IdP.
+  >   - `logout` button to close the OIDC session among frontend, NGINX Plus, and IdP.
+  >   - The proxied API authorization by validating `access token` with the JWK of IdP.
+  >     - Use `access token` for most of IdPs such as Amazon Cognito, Auth0, Keycloak, Okta, OneLogin and Ping Identity.
+  >     - Use `session_jwt` for Azure AD as for now.
+
 - **openid_connect.server_conf** - this is the NGINX configuration for handling the various stages of OpenID Connect authorization code flow
 
   - No changes are usually required here

docker-compose.yml

@@ -0,0 +1,69 @@
+version: '3.4'
+
+networks:
+  mynetwork:
+    name: mynetwork
+    attachable: true
+
+services:
+
+  postgres:
+    container_name: idp-keycloak-db
+    image: postgres:12.0
+    # volumes:
+    #   - type: bind
+    #     source: ./docker/build-context/data
+    #     target: /var/lib/postgresql/data
+    environment:
+      POSTGRES_DB: keycloak
+      POSTGRES_USER: keycloak
+      POSTGRES_PASSWORD: password
+    ports:
+      - 5432:5432
+    networks:
+      - mynetwork
+
+  keycloak:
+    container_name: idp-keycloak
+    image: jboss/keycloak:15.1.0
+    environment:
+      DB_VENDOR: POSTGRES
+      DB_ADDR: postgres
+      DB_DATABASE: keycloak
+      DB_USER: keycloak
+      DB_SCHEMA: public
+      DB_PASSWORD: password
+      KEYCLOAK_USER: admin
+      KEYCLOAK_PASSWORD: password
+      # Uncomment the line below if you want to specify JDBC parameters. The parameter below is just an example, and it shouldn't be used in production without knowledge. It is highly recommended that you read the PostgreSQL JDBC driver documentation in order to use it.
+      #JDBC_PARAMS: "ssl=true"
+    ports:
+      - 8080:8080
+    depends_on:
+      - postgres
+    networks:
+      - mynetwork
+
+  nginxplus_oidc_keycloak_ubuntu18.04:
+    container_name: nginxplus-oidc-keycloak
+    build:
+      context: ./
+      dockerfile: ./docker/docker-files/nginxplus-ubuntu18.04/Dockerfile
+    image: nginxplus_oidc_keycloak_ubuntu18.04
+    ports:
+      - 8010:8010 # Frontend/backend example v1: landing page w/ OIDC flow w/o login button
+      - 8020:8020 # Frontend/backend example v2: landing page w/ login button, login button w/ OIDC flow, logout button, /userinfo, access token based API authorization
+    volumes:
+      - type: bind
+        source: ./
+        target: /etc/nginx/conf.d/
+      - type: bind
+        source: ./docker/build-context/nginx/sample/
+        target: /etc/nginx/sample/
+      - type: bind
+        source: ./docker/build-context/content
+        target: /usr/share/nginx/html/
+    depends_on:
+      - keycloak
+    networks:
+      - mynetwork

docker/build-context/content/50x.html

@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html>
+<head>
+<title>Error</title>
+<style>
+    body {
+        width: 35em;
+        margin: 0 auto;
+        font-family: Tahoma, Verdana, Arial, sans-serif;
+    }
+</style>
+</head>
+<body>
+<h1>An error occurred.</h1>
+<p>Sorry, the page you are looking for is currently unavailable.<br/>
+Please try again later.</p>
+<p>If you are the system administrator of this resource then you should check
+the error log for details.</p>
+<p><em>Faithfully yours, nginx.</em></p>
+</body>
+</html>