Enable PKCE Support (#25)

* Enable PKCE Support

* Enable PKCE Support

- Code cleanup and refactoring
- New function for setting IdP Client Auth variables

* Enable PKCE Support

- Code cleanup and refactoring
- New function for setting IdP Client Auth variables

* PKCE Support

- Added PKCE documentation to README
- Adjusted pkce keyvalue zones size and timeout

Co-authored-by: Timo Stark <[email protected]>

Author: tippexs

README.md

@@ -15,7 +15,7 @@ This implementation assumes the following environment:
   * The identity provider (IdP) supports OpenID Connect 1.0
   * The authorization code flow is in use
   * NGINX Plus is configured as a relying party
-  * The IdP knows NGINX Plus as a confidential client
+  * The IdP knows NGINX Plus as a confidential client or a public client using PKCE
 
 With this environment, both the client and NGINX Plus communicate directly with the IdP at different stages during the initial authentication event.
 
@@ -89,8 +89,8 @@ When NGINX Plus is deployed behind another proxy, the original protocol and port
   * Create an OpenID Connect client to represent your NGINX Plus instance
     * Choose the **authorization code flow**
     * Set the **redirect URI** to the address of your NGINX Plus instance (including the port number), with `/_codexch` as the path, e.g. `https://my-nginx.example.com:443/_codexch`
-    * Ensure NGINX Plus is configured as a confidential client (with a client secret)
-    * Make a note of the `client ID` and `client secret`
+    * Ensure NGINX Plus is configured as a confidential client (with a client secret) or a public client (with PKCE S256 enabled)
+    * Make a note of the `client ID` and `client secret` if set
 
   * 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 next section. Otherwise:
     * Obtain the URL for `jwks_uri` or download the JWK file to your NGINX Plus instance
@@ -130,6 +130,7 @@ The key-value store is used to maintain persistent storage for ID tokens and ref
 ```nginx
 keyval_zone zone=oidc_id_tokens:1M state=conf.d/oidc_id_tokens.json timeout=1h;
 keyval_zone zone=refresh_tokens:1M state=conf.d/refresh_tokens.json timeout=8h;
+keyval_zone zone=oidc_pkce:128K timeout=90s;
 ```
 
 Each of the `keyval_zone` parameters are described below.
@@ -229,3 +230,4 @@ This reference implementation for OpenID Connect is supported for NGINX Plus sub
   * **R18** Opaque session tokens now used by default. Added support for refresh tokens. Added `/logout` location.
   * **R19** Minor bug fixes
   * **R22** Separate configuration file, supports multiple IdPs. Configurable scopes and cookie flags. JavaScript is imported as an indepedent module with `js_import`. Container-friendly logging. Additional metrics for OIDC activity.
+  * **R23** PKCE support. Added support for deployments behind another proxy or load balancer.

openid_connect.js

@@ -24,18 +24,8 @@ function auth(r) {
             r.return(500, r.variables.internal_error_message);
             return;
         }
-
-        // Choose a nonce for this flow for the client, and hash it for the IdP
-        var noncePlain = r.variables.request_id;
-        var c = require('crypto');
-        var h = c.createHmac('sha256', r.variables.oidc_hmac_key).update(noncePlain);
-        var nonceHash = h.digest('base64url');
-
         // Redirect the client to the IdP login page with the cookies we need for state
-        r.headersOut['Set-Cookie'] = [
-            "auth_redir=" + r.variables.request_uri + "; " + r.variables.oidc_cookie_flags,
-            "auth_nonce=" + noncePlain + "; " + r.variables.oidc_cookie_flags ];
-        r.return(302, r.variables.oidc_authz_endpoint + "?response_type=code&scope=" + r.variables.oidc_scopes + "&client_id=" + r.variables.oidc_client + "&state=0&redirect_uri="+ r.variables.redirect_base + r.variables.redir_location + "&nonce=" + nonceHash);
+        r.return(302, r.variables.oidc_authz_endpoint + getAuthZArgs(r));
         return;
     }
 
