|
| 1 | +# JWKS |
| 2 | + |
| 3 | +In this example we deploy a web application, configure load balancing with a VirtualServer, and apply a JWT policy. |
| 4 | +Instead of using a local secret to verify the client request such as in the [jwt](https://github.com/nginxinc/kubernetes-ingress/tree/main/examples/custom-resources/jwt) example, we will define an external Identity Provider (IdP) using the `JwksURI` field. |
| 5 | + |
| 6 | +We will be using a deployment of [KeyCloak](https://www.keycloak.org/) to work as our IdP in this example. |
| 7 | +In this example, KeyCloak is deployed as a single container for the purpose of exposing it with an Ingress Controller. |
| 8 | + |
| 9 | +## Prerequisites |
| 10 | + |
| 11 | +1. Follow the [installation](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) instructions to deploy the Ingress Controller. |
| 12 | + |
| 13 | +2. Save the public IP address of the Ingress Controller into `/etc/hosts` of your machine: |
| 14 | + ``` |
| 15 | + ... |
| 16 | +
|
| 17 | + XXX.YYY.ZZZ.III webapp.example.com |
| 18 | + XXX.YYY.ZZZ.III keycloak.example.com |
| 19 | + ``` |
| 20 | + Here `webapp.example.com` is the domain for the web application and `keycloak.example.com` is the domain for Keycloak. |
| 21 | +
|
| 22 | +## Step 1 - Deploy a TLS Secret |
| 23 | +
|
| 24 | +Create a secret with the TLS certificate and key that will be used for TLS termination of the web application and Keycloak: |
| 25 | +``` |
| 26 | +$ kubectl apply -f tls-secret.yaml |
| 27 | +``` |
| 28 | +
|
| 29 | +## Step 2 - Deploy a Web Application |
| 30 | +
|
| 31 | +Create the application deployment and service: |
| 32 | +``` |
| 33 | +$ kubectl apply -f webapp.yaml |
| 34 | +``` |
| 35 | +
|
| 36 | +## Step 3 - Deploy Keycloak |
| 37 | +
|
| 38 | +1. Create the Keycloak deployment and service: |
| 39 | + ``` |
| 40 | + $ kubectl apply -f keycloak.yaml |
| 41 | + ``` |
| 42 | +1. Create a VirtualServer resource for Keycloak: |
| 43 | + ``` |
| 44 | + $ kubectl apply -f virtual-server-idp.yaml |
| 45 | + ``` |
| 46 | +
|
| 47 | +## Step 4 - Configure Keycloak |
| 48 | +
|
| 49 | +To set up Keycloak: |
| 50 | +1. To connect to Keycloak, use `https://keycloak.example.com`. |
| 51 | +
|
| 52 | +2. Create a new Realm. We will use `jwks-example` for this example. This can be done by selecting the dropdown menu on the left and selecting `Create Realm` |
| 53 | +
|
| 54 | +3. Create a new Client called `jwks-client`. This can be done by selecting the `Client`s tab on the left and then selecting `Create client`. |
| 55 | + - When creating the Client, ensure both `Client authentication` and `Authorization` are enabled. |
| 56 | +
|
| 57 | +4. Once the client is created, navigate to the `Credentials` tab for that client and copy the client secret. |
| 58 | + - This can be saved in the `SECRET` shell variable for later: |
| 59 | + ``` |
| 60 | + export SECRET=<client secret> |
| 61 | + ``` |
| 62 | +
|
| 63 | +5. Create a new User called `jwks-user` by selecting the Users tab on the left and then selecting Create client. |
| 64 | +
|
| 65 | +6. Once the user is created, navigate to the `Credentials` tab for that user and select `Set password`. For this example the password can be whatever you want. |
| 66 | + - This can be saved in the `PASSWORD` shell variable for later: |
| 67 | + ``` |
| 68 | + export PASSWORD=<user password> |
| 69 | + ``` |
| 70 | +
|
| 71 | +## Step 5 - Deploy the JWT Policy |
| 72 | +
|
| 73 | +1. Create a policy with the name `jwt-policy` and configure the `JwksURI` field so that it only permits requests to our web application that contain a valid JWT. |
| 74 | +In the example policy below, replace `<your_realm>` with the realm created in Step 4. We used `jwks-example` as our realm name. |
| 75 | +The value of `spec.jwt.token` is set to `$http_token` in this example as we are sending the client token in an HTTP header. |
| 76 | +``` |
| 77 | +apiVersion: k8s.nginx.org/v1 |
| 78 | +kind: Policy |
| 79 | +metadata: |
| 80 | + name: jwt-policy |
| 81 | +spec: |
| 82 | + jwt: |
| 83 | + realm: MyProductAPI |
| 84 | + token: $http_token |
| 85 | + jwksURI: http://keycloak.default.svc.cluster.local:8080/realms/<your_realm>/protocol/openid-connect/certs |
| 86 | + keyCache: 1h |
| 87 | +``` |
| 88 | +
|
| 89 | +2. Deploy the policy: |
| 90 | +``` |
| 91 | +$ kubectl apply -f jwks.yaml |
| 92 | +``` |
| 93 | +
|
| 94 | +## Step 6 - Deploy a config map with a resolver |
| 95 | +
|
| 96 | +If the value of `jwksURI` uses a hostname, the Ingress Controller will need to reference a resolver. |
| 97 | +This can be done by deploying a ConfigMap with the `resolver-addresses` data field |
| 98 | +``` |
| 99 | +kind: ConfigMap |
| 100 | +apiVersion: v1 |
| 101 | +metadata: |
| 102 | + name: nginx-config |
| 103 | + namespace: nginx-ingress |
| 104 | +data: |
| 105 | + resolver-addresses: <resolver-address> |
| 106 | +``` |
| 107 | +In this example, we create a ConfigMap using Kubernetes' default DNS `kube-dns.kube-system.svc.cluster.local` for the resolver address. For more information on `resolver-addresses` and other related ConfigMap keys, please refer to our documentation [ConfigMap Resource](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/configmap-resource/#summary-of-configmap-keys) and our blog post [Using DNS for Service Discovery with NGINX and NGINX Plus](https://www.nginx.com/blog/dns-service-discovery-nginx-plus) |
| 108 | +
|
| 109 | +NOTE: When setting the value of `jwksURI` in Step 5, the response will differ depending on the IDP used. In some cases the response will be too large for NGINX to properly handle. |
| 110 | +If this occurs you will need to configure the [subrequest_output_buffer_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#subrequest_output_buffer_size) directive in the http context. |
| 111 | +This can currently be done using `http-snippets`. Please refer to our document on [snippets and custom templates](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/configmap-resource/#snippets-and-custom-templates) for details on how to configure this directive. |
| 112 | +
|
| 113 | +The code block below is an example of the updated configmap which adds `subrequest_output_buffer_size` under the http context in the nginx.conf. |
| 114 | +
|
| 115 | +NOTE: The value of `subrequest_output_buffer_size` is only an example value and should be changed to suite your environment. |
| 116 | +``` |
| 117 | +kind: ConfigMap |
| 118 | +apiVersion: v1 |
| 119 | +metadata: |
| 120 | + name: nginx-config |
| 121 | + namespace: nginx-ingress |
| 122 | +data: |
| 123 | + resolver-addresses: <resolver-address> |
| 124 | + http-snippets: | |
| 125 | + subrequest_output_buffer_size 64k; |
| 126 | +``` |
| 127 | +
|
| 128 | +``` |
| 129 | +$ kubectl apply -f nginx-config.yaml |
| 130 | +``` |
| 131 | +
|
| 132 | +## Step 7 - Configure Load Balancing |
| 133 | +
|
| 134 | +Create a VirtualServer resource for the web application: |
| 135 | +``` |
| 136 | +$ kubectl apply -f virtual-server.yaml |
| 137 | +``` |
| 138 | +
|
| 139 | +Note that the VirtualServer references the policy `jwt-policy` created in Step 5. |
| 140 | +
|
| 141 | +## Step 8 - Get the client token |
| 142 | +
|
| 143 | +For the client to have permission to send requests to the web application they must send a Bearer token to the application. |
| 144 | +To get this token, run the following `curl` command: |
| 145 | +``` |
| 146 | +$ export TOKEN=$(curl -k -L -X POST 'https://keycloak.example.com/realms/jwks-example/protocol/openid-connect/token' \ |
| 147 | +-H 'Content-Type: application/x-www-form-urlencoded' \ |
| 148 | +--data-urlencode grant_type=password \ |
| 149 | +--data-urlencode scope=openid \ |
| 150 | +--data-urlencode client_id=jwks-client \ |
| 151 | +--data-urlencode client_secret=$SECRET \ |
| 152 | +--data-urlencode username=jwks-user \ |
| 153 | +--data-urlencode password=$PASSWORD \ |
| 154 | +| jq -r .access_token) |
| 155 | +``` |
| 156 | +
|
| 157 | +This command will save the token in the `TOKEN` shell variable. |
| 158 | +
|
| 159 | +## Step 9 - Test the Configuration |
| 160 | +
|
| 161 | +If you attempt to access the application without providing the bearer token, NGINX will reject your requests for that VirtualServer: |
| 162 | +``` |
| 163 | +$ curl -H 'Accept: application/json' webapp.example.com |
| 164 | +<html> |
| 165 | +<head><title>401 Authorization Required</title></head> |
| 166 | +<body> |
| 167 | +<center><h1>401 Authorization Required</h1></center> |
| 168 | +<hr><center>nginx/1.23.2</center> |
| 169 | +</body> |
| 170 | +</html> |
| 171 | +``` |
| 172 | +
|
| 173 | +If a valid bearer token is provided, the request will succeed: |
| 174 | +``` |
| 175 | +$ curl -H 'Accept: application/json' -H "token: ${TOKEN}" webapp.example.com |
| 176 | +Server address: 10.42.0.7:8080 |
| 177 | +Server name: webapp-5c6fdbcbf9-pt9tp |
| 178 | +Date: 13/Dec/2022:14:50:33 +0000 |
| 179 | +URI: / |
| 180 | +Request ID: f1241390ac51318afa4fcc39d2341359 |
| 181 | +``` |
![pre-commit-ci[bot]](https://avatars.githubusercontent.com/in/68672?v=4&size=40){kind=avatar}
0 commit comments