Access token support

Author: shawnhankim

README.md

@@ -30,6 +30,21 @@ Subsequent requests to protected resources are authenticated by exchanging the s
 
 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/).
 
+### Access Tokens
+The [access tokens](https://openid.net/specs/openid-connect-core-1_0.html#AccessTokenD) are credentials used to access protected resources. If an access token was received from the IdP then it is also stored in the key-value store. To access protected backend, bearer token can be used before calling `proxy_pass` directive as the following example:
+
+```nginx
+    # Bearer token is uses to authorize NGINX to access protected backend
+    proxy_set_header Authorization "Bearer $access_token";
+
+    # Intercept and redirect "401 Unauthorized" proxied responses to nginx
+    # for processing with the error_page directive. Necessary if Access Token
+    # can expire before ID Token.
+    proxy_intercept_errors on;
+
+    proxy_pass http://my_backend; # The backend site/app
+```
+
 ### 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.
@@ -114,6 +129,8 @@ Manual configuration involves reviewing the following files so that they match y
     * Configure the preferred listen port and [enable SSL/TLS configuration](https://docs.nginx.com/nginx/admin-guide/security-controls/terminating-ssl-http/)
     * Modify the severity level of the `error_log` directive to suit the deployment environment
     * 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
+    * Uncomment the `proxy_set_header Authorization "Bearer $access_token"` directive if you want to pass access/bearer token in HTTP header to the protected backend/upstream
+    * Uncoment the `proxy_intercept_errors on` directive if the access token lifetime is less than the ID token lifetime
 
   * **openid_connect.server_conf** - this is the NGINX configuration for handling the various stages of OpenID Connect authorization code flow
     * No changes are usually required here
@@ -128,8 +145,9 @@ Manual configuration involves reviewing the following files so that they match y
 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. This is part of the advanced configuration in **openid_connect_configuration.conf**.
 
 ```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_id_tokens:1M     state=conf.d/oidc_id_tokens.json     timeout=1h;
+keyval_zone zone=oidc_access_tokens:1M state=conf.d/oidc_access_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;
 ```
 
@@ -157,13 +175,15 @@ To delete a single session:
 
 ```shell
 $ curl -iX PATCH -d '{"<session ID>":null}' localhost:8010/api/6/http/keyvals/oidc_id_tokens
+$ curl -iX PATCH -d '{"<session ID>":null}' localhost:8010/api/6/http/keyvals/oidc_access_tokens
 $ curl -iX PATCH -d '{"<session ID>":null}' localhost:8010/api/6/http/keyvals/refresh_tokens
 ```
 
 To delete all sessions:
 
 ```shell
 $ curl -iX DELETE localhost:8010/api/6/http/keyvals/oidc_id_tokens
+$ curl -iX DELETE localhost:8010/api/6/http/keyvals/oidc_access_tokens
 $ curl -iX DELETE localhost:8010/api/6/http/keyvals/refresh_tokens
 ```
 
@@ -223,6 +243,14 @@ proxy_set_header Host <IdP hostname>;
 proxy_ssl_name        <IdP hostname>;
 ```
 
+  * **Invalid access token**
+    * The looping can now happen if the access token is not valid for some reason such that the setup of ID/access tokens expiration is different in the IdP.
+    * In case of this, the backend/upstream can respond with HTTP 401 "Invalid token", and the frontend can restart the flow of OpenID Connect to get new ID token or refresh tokens by calling the following directives.
+```nginx
+        auth_jwt "" token=$session_jwt;
+        error_page 401 = @do_oidc_flow;
+```
+
 ## Support
 
 This reference implementation for OpenID Connect is supported for NGINX Plus subscribers.
@@ -236,3 +264,4 @@ This reference implementation for OpenID Connect is supported for NGINX Plus sub
   * **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.
+  * **R28** Access token support. Added support for access token to authorize NGINX to access protected backend.

frontend.conf

@@ -27,8 +27,17 @@ server {
         # Successfully 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
+
+	    # Bearer token is uses to authorize NGINX to access protected backend
+        #proxy_set_header Authorization "Bearer $access_token";
 
+        # Intercept and redirect "401 Unauthorized" proxied responses to nginx
+        # for processing with the error_page directive. Necessary if Access Token
+        # can expire before ID Token.
+        #proxy_intercept_errors on;
+
+        proxy_pass http://my_backend; # The backend site/app
+
         access_log /var/log/nginx/access.log main_jwt;
     }
 }

openid_connect.js

@@ -104,6 +104,11 @@ 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
+                        if (tokenset.access_token) {
+                            r.variables.access_token = tokenset.access_token;
+                        } else {
+                            r.variables.access_token = "";
+                        }
 
                         // Update refresh token (if we got a new one)
                         if (r.variables.refresh_token != tokenset.refresh_token) {
@@ -187,6 +192,11 @@ 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
+                        if (tokenset.access_token) {
+                            r.variables.new_access_token = tokenset.access_token;
+                        } else {
+                            r.variables.new_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);
                    }
@@ -255,7 +265,8 @@ function validateIdToken(r) {
 
 function logout(r) {
     r.log("OIDC logout for " + r.variables.cookie_auth_token);
-    r.variables.session_jwt = "-";
+    r.variables.session_jwt   = "-";
+    r.variables.access_token  = '-';
     r.variables.refresh_token = "-";
     r.return(302, r.variables.oidc_logout_redirect);
 }

openid_connect_configuration.conf

@@ -87,15 +87,18 @@ map $http_x_forwarded_proto $proto {
 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_id_tokens:1M     state=conf.d/oidc_id_tokens.json     timeout=1h;
+keyval_zone zone=oidc_access_tokens:1M state=conf.d/oidc_access_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;
+keyval $cookie_auth_token $session_jwt   zone=oidc_id_tokens;     # Exchange cookie for JWT
+keyval $cookie_auth_token $access_token  zone=oidc_access_tokens; # Exchange cookie for access token
+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_access_token     zone=oidc_access_tokens;
+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;