R18

Author: lcrilly

README.md

@@ -4,7 +4,7 @@ Reference implementation of NGINX Plus as relying party for OpenID Connect authe
 
 ## Description
 
-This repository describes how to enable OpenID Connect integration for [NGINX Plus](https://www.nginx.com/products/nginx/). The solution depends on the [auth_jwt](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html) module and as such is not suitable for [open source NGINX](http://www.nginx.org/en).
+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).
 
 <img src=https://www.nginx.com/wp-content/uploads/2018/04/dia-LC-2018-03-30-OpenID-Connect-authorization-code-flow-NGINX-800x426-03.svg alt="OpenID Connect components" width=500>
 
@@ -24,15 +24,23 @@ With this environment, both the client and NGINX Plus communicate directly with
 
 NGINX Plus is configured to perform OpenID Connect authentication. Upon a first visit to a protected resource, NGINX Plus initiates the OpenID Connect authorization code flow and redirects the client to the OpenID Connect provider (IdP). When the client returns to NGINX Plus with an authorization code, NGINX Plus exchanges that code for a set of tokens by communicating directly with the IdP.
 
-The ID Token received from the IdP is then [validated](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation). NGINX Plus then issues a session cookie to the client using either the ID Token or the Access Token and is redirected to the original URI requested prior to authentication.
+The ID Token received from the IdP is then [validated](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation). NGINX Plus then stores the ID token in the key-value store, issues a session cookie to the client using a random string, (which becomes the key to obtain the ID token from the key-value store) and redirects the client to the original URI requested prior to authentication.
 
