feat: access token & new endpoints (/login, /userinfo, /v2/logout)

shawndotkim · shawnhankim · commit de4bab2593c6 · 2022-11-17T14:43:22.000-08:00
**1. access token**

  - Enhance the NJS Code to capture the `access_token` sent by the IdP.

  - Store the `access_token` in the k/v store as same as we store `id_token` and `refresh_token`

**2. new endpoints**

  - Add `/userinfo` endpoint:
    - Add a map variable of `$oidc_userinfo_endpoint` as same as authz and token endpoints here (`openid_connect_configuration.conf`) .
    - Expose `/userinfo` endpoint here(`openid_connect.server_conf`) in a location block of NGINX Plus to interact with IdP's `userinfo_endpoint` which is defined in the endpoint of`well-known/openid-configuration`.
    - The nginx location block should proxy to the IdP’s `userinfo_endpoint` by adding `access_token` as a bearer token.
      ```
      Authorization : Bearer &lt;access_token&gt;
      ```
    - The response coming from IdP should be returned back to the caller as it is.

  - Expose `/login` endpoint:
    - Expose the `/login` endpoint as a location block here (`openid_connect.server_conf`)
    - Proxy it to the IdP's `authorization_endpoint` configured in the map variable of `$oidc_authz_endpoint` in (`openid_connect_configuration.conf`).
    - This would outsource the login function to IdP as its configured.

  - Expose `/v2/logout` endpoint:
    - Expose the `/v2/logout` endpoint as a location block here (`openid_connect.server_conf`)
    - Add a map variable of `$oidc_end_session_endpoint` as same as authz and token endpoints here (`openid_connect_configuration.conf`) .
    - Proxy it to the IdP's `end_session_endpoint` to finish the session by IdP.

  - Expose `/v2/_logout` endpoint:
    - Expose `/v2/_logout` endpoint which is a callback from IdP as a location block here (`openid_connect.server_conf`) to handle the following sequences.
      - 1. Redirected by IdP when IdP successfully finished the session.
      - 2. NGINX Plus: Clear session cookies.
      - 3. NGINX Plus: Redirect to either the original landing page or the custom logout page by calling
    - Add a map of `$post_logout_return_uri`: After the successful logout from the IdP, NGINX Plus calls this URI to redirect to either the original page or a custom logout page. The default is original page based on the configuration of `$redirect_base`.

**3. add endpoints in `configure.sh`**

  - IdP's userinfo endpoint
  - IdP's end session endpoint
