feat: added OIDC logout endpoint

Author: shawnhankim

README.md

@@ -36,7 +36,7 @@ If a [refresh token](https://openid.net/specs/openid-connect-core-1_0.html#Refre
 
 ### 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.
+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. By interacting with `$oidc_logout_endpoint` which is the end session endpoint of IdP, the authenticated session is ended at the IdP.
 
 ### Multiple IdPs
 

configure.sh

@@ -120,7 +120,7 @@ fi
 # Build an intermediate configuration file
 # File format is: <NGINX variable name><space><IdP value>
 #
-jq -r '. | "$oidc_authz_endpoint \(.authorization_endpoint)\n$oidc_token_endpoint \(.token_endpoint)\n$oidc_jwks_uri \(.jwks_uri)"' < /tmp/${COMMAND}_$$_json > /tmp/${COMMAND}_$$_conf
+jq -r '. | "$oidc_authz_endpoint \(.authorization_endpoint)\n$oidc_token_endpoint \(.token_endpoint)\n$oidc_jwks_uri \(.jwks_uri)\n$oidc_logout_endpoint \(.logout_endpoint)"' < /tmp/${COMMAND}_$$_json > /tmp/${COMMAND}_$$_conf
 
 # Create a random value for HMAC key, adding to the intermediate configuration file
 echo "\$oidc_hmac_key `openssl rand -base64 18`" >> /tmp/${COMMAND}_$$_conf
@@ -178,7 +178,7 @@ fi
 
 # Loop through each configuration variable
 echo "$COMMAND: NOTICE: Configuring $CONFDIR/openid_connect_configuration.conf"
-for OIDC_VAR in \$oidc_authz_endpoint \$oidc_token_endpoint \$oidc_jwt_keyfile \$oidc_hmac_key $CLIENT_ID_VAR $CLIENT_SECRET_VAR $PKCE_ENABLE_VAR; do
+for OIDC_VAR in \$oidc_authz_endpoint \$oidc_token_endpoint \$oidc_jwt_keyfile \$oidc_logout_endpoint \$oidc_hmac_key $CLIENT_ID_VAR $CLIENT_SECRET_VAR $PKCE_ENABLE_VAR; do
 	# Pull the configuration value from the intermediate file
 	VALUE=`grep "^$OIDC_VAR " /tmp/${COMMAND}_$$_conf | cut -f2 -d' '`
 	echo -n "$COMMAND: NOTICE:  - $OIDC_VAR ..."

openid_connect.js

@@ -5,7 +5,10 @@
  */
 var newSession = false; // Used by oidcAuth() and validateIdToken()
 
-export default {auth, codeExchange, validateIdToken, logout};
+const EXTRA_PARAMS = 1;
+const REPLACE_PARAMS = 2;
+
+export default {auth, codeExchange, validateIdToken, logout, redirectPostLogout};
 
 function retryOriginalRequest(r) {
     delete r.headersOut["WWW-Authenticate"]; // Remove evidence of original failed auth_jwt
@@ -253,11 +256,37 @@ function validateIdToken(r) {
     }
 }
 
+// Default RP-Initiated or Custom Logout w/ OP.
+// - An RP requests that the OP log out the end-user by redirecting the
+//   end-user's User Agent to the OP's Logout endpoint.
+// - https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout
+// - https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RedirectionAfterLogout
 function logout(r) {
     r.log("OIDC logout for " + r.variables.cookie_auth_token);
-    r.variables.session_jwt = "-";
-    r.variables.refresh_token = "-";
-    r.return(302, r.variables.oidc_logout_redirect);
+    var idToken = r.variables.session_jwt;
+    var queryParams = '?post_logout_redirect_uri=' + 
+                      r.variables.redirect_base + 
+                      r.variables.oidc_logout_redirect +
+                      '&id_token_hint=' + idToken;
+    if (r.variables.oidc_logout_query_params_option == REPLACE_PARAMS) {
+        queryParams = '?' + r.variables.oidc_logout_query_params;
+    } else if (r.variables.oidc_logout_query_params_option == EXTRA_PARAMS) {
+        queryParams += '&' + r.variables.oidc_logout_query_params;
+    }
+    r.variables.request_id    = '-';
+    r.variables.session_jwt   = '-';
+    r.variables.access_token  = '-';
+    r.variables.refresh_token = '-';
+    r.return(302, r.variables.oidc_logout_endpoint + queryParams);
+}
+
+// Redirect URI after logged-out from the OP.
+function redirectPostLogout(r) {
+    if (r.variables.post_logout_return_uri) {
+        r.return(302, r.variables.post_logout_return_uri);
+    } else {
+        r.return(302, r.variables.redirect_base + r.variables.cookie_auth_redir);
+    }
 }
 
 function getAuthZArgs(r) {

openid_connect.server_conf

@@ -67,16 +67,30 @@
     }
 
     location = /logout {
+        # RP-Initiated Logout to interact with $oidc_end_session_endpoint as per:
+        #  https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout
         status_zone "OIDC logout";
-        add_header Set-Cookie "auth_token=; $oidc_cookie_flags"; # Send empty cookie
-        add_header Set-Cookie "auth_redir=; $oidc_cookie_flags"; # Erase original cookie
         js_content oidc.logout;
     }
 
     location = /_logout {
-        # This location is the default value of $oidc_logout_redirect (in case it wasn't configured)
+        # This location is a RP's callback URI that is the default value of 
+        # $oidc_logout_redirect which is called by OP after successful logout.
+
+        # Clean cookies
+        add_header Set-Cookie "auth_token=; $oidc_cookie_flags"; # Send empty cookie
+        add_header Set-Cookie "auth_redir=; $oidc_cookie_flags"; # Erase original cookie
+        add_header Set-Cookie "auth_nonce=; $oidc_cookie_flags"; 
+
+        # Enable following directives, and disable the oidc.redirectPostLogout()
+        # if you want to test a Built-in simple logout page before production.
         default_type text/plain;
         return 200 "Logged out\n";
+
+        # Enable oidc.redirectPostLogout(), and disable the above built-in logout
+        # page if you want to redirect to either the landing page or custom
+        # logout page using the map of $post_logout_return_uri.
+        #js_content oidc.redirectPostLogout;
     }
 
     location @oidc_error {

openid_connect_configuration.conf

@@ -28,6 +28,27 @@ map $host $oidc_jwt_keyfile {
     default "http://127.0.0.1:8080/auth/realms/master/protocol/openid-connect/certs";
 }
 
+map $host $oidc_logout_endpoint {
+    default "http://127.0.0.1:8080/auth/realms/master/protocol/openid-connect/logout";
+}
+
+map $host $oidc_logout_query_params_option {
+    # 0: default query params for the RP-initiated logout
+    # 1: extra query params is added after the default query params
+    # 2: replace default query params with custom query params
+    default 0;
+}
+
+map $host $oidc_logout_query_params {
+    # Each IdP may use different query params of the $oidc_logout_endpoint. For
+    # example, The Amazon Cognito requires `client_id` and `logout_uri`. The
+    # Auth0 requires `client_id` and `returnTo`. If the map value is empty, then
+    # `post_logout_redirect_uri` and `id_token_hint` are used as default query
+    # params for most of IdPs like AzureAD/Okta/Keycloak/OneLogin/PingIdentity.
+    default "";
+    #www.example.com "client_id=$oidc_client&logout_uri=$redirect_base/_logout";
+}
+
 map $host $oidc_client {
     default "my-client-id";
 }
@@ -44,12 +65,38 @@ map $host $oidc_scopes {
     default "openid+profile+email+offline_access";
 }
 
+map $host $oidc_landing_page {
+    # Where to send browser after successful login. This option is only 
+    # recommended for scenarios where a landing page shows default information
+    # without login, and the RP redirects to the landing page after successful
+    # login from the OP. If this is empty, then the RP redirects to $request_uri.
+    default "";
+    #www.example.com $redirect_base;
+}
+
 map $host $oidc_logout_redirect {
-    # Where to send browser after requesting /logout location. This can be
-    # replaced with a custom logout page, or complete URL.
+    # This is a RP's callback URI which is called by OP after successful logout.
     default "/_logout"; # Built-in, simple logout page
 }
 
+map $host $post_logout_return_uri {
+    # Where to send browser after the RP requests /logout to the OP, and after
+    # the RP (/_logout) is called by the OP and cleans cookies. The following
+    # examples can be replaced with a custom logout page, or a complete URL.
+    # If this is empty, then the RP redirects to $request_uri.
+
+    default "";
+
+    # Enable if you want to redirect to the landing page
+    # www.example.com $oidc_landing_page;
+
+    # Enable and edit if you want to redirect to a custom logout page
+    #www.example.com $redirect_base/signout;
+
+    # Enable and edit if you want to redirect to an another complete URL
+    #www.example.com https://www.nginx.com;
+}
+
 map $host $oidc_hmac_key {
     # This should be unique for every NGINX instance/cluster
     default "ChangeMe";