NGINX Plus R16

Author: lcrilly

README.md

@@ -89,10 +89,10 @@ Review the following files copied from the GitHub repository so that they match
 
 ## Support
 
-The reference OpenID Connect implementation at the root of the GitHub repository is supported for NGINX Plus subscribers.
+All reference OpenID Connect implementations within the GitHub repository are supported for NGINX Plus subscribers.
 
 ## Other use cases
 
-Subdirectories within the GitHub repository contain sample implementations for alternative OpenID Connect use cases. These are not supported.
+Subdirectories within the GitHub repository contain variations of the reference implementation for alternative OpenID Connect use cases.
 
-  * **opaque_session_token** - proof of concept implementation that sends a random string to the client rather than the JWT
+  * **opaque_session_token** - Uses the NGINX Plus key-value store to hold the ID Token, sending a random string to the client as the session token. The session token is then exchanged for the ID Token on each request. This use case is valuable when the ID Token contains sensitive information that should not reach the client.

opaque_session_token/README.md

@@ -1,23 +1,47 @@
 ## Opaque Session Token
 
-This is a proof of concept implementation of NGINX Plus as relying party for OpenID Connect authentication.
+This is a variation on the reference implementation of NGINX Plus as relying party for OpenID Connect authentication.
 
 ## Description
 
-This is a variation of the reference OpenID Connect implementation. It does not send a JWT to the client as a session cookie. The ID Token is stored in the NGINX Plus key-value store and a random value is sent as a session cookie.
+This use case varies from the top-level reference implementation at the step when the ID Token received from the IdP. Instead of sending the ID Token to the client as a session cookie, the ID Token is saved to the NGINX Plus [key-value store](http://nginx.org/en/docs/http/ngx_http_keyval_module.html). A random string is sent to the client as the session cookie and acts as the _key_ to the key-value store.
 
-When the client presents the session cookie, that value is used to obtain the ID Token from the key-value store. The ID Token is then validated with `auth_jwt` as usual before the client request is proxied to the backend.
+Subsequent requests to protected resources are authenticated by exchanging the session cookie for the ID Token in the key-value store. JWT validation is performed on each request, as normal, so that the ID Token validity period is enforced.
 
-This proof of concept implementation is not suitable for production use because expired tokens are not removed from the key-value store.
+## Installation
+
+OpenID Connect with Opaque Session Token requires NGINX Plus R16 or later to be installed. Installation is as per the instructions in the top-level of the GitHub repo, and using the files found in this directory.
+
+## Configuration
+
+Configuration is as per the instructions in the top-level of the GitHub repo. The key-value store may additionally be configured, within **frontend.conf**, e.g.:
+
+```nginx
+keyval_zone zone=sessions:1M state=state_sessions.json timeout=601m sync;
+```
+
+Each of the `keyval_zone` parameters are described below.
+
+  * **zone** - Specifies the name of the key-value store and how much memory to allocate for it. Each session will typically occupy 1-2KB, depending on the size of the JWT, so scale this value to exceed the number of unique users that may authenticate.
+
+  * **state** (optional) - Specifies where all of the ID Tokens in the key-value store are saved, so that sessions will persist across restart or reboot of the NGINX host. The NGINX Plus user account, typically **nginx**, must have write permission to the directory where the state file is stored. Consider creating a dedicated directory for this purpose.
+
+  * **timeout** - Expired tokens are removed from the key-value store after the `timeout` value. This should be set to value slightly longer than the JWT validity period. JWT validation occurs on each request, and will fail when the expiry date (`exp` claim) has elapsed. If JWTs are issued without a JWT then set `timeout` to the desired session duration. If JWTs are issued with various validity periods then set `timeout` to exceed the longest period.
+
+  * **sync** (optional) - If deployed in a cluster, the key-value store may be synchronized across all instances in the cluster, so that all instances are able to create and validate authenticated sessions. Each instance must be configured to participate in state sharing with the [zone_sync module](http://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html) and by adding the `sync` parameter to the `keyval_zone` directive above.
+
+## Session Management
+
+The [NGINX Plus API](http://nginx.org/en/docs/http/ngx_http_api_module.html) is enabled in **openid_connect.server_conf** so that sessions can be created. The API can be used to manage the current set of active sessions.
 
 To query the current sessions in the key-value store:
 
-`curl localhost:8010/api/3/http/keyvals/sessions`
+`$ curl localhost:8010/api/3/http/keyvals/sessions`
 
 To delete a single session:
 
-`curl -X PATCH '{"<session ID>":null}' localhost:8010/api/3/http/keyvals/sessions`
+`$ curl -iX PATCH '{"<session ID>":null}' localhost:8010/api/3/http/keyvals/sessions`
 
-To delete all sessions
+To delete all sessions:
 
-`curl -X DELETE localhost:8010/api/3/http/keyvals/sessions`
+`$ curl -iX DELETE localhost:8010/api/3/http/keyvals/sessions`

opaque_session_token/frontend.conf

@@ -13,8 +13,8 @@ js_include conf.d/openid_connect.js;
 js_set $requestid_hash hashRequestId;
 js_set $auth_token getAuthToken;
 
-keyval_zone zone=sessions:1M; # state=state_sessions.json;
-keyval $cookie_auth_token $session_jwt zone=sessions;
+keyval_zone zone=sessions:1M state=state_sessions.json timeout=1h; # CHANGE timeout to JWT validity period
+keyval $cookie_auth_token $session_jwt zone=sessions;              # Exchange cookie for JWT
 
 # The frontend server - reverse proxy with OpenID Connect authentication
 #
@@ -33,7 +33,7 @@ server {
 
     location / {
         # This site is protected with OpenID Connect
-        auth_jwt "" token=$session_jwt;
+        auth_jwt "" token=$session_jwt; # Obtain JWT from key-value store
         auth_jwt_key_file $oidc_jwt_keyfile;
 
         # Absent/invalid OpenID Connect token will (re)start auth process

opaque_session_token/openid_connect.server_conf

@@ -72,9 +72,9 @@
         proxy_pass     http://127.0.0.1:$server_port/api/3/http/keyvals/sessions;
     } 
 
-    location /api {
+    location /api/ {
         api write=on;
-        allow 127.0.0.1;
+        allow 127.0.0.1; # Only the NGINX host may call the NIGNX Plus API
         deny all;
     }