From ddfec9d970c17200c6ff1e63bdb87608c16c27aa Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Mon, 19 Jun 2023 16:53:28 +0100 Subject: [PATCH 1/7] Add document to tutorial section for configuring the default oidc implementation --- .../tutorials/oidc-custom-configuration.md | 199 ++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 docs/content/tutorials/oidc-custom-configuration.md diff --git a/docs/content/tutorials/oidc-custom-configuration.md b/docs/content/tutorials/oidc-custom-configuration.md new file mode 100644 index 0000000000..81217c155c --- /dev/null +++ b/docs/content/tutorials/oidc-custom-configuration.md @@ -0,0 +1,199 @@ +--- +title: NGINX Ingress Controller and Open Service Mesh +description: | + Use NGINX Ingress Controller with Open Service Mesh. +weight: 1800 +doctypes: ["concept"] +toc: true +docs: "DOCS-1181" +--- + +# OIDC Custom Configuration + +The F5 NGINX Ingress Controller implements OpenID Connect (OIDC) using the NGINX OpenID Connect Reference implementation: [nginx-openid-connect](https://github.com/nginxinc/nginx-openid-connect). + +This guide will walk through how to customise and configure this default implementation. + +## Prerequisites +This guide assumes that you have an F5 NGINX Ingress Controller deployed. If not, please follow the installation steps using either the [Manifest](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) or [HELM](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) approach. + +To customise the NGINX OpenID Connect Reference implementation, we will need to: +1. Create a ConfigMap containing the contents of the default `oidc.conf` file +2. Attach a `Volume` and `VolumeMount` to our deployment of the F5 NGINX Ingress Controller + +This setup will allow our custom configuration in our ConfigMap to override the contents of the default `oidc.conf` file. + +## Step 1 - Creating the ConfigMap + +Run the below command to generate a ConfgMap with the contents of the `oidc.conf` file. +**NOTE** The ConfgMap must be deployed in the same `namespace` as the F5 NGINX Ingress Controller. +``` +kubectl create configmap oidc-config-map --from-literal=oidc.conf="$(curl -k https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/internal/configs/oidc/oidc.conf)" +``` + +Use the `kubectl describe` command to confirm the contents of the ConfigMap are correct + +``` +kubectl describe configmap oidc-config-map +``` + +``` +Name: oidc-config-map +Namespace: default +Labels: +Annotations: + +Data +==== +oidc.conf: +---- + # 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; + subrequest_output_buffer_size 32k; # To fit a complete tokenset response + gunzip on; # Decompress IdP responses if necessary + # Advanced configuration END + + ... + # Rest of config ammended +``` + +## Step 2 - Customising the default configuration +Once the contents of the `oidc.conf` file has been added to the ConfigMap, you are free to customise the contents of this ConfigMap. +In this example, we will add a comment to the top of the file to demonstrate it is overwriting the default contents. +This comment will be `# >> Custom Comment for my OIDC file <<` + +``` +kubectl edit configmap oidc-config-map +``` + +Add the custom content: +``` +# Please edit the object below. Lines beginning with a '#' will be ignored, +# and an empty file will abort the edit. If an error occurs while saving this file will be +# reopened with the relevant failures. +# +apiVersion: v1 +data: + oidc.conf: |2- + # >> Custom Comment for my OIDC file << + # 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; + subrequest_output_buffer_size 32k; # To fit a complete tokenset response + gunzip on; # Decompress IdP responses if necessary + # Advanced configuration END + + ... + # Rest of config ammended +``` +> **IMPORTANT** +> +> In Step 3 we will deploy/update an Ingress Controller that will use this ConfigMap. Any changes made to this ConfigMap must be made **before** deploying/updating the Ingress Controller. If an update is applied to the ConfigMap after the Ingress Controller is deployed, it will not get applied. Applying any updates to the data in this ConfigMap will require the Ingress Controller to be re-deployed. + +## Step 3 - Add Volume and VolumeMount to the Ingress Controller deployment + +In this step we will add a `Volume` and `VolumeMount` to our Ingress Controller deployment. +This will allow us to mount the ConfigMap created in Step 1 and over write the contents of the `oidc.conf` file. + +This document will demonstrate how to add the `Volume` and `VolumeMount` using both Manifest and HELM + +### Manifest + +The below configuration shows where the `Volume` and `VolumeMount` can be added to your Deployment/Daemonset file. + +The `VolumeMount` must be added the `spec.template.spec.containers` section. + +The `Volume` must be added the `spec.template.spec` section: +``` +apiVersion: apps/v1 +kind: +metadata: + name: + namespace: +spec: + ... + ... + template: + ... + ... + spec: + ... + ... + volumes: + - name: oidc-volume + configMap: + name: # Must match the name of the ConfigMap + containers: + ... + ... + volumeMounts: + - name: oidc-volume + mountPath: /etc/nginx/oidc/oidc.conf + subPath: oidc.conf # Must match the name in the data filed + readOnly: true +``` + +Once the `Volume` and `VolumeMount` has been added the manifest file, apply the changes do the Ingress Controller deployment. + +Confirm the `oidc.conf` file has been updated: +``` +kubectl exec -it -n -- cat /etc/nginx/oidc/oidc.conf +``` + +### HELM + +Deployments using HELM will need to edit their existing +Edit your Ingress Controller Deployment/Daemonset yaml to include a `Volume` and `VolumeMount`. + +The `Volume` should be within the `spec.template.spec` section. + +The `VolumeMount `must be added the `spec.template.spec.containers` section. + +For Deployments: +``` +kubectl edit deployments -n +``` + +For Daemonsets: +``` +kubectl edit daemonset -n +``` + +``` +apiVersion: apps/v1 +kind: +metadata: + name: + namespace: +spec: + ... + ... + template: + ... + ... + spec: + ... + ... + volumes: + - name: oidc-volume + configMap: + name: # Must match the name of the ConfigMap + containers: + ... + ... + volumeMounts: + - name: oidc-volume + mountPath: /etc/nginx/oidc/oidc.conf + subPath: oidc.conf # Must match the name in the data filed + readOnly: true +``` + +Once the Deployment/Daemonset has been edited, save the file and exit. + +Confirm the `oidc.conf` file has been updated: +``` +kubectl exec -it -n -- cat /etc/nginx/oidc/oidc.conf +``` From 785ebd721f786d3b12861dec360930d6fa39e276 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 19 Jun 2023 15:56:24 +0000 Subject: [PATCH 2/7] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/content/tutorials/oidc-custom-configuration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/content/tutorials/oidc-custom-configuration.md b/docs/content/tutorials/oidc-custom-configuration.md index 81217c155c..92139aac76 100644 --- a/docs/content/tutorials/oidc-custom-configuration.md +++ b/docs/content/tutorials/oidc-custom-configuration.md @@ -54,7 +54,7 @@ oidc.conf: subrequest_output_buffer_size 32k; # To fit a complete tokenset response gunzip on; # Decompress IdP responses if necessary # Advanced configuration END - + ... # Rest of config ammended ``` @@ -85,12 +85,12 @@ data: subrequest_output_buffer_size 32k; # To fit a complete tokenset response gunzip on; # Decompress IdP responses if necessary # Advanced configuration END - + ... # Rest of config ammended ``` > **IMPORTANT** -> +> > In Step 3 we will deploy/update an Ingress Controller that will use this ConfigMap. Any changes made to this ConfigMap must be made **before** deploying/updating the Ingress Controller. If an update is applied to the ConfigMap after the Ingress Controller is deployed, it will not get applied. Applying any updates to the data in this ConfigMap will require the Ingress Controller to be re-deployed. ## Step 3 - Add Volume and VolumeMount to the Ingress Controller deployment From 0061a31bea04f5e56b28bccdecc9efccc26f2836 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Tue, 20 Jun 2023 09:24:54 +0100 Subject: [PATCH 3/7] Fix spelling and grammer errors --- .../tutorials/oidc-custom-configuration.md | 35 +++++++++---------- 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/docs/content/tutorials/oidc-custom-configuration.md b/docs/content/tutorials/oidc-custom-configuration.md index 92139aac76..d670dee006 100644 --- a/docs/content/tutorials/oidc-custom-configuration.md +++ b/docs/content/tutorials/oidc-custom-configuration.md @@ -5,7 +5,6 @@ description: | weight: 1800 doctypes: ["concept"] toc: true -docs: "DOCS-1181" --- # OIDC Custom Configuration @@ -17,21 +16,21 @@ This guide will walk through how to customise and configure this default impleme ## Prerequisites This guide assumes that you have an F5 NGINX Ingress Controller deployed. If not, please follow the installation steps using either the [Manifest](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) or [HELM](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) approach. -To customise the NGINX OpenID Connect Reference implementation, we will need to: +To customise the NGINX OpenID Connect Reference implementation, you will need to: 1. Create a ConfigMap containing the contents of the default `oidc.conf` file -2. Attach a `Volume` and `VolumeMount` to our deployment of the F5 NGINX Ingress Controller +2. Attach a `Volume` and `VolumeMount` to your deployment of the F5 NGINX Ingress Controller -This setup will allow our custom configuration in our ConfigMap to override the contents of the default `oidc.conf` file. +This setup will allow the custom configuration in your ConfigMap to override the contents of the default `oidc.conf` file. ## Step 1 - Creating the ConfigMap -Run the below command to generate a ConfgMap with the contents of the `oidc.conf` file. -**NOTE** The ConfgMap must be deployed in the same `namespace` as the F5 NGINX Ingress Controller. +Run the below command to generate a ConfigMap with the contents of the `oidc.conf` file. +**NOTE** The ConfigMap must be deployed in the same `namespace` as the F5 NGINX Ingress Controller. ``` kubectl create configmap oidc-config-map --from-literal=oidc.conf="$(curl -k https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/internal/configs/oidc/oidc.conf)" ``` -Use the `kubectl describe` command to confirm the contents of the ConfigMap are correct +Use the `kubectl describe` command to confirm the contents of the ConfigMap are correct. ``` kubectl describe configmap oidc-config-map @@ -56,12 +55,12 @@ oidc.conf: # Advanced configuration END ... - # Rest of config ammended + # Rest of configuration file truncated ``` ## Step 2 - Customising the default configuration Once the contents of the `oidc.conf` file has been added to the ConfigMap, you are free to customise the contents of this ConfigMap. -In this example, we will add a comment to the top of the file to demonstrate it is overwriting the default contents. +This example demonstrates adding a comment to the top of the file. This comment will be shown at the top of the `oidc.conf` file. This comment will be `# >> Custom Comment for my OIDC file <<` ``` @@ -87,16 +86,16 @@ data: # Advanced configuration END ... - # Rest of config ammended + # Rest of configuration file truncated ``` > **IMPORTANT** -> -> In Step 3 we will deploy/update an Ingress Controller that will use this ConfigMap. Any changes made to this ConfigMap must be made **before** deploying/updating the Ingress Controller. If an update is applied to the ConfigMap after the Ingress Controller is deployed, it will not get applied. Applying any updates to the data in this ConfigMap will require the Ingress Controller to be re-deployed. +> +> In Step 3 an NGINX Ingress Controller will be deployed/updated that will use this ConfigMap. Any changes made to this ConfigMap must be made **before** deploying/updating the NGINX Ingress Controller. If an update is applied to the ConfigMap after the NGINX Ingress Controller is deployed, it will not get applied. Applying any updates to the data in this ConfigMap will require the NGINX Ingress Controller to be re-deployed. ## Step 3 - Add Volume and VolumeMount to the Ingress Controller deployment -In this step we will add a `Volume` and `VolumeMount` to our Ingress Controller deployment. -This will allow us to mount the ConfigMap created in Step 1 and over write the contents of the `oidc.conf` file. +In this step we will add a `Volume` and `VolumeMount` to the NGINX Ingress Controller deployment. +This will allow you to mount the ConfigMap created in Step 1 and overwrite the contents of the `oidc.conf` file. This document will demonstrate how to add the `Volume` and `VolumeMount` using both Manifest and HELM @@ -136,17 +135,17 @@ spec: readOnly: true ``` -Once the `Volume` and `VolumeMount` has been added the manifest file, apply the changes do the Ingress Controller deployment. +Once the `Volume` and `VolumeMount` has been added the manifest file, apply the changes to the Ingress Controller deployment. Confirm the `oidc.conf` file has been updated: ``` kubectl exec -it -n -- cat /etc/nginx/oidc/oidc.conf ``` -### HELM +### Helm -Deployments using HELM will need to edit their existing -Edit your Ingress Controller Deployment/Daemonset yaml to include a `Volume` and `VolumeMount`. +Deployments using helm will need to edit their existing +Edit the NGINX Ingress Controller Deployment/Daemonset yaml to include a `Volume` and `VolumeMount`. The `Volume` should be within the `spec.template.spec` section. From 601435edcb985c46a0efc31e74815eb85322036c Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 20 Jun 2023 08:26:09 +0000 Subject: [PATCH 4/7] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/content/tutorials/oidc-custom-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/tutorials/oidc-custom-configuration.md b/docs/content/tutorials/oidc-custom-configuration.md index d670dee006..636dfe430a 100644 --- a/docs/content/tutorials/oidc-custom-configuration.md +++ b/docs/content/tutorials/oidc-custom-configuration.md @@ -89,7 +89,7 @@ data: # Rest of configuration file truncated ``` > **IMPORTANT** -> +> > In Step 3 an NGINX Ingress Controller will be deployed/updated that will use this ConfigMap. Any changes made to this ConfigMap must be made **before** deploying/updating the NGINX Ingress Controller. If an update is applied to the ConfigMap after the NGINX Ingress Controller is deployed, it will not get applied. Applying any updates to the data in this ConfigMap will require the NGINX Ingress Controller to be re-deployed. ## Step 3 - Add Volume and VolumeMount to the Ingress Controller deployment From 1c4b21ca2dd4480a1f43f29ecb902593b76f316d Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Tue, 20 Jun 2023 09:27:12 +0100 Subject: [PATCH 5/7] Correct indentation --- docs/content/tutorials/oidc-custom-configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/tutorials/oidc-custom-configuration.md b/docs/content/tutorials/oidc-custom-configuration.md index 636dfe430a..d604b05843 100644 --- a/docs/content/tutorials/oidc-custom-configuration.md +++ b/docs/content/tutorials/oidc-custom-configuration.md @@ -55,7 +55,7 @@ oidc.conf: # Advanced configuration END ... - # Rest of configuration file truncated + # Rest of configuration file truncated ``` ## Step 2 - Customising the default configuration @@ -86,7 +86,7 @@ data: # Advanced configuration END ... - # Rest of configuration file truncated + # Rest of configuration file truncated ``` > **IMPORTANT** > From a38f5f5cb7e2ef17984c540351001c15f81a61d4 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Tue, 20 Jun 2023 10:39:27 +0100 Subject: [PATCH 6/7] Update title and desription --- docs/content/tutorials/oidc-custom-configuration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/content/tutorials/oidc-custom-configuration.md b/docs/content/tutorials/oidc-custom-configuration.md index d604b05843..d42c72c4e1 100644 --- a/docs/content/tutorials/oidc-custom-configuration.md +++ b/docs/content/tutorials/oidc-custom-configuration.md @@ -1,13 +1,13 @@ --- -title: NGINX Ingress Controller and Open Service Mesh +title: Customise OIDC Configuration with NGINX Ingress Controller description: | - Use NGINX Ingress Controller with Open Service Mesh. + How to Customise the default OIDC Configuration with NGINX Ingress Controller weight: 1800 doctypes: ["concept"] toc: true --- -# OIDC Custom Configuration +# Overview The F5 NGINX Ingress Controller implements OpenID Connect (OIDC) using the NGINX OpenID Connect Reference implementation: [nginx-openid-connect](https://github.com/nginxinc/nginx-openid-connect). From 8a4cbd8dfa5fc9d383a32351b3df2787fa110970 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Tue, 20 Jun 2023 10:47:48 +0100 Subject: [PATCH 7/7] Fix grammer --- docs/content/tutorials/oidc-custom-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/tutorials/oidc-custom-configuration.md b/docs/content/tutorials/oidc-custom-configuration.md index d42c72c4e1..35b8acb7c7 100644 --- a/docs/content/tutorials/oidc-custom-configuration.md +++ b/docs/content/tutorials/oidc-custom-configuration.md @@ -60,7 +60,7 @@ oidc.conf: ## Step 2 - Customising the default configuration Once the contents of the `oidc.conf` file has been added to the ConfigMap, you are free to customise the contents of this ConfigMap. -This example demonstrates adding a comment to the top of the file. This comment will be shown at the top of the `oidc.conf` file. +This example demonstrates adding a comment to the top of the file. The comment will be shown at the top of the `oidc.conf` file. This comment will be `# >> Custom Comment for my OIDC file <<` ```