@@ -125,8 +115,7 @@ function codeExchange(r) {
 
     // Pass the authorization code to the /_token location so that it can be
     // proxied to the IdP in exchange for a JWT
-    r.subrequest("/_token", "code=" + r.variables.arg_code,
-        function(reply) {
+    r.subrequest("/_token",idpClientAuth(r), function(reply) {
             if (reply.status == 504) {
                 r.error("OIDC timeout connecting to IdP when sending authorization code");
                 r.return(504);
@@ -248,3 +237,39 @@ function logout(r) {
     r.variables.refresh_token = "-";
     r.return(302, r.variables.oidc_logout_redirect);
 }
+
+function getAuthZArgs(r) {
+    // Choose a nonce for this flow for the client, and hash it for the IdP
+    var noncePlain = r.variables.request_id;
+    var c = require('crypto');
+    var h = c.createHmac('sha256', r.variables.oidc_hmac_key).update(noncePlain);
+    var nonceHash = h.digest('base64url');
+    var authZArgs = "?response_type=code&scope=" + r.variables.oidc_scopes + "&client_id=" + r.variables.oidc_client + "&redirect_uri="+ r.variables.redirect_base + r.variables.redir_location + "&nonce=" + nonceHash;
+
+    r.headersOut['Set-Cookie'] = [
+        "auth_redir=" + r.variables.request_uri + "; " + r.variables.oidc_cookie_flags,
+        "auth_nonce=" + noncePlain + "; " + r.variables.oidc_cookie_flags
+    ];
+
+    if ( r.variables.oidc_pkce_enable == 1 ) {
+        var pkce_code_verifier = c.createHmac('sha256', r.variables.oidc_hmac_key).update(String(Math.random())).digest('hex');
+        r.variables.pkce_id = c.createHash('sha256').update(String(Math.random())).digest('base64url');
+        var pkce_code_challenge = c.createHash('sha256').update(pkce_code_verifier).digest('base64url');
+        r.variables.pkce_code_verifier = pkce_code_verifier;
+
+        authZArgs += "&code_challenge_method=S256&code_challenge=" + pkce_code_challenge + "&state=" + r.variables.pkce_id;
+    } else {
+        authZArgs += "&state=0";
+    }
+    return authZArgs;
+}
+
+function idpClientAuth(r) {
+    // If PKCE is enabled we have to use the code_verifier
+    if ( r.variables.oidc_pkce_enable == 1 ) {
+        r.variables.pkce_id = r.variables.arg_state;
+        return "code=" + r.variables.arg_code + "&code_verifier=" + r.variables.pkce_code_verifier;
+    } else {
+        return "code=" + r.variables.arg_code + "&client_secret=" + r.variables.oidc_client_secret;
+    }   
+}

openid_connect.server_conf

@@ -1,5 +1,6 @@
     # Advanced configuration START
     set $internal_error_message "NGINX / OpenID Connect login failure\n";
+    set $pkce_id "";
     resolver 8.8.8.8; # For DNS lookup of IdP endpoints;
     subrequest_output_buffer_size 32k; # To fit a complete tokenset response
     gunzip on; # Decompress IdP responses if necessary
@@ -30,15 +31,15 @@
         js_content oidc.codeExchange;
         error_page 500 502 504 @oidc_error; 
     }
-
+   
     location = /_token {
         # This location is called by oidcCodeExchange(). We use the proxy_ directives
         # to construct the OpenID Connect token request, as per:
         #  http://openid.net/specs/openid-connect-core-1_0.html#TokenRequest
         internal;
         proxy_ssl_server_name on; # For SNI to the IdP
         proxy_set_header      Content-Type "application/x-www-form-urlencoded";
-        proxy_set_body        "grant_type=authorization_code&code=$arg_code&client_id=$oidc_client&client_secret=$oidc_client_secret&redirect_uri=$redirect_base$redir_location";
+        proxy_set_body        "grant_type=authorization_code&client_id=$oidc_client&$args&redirect_uri=$redirect_base$redir_location";
         proxy_method          POST;
         proxy_pass            $oidc_token_endpoint;
    }

openid_connect_configuration.conf

@@ -20,6 +20,10 @@ map $host $oidc_client {
     default "my-client-id";
 }
 
+map $host $oidc_pkce_enable {
+    default 0;
+}
+
 map $host $oidc_client_secret {
     default "my-client-secret";
 }
@@ -63,11 +67,13 @@ proxy_cache_path /var/cache/nginx/jwk levels=1 keys_zone=jwk:64k max_size=1m;
 # Change timeout values to at least the validity period of each token type
 keyval_zone zone=oidc_id_tokens:1M state=conf.d/oidc_id_tokens.json timeout=1h;
 keyval_zone zone=refresh_tokens:1M state=conf.d/refresh_tokens.json timeout=8h;
+keyval_zone zone=oidc_pkce:128K timeout=90s; # Temporary storage for PKCE code verifier.
 
 keyval $cookie_auth_token $session_jwt zone=oidc_id_tokens;   # Exchange cookie for JWT
 keyval $cookie_auth_token $refresh_token zone=refresh_tokens; # Exchange cookie for refresh token
 keyval $request_id $new_session zone=oidc_id_tokens; # For initial session creation
 keyval $request_id $new_refresh zone=refresh_tokens; # ''
+keyval $pkce_id $pkce_code_verifier zone=oidc_pkce;
 
 auth_jwt_claim_set $jwt_audience aud; # In case aud is an array
 js_import oidc from conf.d/openid_connect.js;