From 90406970f5c9f70735f4cbea0cbf9f379888401e Mon Sep 17 00:00:00 2001 From: Michael Pleshakov Date: Fri, 2 Oct 2020 08:20:29 -0700 Subject: [PATCH] Document variables in Action.Proxy headers Co-authored-by: Jodie Putrino --- docs-web/configuration/policy-resource.md | 31 ++++++++++ ...server-and-virtualserverroute-resources.md | 56 +++++++++++++++---- 2 files changed, 76 insertions(+), 11 deletions(-) diff --git a/docs-web/configuration/policy-resource.md b/docs-web/configuration/policy-resource.md index 084279680b..0c61b7fa26 100644 --- a/docs-web/configuration/policy-resource.md +++ b/docs-web/configuration/policy-resource.md @@ -216,6 +216,23 @@ jwt: token: $http_token ``` +You can pass the JWT claims and JOSE headers to the upstream servers. For example: +```yaml +action: + proxy: + upstream: webapp + requestHeaders: + set: + - name: user + value: ${jwt_claim_user} + - name: alg + value: ${jwt_header_alg} +``` +We use the `requestHeaders` of the [Action.Proxy](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/#action-proxy) to set the values of two headers that NGINX will pass to the upstream servers. + +The value of the `${jwt_claim_user}` variable is the `user` claim of a JWT. For other claims, use `${jwt_claim_name}`, where `name` is the name of the claim. Note that nested claims and claims that include a period (`.`) are not supported. Similarly, use `${jwt_header_name}` where `name` is the name of a header. In our example, we use the `alg` header. + + > Note: The feature is implemented using the NGINX Plus [ngx_http_auth_jwt_module](https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html). ```eval_rst @@ -268,6 +285,20 @@ A VirtualServer that references an IngressMTLS policy must: If the conditions above are not met, NGINX will send `500` error response to clients. +You can pass the client certificate details, including the certificate, to the upstream servers. For example: +```yaml +action: + proxy: + upstream: webapp + requestHeaders: + set: + - name: client-cert-subj-dn + value: ${ssl_client_s_dn} # subject DN + - name: client-cert + value: ${ssl_client_escaped_cert} # client certificate in the PEM format (urlencoded) +``` +We use the `requestHeaders` of the [Action.Proxy](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/#action-proxy) to set the values of the two headers that NGINX will pass to the upstream servers. See the [list of embedded variables](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#variables) that are supported by the `ngx_http_ssl_module`, which you can use to pass the client certificate details. + > Note: The feature is implemented using the NGINX [ngx_http_ssl_module](https://nginx.org/en/docs/http/ngx_http_ssl_module.html). ```eval_rst diff --git a/docs-web/configuration/virtualserver-and-virtualserverroute-resources.md b/docs-web/configuration/virtualserver-and-virtualserverroute-resources.md index ed349c9ba6..ed7869324e 100644 --- a/docs-web/configuration/virtualserver-and-virtualserverroute-resources.md +++ b/docs-web/configuration/virtualserver-and-virtualserverroute-resources.md @@ -816,7 +816,7 @@ redirect: - Type - Required * - ``url`` - - The URL to redirect the request to. Supported NGINX variables: ``$scheme``\ , ``$http_x_forwarded_proto``\ , ``$request_uri``\ , ``$host``. Variables must be inclosed in curly braces. For example: ``${host}${request_uri}``. + - The URL to redirect the request to. Supported NGINX variables: ``$scheme``\ , ``$http_x_forwarded_proto``\ , ``$request_uri``\ , ``$host``. Variables must be enclosed in curly braces. For example: ``${host}${request_uri}``. - ``string`` - Yes * - ``code`` @@ -854,7 +854,7 @@ return: - ``string`` - No * - ``body`` - - The body of the response. Supports NGINX variables*. Variables must be inclosed in curly brackets. For example: ``Request is ${request_uri}\n``. + - The body of the response. Supports NGINX variables*. Variables must be enclosed in curly brackets. For example: ``Request is ${request_uri}\n``. - ``string`` - Yes ``` @@ -874,10 +874,14 @@ proxy: set: - name: My-Header value: Value + - name: Client-Cert + value: ${ssl_client_escaped_cert} responseHeaders: add: - name: My-Header value: Value + - name: IC-Nginx-Version + value: ${nginx_version} always: true hide: - x-internal-version @@ -933,10 +937,38 @@ The RequestHeaders field modifies the headers of the request to the proxied upst - No * - ``set`` - Allows redefining or appending fields to present request headers passed to the proxied upstream servers. See the `proxy_set_header `_ directive for more information. - - `[]header <#header>`_ + - `[]header <#action-proxy-requestheaders-set-header>`_ + - No +``` + +### Action.Proxy.RequestHeaders.Set.Header + +The header defines an HTTP Header: +```yaml +name: My-Header +value: My-Value +``` + +```eval_rst +.. list-table:: + :header-rows: 1 + + * - Field + - Description + - Type + - Required + * - ``name`` + - The name of the header. + - ``string`` + - Yes + * - ``value`` + - The value of the header. Supports NGINX variables*. Variables must be enclosed in curly brackets. For example: ``${scheme}``. + - ``string`` - No ``` +\* -- Supported NGINX variables: `$request_uri`, `$request_method`, `$request_body`, `$scheme`, `$http_`, `$args`, `$arg_`, `$cookie_`, `$host`, `$request_time`, `$request_length`, `$nginx_version`, `$pid`, `$connection`, `$remote_addr`, `$remote_port`, `$time_iso8601`, `$time_local`, `$server_addr`, `$server_port`, `$server_name`, `$server_protocol`, `$connections_active`, `$connections_reading`, `$connections_writing`, `$connections_waiting`, `$ssl_cipher`, `$ssl_ciphers`, `$ssl_client_cert`, `$ssl_client_escaped_cert`, `$ssl_client_fingerprint`, `$ssl_client_i_dn`, `$ssl_client_i_dn_legacy`, `$ssl_client_raw_cert`, `$ssl_client_s_dn`, `$ssl_client_s_dn_legacy`, `$ssl_client_serial`, `$ssl_client_v_end`, `$ssl_client_v_remain`, `$ssl_client_v_start`, `$ssl_client_verify`, `$ssl_curves`, `$ssl_early_data`, `$ssl_protocol`, `$ssl_server_name`, `$ssl_session_id`, `$ssl_session_reused`, `$jwt_claim_` (NGINX Plus only) and `$jwt_header_` (NGINX Plus only). + ### Action.Proxy.ResponseHeaders The ResponseHeaders field modifies the headers of the response to the client. @@ -975,8 +1007,8 @@ The ResponseHeaders field modifies the headers of the response to the client. The addHeader defines an HTTP Header with an optional `always` field: ```yaml -name: Host -value: example.com +name: My-Header +value: My-Value always: true ``` @@ -993,16 +1025,18 @@ always: true - ``string`` - Yes * - ``value`` - - The value of the header. + - The value of the header. Supports NGINX variables*. Variables must be enclosed in curly brackets. For example: ``${scheme}``. - ``string`` - No * - ``always`` - - If set to true, add the header regardless of the response status code*. Default is false. See the `add_header `_ directive for more information. + - If set to true, add the header regardless of the response status code**. Default is false. See the `add_header `_ directive for more information. - ``bool`` - No ``` -\* -- If `always` is false, the response header is added only if the response status code is any of `200`, `201`, `204`, `206`, `301`, `302`, `303`, `304`, `307` or `308`. +\* -- Supported NGINX variables: `$request_uri`, `$request_method`, `$request_body`, `$scheme`, `$http_`, `$args`, `$arg_`, `$cookie_`, `$host`, `$request_time`, `$request_length`, `$nginx_version`, `$pid`, `$connection`, `$remote_addr`, `$remote_port`, `$time_iso8601`, `$time_local`, `$server_addr`, `$server_port`, `$server_name`, `$server_protocol`, `$connections_active`, `$connections_reading`, `$connections_writing`, `$connections_waiting`, `$ssl_cipher`, `$ssl_ciphers`, `$ssl_client_cert`, `$ssl_client_escaped_cert`, `$ssl_client_fingerprint`, `$ssl_client_i_dn`, `$ssl_client_i_dn_legacy`, `$ssl_client_raw_cert`, `$ssl_client_s_dn`, `$ssl_client_s_dn_legacy`, `$ssl_client_serial`, `$ssl_client_v_end`, `$ssl_client_v_remain`, `$ssl_client_v_start`, `$ssl_client_verify`, `$ssl_curves`, `$ssl_early_data`, `$ssl_protocol`, `$ssl_server_name`, `$ssl_session_id`, `$ssl_session_reused`, `$jwt_claim_` (NGINX Plus only) and `$jwt_header_` (NGINX Plus only). + +\*\* -- If `always` is false, the response header is added only if the response status code is any of `200`, `201`, `204`, `206`, `301`, `302`, `303`, `304`, `307` or `308`. ### Split @@ -1219,7 +1253,7 @@ redirect: - ``int`` - No * - ``url`` - - The URL to redirect the request to. Supported NGINX variables: ``$scheme``\ and ``$http_x_forwarded_proto``\. Variables must be inclosed in curly braces. For example: ``${scheme}``. + - The URL to redirect the request to. Supported NGINX variables: ``$scheme``\ and ``$http_x_forwarded_proto``\. Variables must be enclosed in curly braces. For example: ``${scheme}``. - ``string`` - Yes ``` @@ -1259,7 +1293,7 @@ return: - ``string`` - No * - ``body`` - - The body of the response. Supported NGINX variable: ``$upstream_status`` \ . Variables must be inclosed in curly braces. For example: ``${upstream_status}``. + - The body of the response. Supported NGINX variable: ``$upstream_status`` \ . Variables must be enclosed in curly braces. For example: ``${upstream_status}``. - ``string`` - Yes * - ``headers`` @@ -1290,7 +1324,7 @@ value: ${upstream_status} - ``string`` - Yes * - ``value`` - - The value of the header. Supported NGINX variable: ``$upstream_status`` \ . Variables must be inclosed in curly braces. For example: ``${upstream_status}``. + - The value of the header. Supported NGINX variable: ``$upstream_status`` \ . Variables must be enclosed in curly braces. For example: ``${upstream_status}``. - ``string`` - No ```