-Subsequent requests to protected resources are authenticated using the session cookie by performing JWT validation.
- 
-For more information on OIDC and NGINX Plus JWT support, see [Authenticating Users to Existing Applications with OpenID Connect and NGINX Plus](https://www.nginx.com/blog/authenticating-users-existing-applications-openid-connect-nginx-plus/).
+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.
+
+For more information on OpenID Connect and JWT validation with NGINX Plus, see [Authenticating Users to Existing Applications with OpenID Connect and NGINX Plus](https://www.nginx.com/blog/authenticating-users-existing-applications-openid-connect-nginx-plus/).
+
+### 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.
+
+### 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.
 
 ## Installation
 
-OpenID Connect integration requires NGINX Plus R15 or later to be installed. See [Installing NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/).
+The master branch of this repo requires the most recent release of NGINX Plus. Older releases should use the branch corresponding to that NGINX Plus release. For installation instructions, see [Installing NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). 
 
 In addition, the [njs module](https://www.nginx.com/blog/introduction-nginscript/) 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:
 
@@ -67,7 +75,7 @@ All files can be copied to **/etc/nginx/conf.d**
     * Make a note of the `client ID` and `client secret`
 
   * If your IdP supports OpenID Connect Discovery (usually at the URI `/.well-known/openid-configuration`) then use the `configure.sh` script to complete configuration. In this case you can skip the **frontend.conf** configuration. Otherwise:
-    * Download the `jwks_uri` JWK file to your NGINX Plus instance
+    * 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**
 
@@ -78,8 +86,10 @@ Review the following files copied from the GitHub repository so that they match
   * **frontend.conf** - this is the reverse proxy configuration and where the IdP is configured. This file can be automatically configured by using the `configure.sh` script.
     * Modify the upstream group to match your backend site or app
     * Modify the `resolver` directive to match a DNS server that is capable of resolving the IdP defined in `$oidc_token_endpoint`
+    * Modify the URI defined in `$oidc_logout_redirect` to specify an unprotected resource to be displayed after requesting the `/logout` location
     * Configure the preferred listen port and [enable SSL/TLS configuration](https://docs.nginx.com/nginx/admin-guide/security-controls/terminating-ssl-http/)
-    * Set the value of `$oidc_jwt_keyfile` to match the downloaded JWK file from the IdP and ensure that it is readable by the NGINX worker processes
+    * Set the value of `$oidc_jwt_keyfile` to specify the `jwks_uri` value or match the JWK file downloaded from the IdP (ensuring that it is readable by the NGINX worker processes)
+    * 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
     * Modify all of the `set $oidc_` directives to match your IdP configuration
     * Set a unique value for `$oidc_hmac_key` to ensure nonce values are unpredictable
 
@@ -91,6 +101,49 @@ Review the following files copied from the GitHub repository so that they match
   * **openid_connect.js** - this is the JavaScript code for performing the authorization code exchange and nonce hashing
     * No changes are required unless modifying the code exchange or validation process
 
+### Configuring the Key-Value Store
+
+The key-value store is used to maintain persistent storage for ID tokens and refresh tokens. The default configuration should be reviewed so that it suits the environment.
+
+```nginx
+keyval_zone zone=opaque_sessions:1M state=conf.d/opaque_sessions.json timeout=1h;
+keyval_zone zone=refresh_tokens:1M  state=conf.d/refresh_tokens.json  timeout=8h;
+```
+
+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 an `exp` claim then set `timeout` to the desired session duration. If JWTs are issued with a range of 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` directives 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 monitored. The API can also be used to manage the current set of active sessions.
+
+To query the current sessions in the key-value store:
+
+```shell
+$ curl localhost:8010/api/4/http/keyvals/opaque_sessions
+```
+
+To delete a single session:
+
+```shell
+$ curl -iX PATCH -d '{"<session ID>":null}' localhost:8010/api/4/http/keyvals/opaque_sessions
+$ curl -iX PATCH -d '{"<session ID>":null}' localhost:8010/api/4/http/keyvals/refresh_tokens
+```
+
+To delete all sessions:
+
+```shell
+$ curl -iX DELETE localhost:8010/api/3/http/keyvals/opaque_sessions
+$ curl -iX DELETE localhost:8010/api/3/http/keyvals/refresh_tokens
+```
+
 ## Troubleshooting
 
 Any errors generated by the OpenID Connect flow are logged in a separate file, `/var/log/nginx/oidc_error.log`. Check the contents of this file as it may include error responses received by the IdP.
@@ -102,21 +155,16 @@ Any errors generated by the OpenID Connect flow are logged in a separate file, `
   * **Authentication is successful but browser shows too many redirects**
     * This is typically because the JWT sent to the browser cannot be validated, resulting in 'authorization required' `401` response and starting the authentication process again. But the user is already authenticated so is redirected back to NGINX,  hence the redirect loop.
     * Check the error log `/var/log/nginx/oidc_error.log` for JWT/JWK errors.
-    * Ensure that the JWK file (`$oidc_jwt_keyfile` variable) is correct and that the nginx workers have permission to read it.
+    * Ensure that the JWK file (`$oidc_jwt_keyfile` variable) is correct and that the nginx user has permission to read it.
 
 ## Support
 
-All reference OpenID Connect implementations within the GitHub repository are supported for NGINX Plus subscribers.
-
-## Other use cases
-
-Subdirectories within the GitHub repository contain variations of the reference implementation for alternative OpenID Connect use cases.
+This reference implementation for OpenID Connect is supported for NGINX Plus subscribers.
 
-  * **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.
-  
 ## Changelog
 
   * **R15** Initial release of OpenID Connect reference implmentation
   * **R16** Added support for opaque session tokens using key-value store
   * **R17** Configuration now supports JSON Web Key (JWK) set to be obtained by URI
+  * **R18** Opaque session tokens now used by default. Added support for refresh tokens. Added `/logout` location.
 

configure.sh

@@ -4,7 +4,7 @@
 COMMAND=${0##*/}
 CONFDIR=${0%/*}
 if [ $# -lt 1 ]; then
-	echo "USAGE: $COMMAND [options] <OpenID Connect confinguration URL>"
+	echo "USAGE: $COMMAND [options] <OpenID Connect configuration URL>"
 	echo ""
 	echo "Configures NGINX Plus OpenID Connect reference implementation by using the IdP's Discovery interface"
 	echo ""

frontend.conf

@@ -5,16 +5,23 @@ upstream my_backend {
 }
 
 # Custom log format to include the 'sub' claim in the REMOTE_USER field
-log_format main_jwt '$remote_addr $jwt_claim_sub $remote_user [$time_local] "$request" $status '
+log_format main_jwt '$remote_addr - $jwt_claim_sub [$time_local] "$request" $status '
                     '$body_bytes_sent "$http_referer" "$http_user_agent" "$http_x_forwarded_for"';
 
-# nginScript functions for code exchange and hashing for secure nonce validation
+# JavaScript code for OpenID Connect
 js_include conf.d/openid_connect.js;
 js_set $requestid_hash hashRequestId;
-js_set $auth_token getAuthToken;
 
-# Caching for JWT keys when using 'auth_jwt_key_request' with NGINX Plus R17+
-proxy_cache_path /var/cache/nginx/jwk levels=1 keys_zone=jwk:1m max_size=10m;
+keyval_zone zone=opaque_sessions:1M state=conf.d/opaque_sessions.json timeout=1h; # CHANGE timeout to JWT/exp validity period
+keyval_zone zone=refresh_tokens:1M  state=conf.d/refresh_tokens.json  timeout=8h; # CHANGE timeout to refresh validity period
+
+keyval $cookie_auth_token $session_jwt zone=opaque_sessions;  # Exchange cookie for JWT
+keyval $cookie_auth_token $refresh_token zone=refresh_tokens; # Exchange cookie for refresh token
+keyval $request_id $new_session zone=opaque_sessions; # For initial session creation
+keyval $request_id $new_refresh zone=refresh_tokens;  # "
+
+# JWK Set will be fetched from $oidc_jwks_uri and cached here - ensure writable by nginx user
+proxy_cache_path /var/cache/nginx/jwk levels=1 keys_zone=jwk:64k max_size=1m;
 
 # The frontend server - reverse proxy with OpenID Connect authentication
 #
@@ -26,31 +33,30 @@ server {
     subrequest_output_buffer_size 32k; # To fit a complete tokenset response
 
     set $oidc_jwt_keyfile     /etc/nginx/my_idp_jwk.json; # URL when using 'auth_jwt_key_request'
+    set $oidc_logout_redirect "/_logout"; Where to send browser after requesting /logout location
     set $oidc_authz_endpoint  "http://127.0.0.1:8080/auth/realms/master/protocol/openid-connect/auth";
     set $oidc_token_endpoint  "http://127.0.0.1:8080/auth/realms/master/protocol/openid-connect/token";
     set $oidc_client          "my-client-id";
     set $oidc_client_secret   "my-client-secret";
-    set $oidc_token_type      "id_token"; # Session token (access_token or id_token)
     set $oidc_hmac_key        "ChangeMe"; # This should be unique for every NGINX instance/cluster
 
     listen 8010; # Use SSL/TLS in production
-
+    
     location / {
         # This site is protected with OpenID Connect
-        auth_jwt "" token=$cookie_auth_token;
-        auth_jwt_key_file $oidc_jwt_keyfile;
-        #auth_jwt_key_request /_jwks_uri; # Requires NGINX Plus R17+
+        auth_jwt "" token=$session_jwt;
+        auth_jwt_key_file $oidc_jwt_keyfile; # Enable when using filename
+        #auth_jwt_key_request /_jwks_uri; # Enable when using URL
 
-        # Absent/invalid OpenID Connect token will (re)start auth process
+        # Absent/invalid OpenID Connect token will (re)start auth process (including refresh)
         error_page 401 @oidc_auth;
 
-        # Successfully authenticated users are proxied to the backend,
+        # Successfuly authenticated users are proxied to the backend,
         # with 'sub' claim passed as HTTP header
         proxy_set_header username $jwt_claim_sub;
         proxy_pass http://my_backend; # The backend site/app
-
+        
         access_log /var/log/nginx/access.log main_jwt;
-        error_log  /var/log/nginx/oidc_error.log info;
     }
 }