diff --git a/README.md b/README.md
diff --git a/configure.sh b/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_end_session_endpoint \(.end_session_endpoint)\n$oidc_userinfo_endpoint \(.userinfo_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_end_session_endpoint \$oidc_userinfo_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 ..."
diff --git a/frontend.conf b/frontend.conf
@@ -1,3 +1,16 @@
+# -----------------------------------------------------------------------------#
+#                                                                              #
+#        Sample Reverse Proxy Configuration: Frontend Site, Backend App        #
+#                       (for Open ID Connect workflow)                         #
+#                                                                              #
+# -----------------------------------------------------------------------------#
+
+# -----------------------------------------------------------------------------#
+#                                                                              #
+# 1. Basic Example: Landing page starts OIDC workflow w/o login/logout button. #
+#                                                                              #
+# -----------------------------------------------------------------------------#
+
 # This is the backend application we are protecting with OpenID Connect
 upstream my_backend {
     zone my_backend 64k;
@@ -33,4 +46,106 @@ server {
     }
 }
 
+# -----------------------------------------------------------------------------#
+#                                                                              #
+# 2. Advanced Example: Landing page, login/logout button to handle OIDC kflow  #
+#                                                                              #
+#  - Landing page shows 'login' button                                         #
+#  - 'login' button calls `/login` endpoint to start OIDC flow by validating 
+#    'id_token' w/ IdP's JWK.  #
+#  - Landing page calls `/userinfo` to show user info using 'access_token`.    #
+#  - 'logout' button to be finished OIDC session by IdP.                       #
+#  - API authorization by validating `access_token` w/ IdP's JWK               #
+#                                                                              #
+# -----------------------------------------------------------------------------#
+
+#
+# Upstream server for proxing to the frontend site.
+# - Example of a bundle frontend app to locally test NGINX Plus OIDC workflow.
+#   https://github.com/nginx-openid-connect/nginx-oidc-examples/blob/main/001-oidc-local-test/docker/build-context/nginx/sample/proxy_server_frontend.conf
+#   This link is subject to change.
+# - Modify this configuration to match your frontend site.
+#
+upstream my_frontend_site {
+    zone my_frontend_site 64k;
+    server 127.0.0.1:9091;
+}
+
+#
+# Upstream sample for proxing to the backend API server.
+# - Example of a bundle backend app to locally test an API using access token.
+#   + https://github.com/nginx-openid-connect/nginx-oidc-examples/blob/main/001-oidc-local-test/docker/build-context/nginx/sample/proxy_server_backend.conf
+#   This link is subject to change.
+# - Modify this configuration to match your backend app.
+#
+upstream my_backend_app {
+    zone my_backend_app 64k;
+    server 127.0.0.1:9092;
+}
+
+#
+# Sample Frontend-site & backend-api-server for the OIDC workflow.
+#
+server {
+    # Enable when debugging is needed.
+    error_log  /var/log/nginx/error.log  debug; # Reduce severity level as required
+    access_log /var/log/nginx/access.log main;
+
+    # Replace the following server name with your host name.
+    #
+    # [Example: if you want to locally test OIDC in your laptop]
+    #  - Add '127.0.0.1 nginx.oidc.test` in your `/etc/hosts'.
+    #  - Use the command like 'make start'.
+    #  - Type 'https://nginx.oidc.test' in your browser.
+    #  - You will see the sample landing page and 'Sign In' button.
+    #
+    listen 8020; # Use SSL/TLS in production
+    server_name nginx.oidc.test;
+
+    # Replace the following files with your certificate.
+    ssl_certificate     /etc/ssl/nginx/nginx-repo.crt;
+    ssl_certificate_key /etc/ssl/nginx/nginx-repo.key;
+
+    # OIDC workflow
+    include conf.d/openid_connect.server_conf;  
+
+    #
+    # Frontend example:
+    #
+    #  - Default landing page: no need OIDC workflow to show 'Sign In' button.
+    #  - The site is protected with OpenID Connect(OIDC) by calling the API 
+    #    endpoint of `/login` when users click 'login' button.
+    #
+    location / {
+        proxy_pass http://my_frontend_site;
+        access_log /var/log/nginx/access.log main_jwt;
+    }
+
+    #
+    # Backend API example to interact with proxied backend service:
+    #
+    #  - This API resource is protected by access token which is received by IdP
+    #    after successful signing-in among the frontend site, NGINX Plus and IdP.
+    #
+    #  - To ensure that client requests access the API securely, access token is
+    #    used for API authorization.
+    #    + Most of IdP generate an access token for API authorization of IdP's
+    #      endpoints (like /userinfo) as well as customer's endpoints.
+    #    + But Azure AD generate two types of access token for API authorization
+    #      of Microsoft graph API endpoints and customers' endpoints.
+    #    + Therefore, we recommend that you use $session_jwt for Azure AD and
+    #      $access_token for most of IdPs such as Cognito, Auth0, Keycloak, Okta,
+    #      OneLogin, Ping Identity, etc as for now.
+    #
+    location /v1/api/example {
+        auth_jwt "" token=$access_token;      # Use $session_jwt for Azure AD
+        auth_jwt_key_request /_jwks_uri;      # Enable when using URL
+        #auth_jwt_key_file $oidc_jwt_keyfile; # Enable when using filename
+
+        proxy_set_header Authorization "Bearer $access_token";
+        proxy_pass http://my_backend_app;
+        access_log /var/log/nginx/access.log main_jwt;
+    }
+}
+
 # vim: syntax=nginx
diff --git a/openid_connect.js b/openid_connect.js
@@ -5,7 +5,15 @@
  */
 var newSession = false; // Used by oidcAuth() and validateIdToken()
 
-export default {auth, codeExchange, validateIdToken, logout};
+export default {
+    auth,
+    codeExchange,
+    validateIdToken,
+    logout,
+    v2logout,
+    redirectPostLogin,
+    redirectPostLogout
+};
 
 function retryOriginalRequest(r) {
     delete r.headersOut["WWW-Authenticate"]; // Remove evidence of original failed auth_jwt
@@ -104,6 +112,7 @@ function auth(r, afterSyncCheck) {
                         // ID Token is valid, update keyval
                         r.log("OIDC refresh success, updating id_token for " + r.variables.cookie_auth_token);
                         r.variables.session_jwt = tokenset.id_token; // Update key-value store
+                        r.variables.access_token = tokenset.access_token;
 
                         // Update refresh token (if we got a new one)
                         if (r.variables.refresh_token != tokenset.refresh_token) {
@@ -187,6 +196,7 @@ function codeExchange(r) {
                         // Add opaque token to keyval session store
                         r.log("OIDC success, creating session " + r.variables.request_id);
                         r.variables.new_session = tokenset.id_token; // Create key-value store entry
+                        r.variables.new_access_token = tokenset.access_token;
                         r.headersOut["Set-Cookie"] = "auth_token=" + r.variables.request_id + "; " + r.variables.oidc_cookie_flags;
                         r.return(302, r.variables.redirect_base + r.variables.cookie_auth_redir);
                    }
@@ -256,6 +266,7 @@ function validateIdToken(r) {
 function logout(r) {
     r.log("OIDC logout for " + r.variables.cookie_auth_token);
     r.variables.session_jwt = "-";
+    r.variables.access_token = "-";
     r.variables.refresh_token = "-";
     r.return(302, r.variables.oidc_logout_redirect);
 }
@@ -294,4 +305,69 @@ function idpClientAuth(r) {
     } else {
         return "code=" + r.variables.arg_code + "&client_secret=" + r.variables.oidc_client_secret;
     }   
-}
+}
+
+//
+// Redirect URI after logging in the IDP.
+function redirectPostLogin(r) {
+    r.return(302, r.variables.redirect_base + getIDTokenArgsAfterLogin(r));
+}
+
+//
+// Get query parameter of ID token after sucessful login:
+//
+// - For the variable of `returnTokenToClientOnLogin` of the APIM, this config
+//   is only effective for /login endpoint. By default, our implementation MUST
+//   not return any token back to the client app.
+// - If its configured it can send id_token in the request uri as 
+//   `?id_token=sdfsdfdsfs` after successful login. 
+//
+//
+function getIDTokenArgsAfterLogin(r) {
+    if (r.variables.return_token_to_client_on_login == 'id_token') {
+        return '?id_token=' + r.variables.id_token;
+    }
+    return '';
+}
+
+//
+// RP-Initiated or Custom Logout w/ Idp.
+// 
+// - An RP requests that the Idp log out the end-user by redirecting the
+//   end-user's User Agent to the Idp's Logout endpoint.
+// - TODO: Handle custom logout parameters if Idp doesn't support standard spec
+//         of 'OpenID Connect RP-Initiated Logout 1.0'.
+//
+// - https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout
+// - https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RedirectionAfterLogout
+//
+function v2logout(r) {
+    r.log("OIDC logout for " + r.variables.cookie_auth_token);
+    var idToken = r.variables.session_jwt;
+    var queryParams = getRPInitiatedLogoutArgs(r, idToken);
+
+    r.variables.request_id    = '-';
+    r.variables.session_jwt   = '-';
+    r.variables.access_token  = '-';
+    r.variables.refresh_token = '-';
+    r.return(302, r.variables.oidc_end_session_endpoint + queryParams);
+}
+
+//
+// Get query params for RP-initiated logout:
+//
+// - https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout
+// - https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RedirectionAfterLogout
+//
+function getRPInitiatedLogoutArgs(r, idToken) {
+    return '?post_logout_redirect_uri=' + r.variables.redirect_base
+                                        + r.variables.oidc_logout_redirect_uri +
+           '&id_token_hint='            + idToken;
+}
+
+//
+// Redirect URI after logged-out from the IDP.
+//
+function redirectPostLogout(r) {
+    r.return(302, r.variables.post_logout_return_uri);
+}
diff --git a/openid_connect.server_conf b/openid_connect.server_conf
@@ -1,7 +1,10 @@
     # 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;
+    resolver 8.8.8.8; # For global DNS lookup of IDP endpoint
+        # 127.0.0.11; # For local Docker DNS lookup
+
+    resolver_timeout 10s;
     subrequest_output_buffer_size 32k; # To fit a complete tokenset response
     gunzip on; # Decompress IdP responses if necessary
     # Advanced configuration END
@@ -42,7 +45,7 @@
         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;
-   }
+    }
 
     location = /_refresh {
         # This location is called by oidcAuth() when performing a token refresh. We
@@ -66,6 +69,70 @@
         error_page 500 502 504 @oidc_error;
     }
 
+    #
+    # User information endpoint for the following purposes:
+    # - Browser to periodically check if your are signed-in based on status code.
+    # - Browser to show the signed-in user information.
+    # - https://openid.net/specs/openid-connect-core-1_0.html#UserInfo
+    #
+    location = /userinfo {
+        auth_jwt "" token=$access_token;      # Access token for API authorization
+        #auth_jwt_key_file $oidc_jwt_keyfile; # Enable when using filename
+        auth_jwt_key_request /_jwks_uri;      # Enable when using URL
+
+        proxy_ssl_server_name on;             # For SNI to the IdP
+        proxy_set_header Authorization "Bearer $access_token";
+        proxy_pass       $oidc_userinfo_endpoint;
+        access_log /var/log/nginx/access.log main_jwt;
+    }
+
+    #
+    # Login endpoint to start OIDC flow when a user clicks 'login' button in the
+    # landing page.
+    #
+    location = /login {
+        # This location is called by UI for logging-in IDP using OpenID Connect.
+        auth_jwt "" token=$session_jwt;       # ID token for user authentication.
+        error_page 401 = @do_oidc_flow;
+
+        #auth_jwt_key_file $oidc_jwt_keyfile; # Enable when using filename
+        auth_jwt_key_request /_jwks_uri;      # Enable when using URL
+
+        # Redirect to the the original URI of UI after successful login to IDP.
+        js_content oidc.redirectPostLogin;
+        access_log /var/log/nginx/access.log main_jwt;
+    }
+
+    #
+    # V2 Logout: The following features are added in the NGINX R29.
+    # - The spec of RP-Initiated Logout is added.
+    # - Sample logout page for your OIDC simulation.
+    # - TODO: Custom logout parameters will be separately added.
+    #
+    location = /v2/logout {
+        # This location is called by UI to handle OIDC logout with IDP as per:
+        #  https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout
+        status_zone "OIDC logout";
+        js_content oidc.v2logout;
+    }
+
+    location = /v2/_logout {
+        # This location is the default value of $oidc_logout_redirect_uri (in case
+        # it wasn't configured) called by IdP after closing user session in IdP.
+
+        # 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"; 
+
+        # Redirect to either the original page or custom logout page.
+        js_content oidc.redirectPostLogout;
+    }
+
+    #
+    # V1 Logout (NGINX R28): 
+    # - Need to implement 'RP-Initiated or Custom Logout' by yourselves.
+    #
     location = /logout {
         status_zone "OIDC logout";
         add_header Set-Cookie "auth_token=; $oidc_cookie_flags"; # Send empty cookie
diff --git a/openid_connect_configuration.conf b/openid_connect_configuration.conf
