Implement Front-Channel Logout endpoint

Implement OpenID Connect Front-Channel Logout 1.0 specification:
- Add default /front_channel_logout location that handles logout requests
- Both sid and iss parameters must be present
- Issuer verification against iss claim in ID token

Reference: https://openid.net/specs/openid-connect-frontchannel-1_0.html

Author: route443

README.md

@@ -100,6 +100,10 @@ Requests made to the `/logout` location invalidate both the ID token, access tok
 
 RP-initiated logout is supported according to [OpenID Connect RP-Initiated Logout 1.0](https://openid.net/specs/openid-connect-rpinitiated-1_0.html). This behavior is controlled by the `$oidc_end_session_endpoint` variable.
 
+#### Front-Channel OIDC Logout
+
+Front-Channel Logout is supported according to [OpenID Connect Front-Channel Logout 1.0](https://openid.net/specs/openid-connect-frontchannel-1_0.html). The `/front_channel_logout endpoint` location handles logout requests from the IdP. Both arguments, `sid` (session identifier) and `iss` (issuer identifier), must be present.
+
 ### 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.
@@ -198,6 +202,7 @@ The key-value store is used to maintain persistent storage for ID tokens and ref
 keyval_zone zone=oidc_id_tokens:1M     state=/var/lib/nginx/state/oidc_id_tokens.json     timeout=1h;
 keyval_zone zone=oidc_access_tokens:1M state=/var/lib/nginx/state/oidc_access_tokens.json timeout=1h;
 keyval_zone zone=refresh_tokens:1M     state=/var/lib/nginx/state/refresh_tokens.json     timeout=8h;
+keyval_zone zone=oidc_sids:1M          state=/var/lib/nginx/state/oidc_sids.json          timeout=8h;
 keyval_zone zone=oidc_pkce:128K timeout=90s;
 ```
 
@@ -314,3 +319,4 @@ This reference implementation for OpenID Connect is supported for NGINX Plus sub
   * **R23** PKCE support. Added support for deployments behind another proxy or load balancer.
   * **R28** Access token support. Added support for access token to authorize NGINX to access protected backend.
   * **R32** Added support for `client_secret_basic` client authentication method.
+  * **R33** Refactor code to use async/await. Implement Front-Channel Logout endpoint.

openid_connect.js

@@ -8,7 +8,8 @@ export default {
     auth,
     codeExchange,
     extractTokenClaims,
-    logout
+    logout,
+    handleFrontChannelLogout
 };
 
 // The main authentication flow, called before serving a protected resource.
@@ -42,7 +43,7 @@ async function auth(r, afterSyncCheck) {
 
     // Determine session ID and store session data
     const sessionId = getSessionId(r, false);
-    storeSessionData(r, tokenset, false);
+    storeSessionData(r, sessionId, claims, tokenset, true);
 
     r.log("OIDC success, refreshing session " + sessionId);
 
@@ -79,7 +80,7 @@ async function codeExchange(r) {
 
     // Determine session ID and store session data for a new session
     const sessionId = getSessionId(r, true);
-    storeSessionData(r, tokenset, true);
+    storeSessionData(r, sessionId, claims, tokenset, true);
 
     r.log("OIDC success, creating session " + sessionId);
 
@@ -173,7 +174,12 @@ function validateIdTokenClaims(r, claims) {
 }
 
 // Store session data in the key-val store
-function storeSessionData(r, tokenset, isNewSession) {
+function storeSessionData(r, sessionId, claims, tokenset, isNewSession) {
+    if (claims.sid) {
+        r.variables.idp_sid = claims.sid;
+        r.variables.client_sid = sessionId;
+    }
+
     if (isNewSession) {
         r.variables.new_session = tokenset.id_token;
         r.variables.new_access_token = tokenset.access_token || "";
@@ -190,7 +196,7 @@ function storeSessionData(r, tokenset, isNewSession) {
 // Extracts claims from the validated ID Token (used by /_token_validation)
 function extractTokenClaims(r) {
     const claims = {};
-    const claimNames = ["sub", "iss", "iat", "nonce"];
+    const claimNames = ["sub", "iss", "iat", "nonce", "sid"];
 
     claimNames.forEach((name) => {
         const value = r.variables["jwt_claim_" + name];
@@ -277,7 +283,7 @@ async function refreshTokens(r) {
 
 // Logout handler
 function logout(r) {
-    r.log("RP-Initiated Logout for " + (r.variables.cookie_auth_token || "unknown"));
+    r.log("OIDC RP-Initiated Logout for " + (r.variables.cookie_auth_token || "unknown"));
 
     function getLogoutRedirectUrl(base, redirect) {
         return redirect.match(/^(http|https):\/\//) ? redirect : base + redirect;
@@ -286,7 +292,16 @@ function logout(r) {
     var logoutRedirectUrl = getLogoutRedirectUrl(r.variables.redirect_base,
                             r.variables.oidc_logout_redirect);
 
-    function performLogout(redirectUrl) {
+    async function performLogout(redirectUrl, idToken) {
+        // Clean up $idp_sid -> $client_sid mapping
+        if (idToken && idToken !== '-') {
+            const claims = await getTokenClaims(r, idToken);
+            if (claims.sid) {
+                r.variables.idp_sid = claims.sid;
+                r.variables.client_sid = '-';
+            }
+        }
+
         r.variables.session_jwt = '-';
         r.variables.access_token = '-';
         r.variables.refresh_token = '-';
@@ -305,12 +320,79 @@ function logout(r) {
 
         var logoutArgs = "?post_logout_redirect_uri=" + encodeURIComponent(logoutRedirectUrl) +
                          "&id_token_hint=" + encodeURIComponent(r.variables.session_jwt);
-        performLogout(r.variables.oidc_end_session_endpoint + logoutArgs);
+        performLogout(r.variables.oidc_end_session_endpoint + logoutArgs, r.variables.session_jwt);
     } else {
-        performLogout(logoutRedirectUrl);
+        performLogout(logoutRedirectUrl, r.variables.session_jwt);
     }
 }
 
+/**
+ * Handles Front-Channel Logout as per OpenID Connect Front-Channel Logout 1.0 spec.
+ * @see https://openid.net/specs/openid-connect-frontchannel-1_0.html
+ */
+async function handleFrontChannelLogout(r) {
+    const sid = r.args.sid;
+    const requestIss = r.args.iss;
+
+    // Validate input parameters
+    if (!sid) {
+        r.error("Missing sid parameter in front-channel logout request");
+        r.return(400, "Missing sid");
+        return;
+    }
+
+    if (!requestIss) {
+        r.error("Missing iss parameter in front-channel logout request");
+        r.return(400, "Missing iss");
+        return;
+    }
+
+    r.log("OIDC Front-Channel Logout initiated for sid: " + sid);
+
+    // Define idp_sid as a key to get the client_sid from the key-value store
+    r.variables.idp_sid = sid;
+
+    const clientSid = r.variables.client_sid;
+    if (!clientSid || clientSid === '-') {
+        r.log("No client session found for sid: " + sid);
+        r.return(200, "Logout successful");
+        return;
+    }
+
+    /* TODO: Since we cannot use the cookie_auth_token var as a key (it does not exist if cookies
+       are absent), we use the request_id as a workaround. */
+    r.variables.request_id = clientSid;
+    var sessionJwt = r.variables.new_session;
+
+    if (!sessionJwt || sessionJwt === '-') {
+        r.log("No associated ID token found for client session: " + clientSid);
+        cleanSessionData(r);
+        r.return(200, "Logout successful");
+        return;
+    }
+
+    const claims = await getTokenClaims(r, sessionJwt);
+    if (claims.iss !== requestIss) {
+        r.error("Issuer mismatch during logout. Received iss: " +
+                requestIss + ", expected: " + claims.iss);
+        r.return(400, "Issuer mismatch");
+        return;
+    }
+
+    // idp_sid needs to be updated after subrequest
+    r.variables.idp_sid = sid;
+    cleanSessionData(r);
+
+    r.return(200, "Logout successful");
+}
+
+function cleanSessionData(r) {
+    r.variables.new_session = '-';
+    r.variables.new_access_token = '-';
+    r.variables.new_refresh = '-';
+    r.variables.client_sid = '-';
+}
+
 // Initiate a new authentication flow by redirecting to the IdP's authorization endpoint
 function initiateNewAuth(r) {
     const oidcConfigurables = ["authz_endpoint", "scopes", "hmac_key", "cookie_flags"];

openid_connect.server_conf

@@ -1,6 +1,7 @@
     # Advanced configuration START
     set $internal_error_message "NGINX / OpenID Connect login failure\n";
     set $pkce_id "";
+    set $idp_sid "";
     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
@@ -79,6 +80,13 @@
         js_content oidc.logout;
     }
 
+    location = /front_channel_logout {
+        status_zone "OIDC logout";
+        add_header Cache-Control "no-store";
+        default_type text/plain;
+        js_content oidc.handleFrontChannelLogout;
+    }
+
     location = /_logout {
         # This location is the default value of $oidc_logout_redirect (in case it wasn't configured)
         default_type text/plain;

openid_connect_configuration.conf

@@ -104,6 +104,7 @@ proxy_cache_path /var/cache/nginx/jwk levels=1 keys_zone=jwk:64k max_size=1m;
 keyval_zone zone=oidc_id_tokens:1M     state=/var/lib/nginx/state/oidc_id_tokens.json     timeout=1h;
 keyval_zone zone=oidc_access_tokens:1M state=/var/lib/nginx/state/oidc_access_tokens.json timeout=1h;
 keyval_zone zone=refresh_tokens:1M     state=/var/lib/nginx/state/refresh_tokens.json     timeout=8h;
+keyval_zone zone=oidc_sids:1M          state=/var/lib/nginx/state/oidc_sids.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
@@ -113,6 +114,7 @@ keyval $request_id $new_session          zone=oidc_id_tokens;     # For initial
 keyval $request_id $new_access_token     zone=oidc_access_tokens;
 keyval $request_id $new_refresh          zone=refresh_tokens; # ''
 keyval $pkce_id $pkce_code_verifier      zone=oidc_pkce;
+keyval $idp_sid $client_sid              zone=oidc_sids;
 
 auth_jwt_claim_set $jwt_audience aud; # In case aud is an array
 js_import oidc from conf.d/openid_connect.js;