Skip to content

Commit

Permalink
Adds JWT Authn User Docs (#991)
Browse files Browse the repository at this point in the history
Signed-off-by: danehans <daneyonhansen@gmail.com>
  • Loading branch information
danehans committed Feb 8, 2023
1 parent 1b26380 commit 2a431c1
Show file tree
Hide file tree
Showing 6 changed files with 157 additions and 0 deletions.
13 changes: 13 additions & 0 deletions docs/latest/dev/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,14 @@ Now you are able to view the running Envoy configuration by navigating to `127.0

There are many other endpoints on the [Envoy admin interface][] that may be helpful when debugging.

### JWT Testing

An example [JSON Web Token (JWT)][jwt] and [JSON Web Key Set (JWKS)][jwks] are used for the [request authentication][]
user guide. The JWT was created by the [JWT Debugger][], using the `RS256` algorithm. The public key from the JWTs
verify signature was copied to [JWK Creator][] for generating the JWK. The JWK Creator was configured with matching
settings, i.e. `Signing` public key use and the `RS256` algorithm. The generated JWK was wrapped in a JWKS structure
and is hosted in the repo.

[Quickstart]: https://github.com/envoyproxy/gateway/blob/main/docs/user/quickstart.md
[make]: https://www.gnu.org/software/make/
[Github Actions]: https://docs.github.com/en/actions
Expand All @@ -137,3 +145,8 @@ There are many other endpoints on the [Envoy admin interface][] that may be help
[gateway-dev]: https://hub.docker.com/r/envoyproxy/gateway-dev/tags
[mac_connect]: https://github.com/chipmk/docker-mac-net-connect
[Envoy admin interface]: https://www.envoyproxy.io/docs/envoy/latest/operations/admin#operations-admin-interface
[jwt]: https://tools.ietf.org/html/rfc7519
[jwks]: https://tools.ietf.org/html/rfc7517
[request authentication]: https://gateway.envoyproxy.io/latest/user/authn.html
[JWT Debugger]: https://jwt.io/
[JWK Creator]: https://russelldavies.github.io/jwk-creator/
94 changes: 94 additions & 0 deletions docs/latest/user/authn.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
# Request Authentication

This guide provides instructions for configuring [JSON Web Token (JWT)][jwt] authentication. JWT authentication checks
if an incoming request has a valid JWT before routing the request to a backend service. Currently, Envoy Gateway only
supports validating a JWT from an HTTP header, e.g. `Authorization: Bearer <token>`.

## Installation

Follow the steps from the [Quickstart](quickstart.md) guide to install Envoy Gateway and the example manifest.
Before proceeding, you should be able to query the example backend using HTTP.

## Configuration

Allow requests with a valid JWT by creating an [AuthenticationFilter][] and referencing it from the example HTTPRoute.

```shell
kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/authn/jwt.yaml
```

The HTTPRoute is now updated to authenticate requests for `/foo` and allow unauthenticated requests to `/bar`. The
`/foo` route rule references an AuthenticationFilter that provides the JWT authentication configuration.

Verify the HTTPRoute configuration and status:

```shell
kubectl get httproute/backend -o yaml
```

The AuthenticationFilter is configured for JWT authentication and uses a single [JSON Web Key Set (JWKS)][jwks]
provider for authenticating the JWT.

Verify the AuthenticationFilter configuration:

```shell
kubectl get authenticationfilter/jwt-example -o yaml
```

## Testing

Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](quickstart.md) guide is set. If not, follow the
Quickstart instructions to set the variable.

```shell
echo $GATEWAY_HOST
```

Verify that requests to `/foo` are denied without a JWT:

```shell
curl -sS -o /dev/null -H "Host: www.example.com" -w "%{http_code}\n" http://$GATEWAY_HOST/foo
```

A `401` HTTP response code should be returned.

Get the JWT used for testing request authentication:

```shell
TOKEN=$(curl https://raw.githubusercontent.com/envoyproxy/gateway/main/examples/kubernetes/authn/test.jwt -s) && echo "$TOKEN" | cut -d '.' -f2 - | base64 --decode -
```

__Note:__ The above command decodes and returns the token's payload. You can replace `f2` with `f1` to view the token's
header.

Verify that a request to `/foo` with a valid JWT is allowed:

```shell
curl -sS -o /dev/null -H "Host: www.example.com" -H "Authorization: Bearer $TOKEN" -w "%{http_code}\n" http://$GATEWAY_HOST/foo
```

A `200` HTTP response code should be returned.

Verify that requests to `/bar` are allowed __without__ a JWT:

```shell
curl -sS -o /dev/null -H "Host: www.example.com" -w "%{http_code}\n" http://$GATEWAY_HOST/bar
```

## Clean-Up

Follow the steps from the [Quickstart](quickstart.md) guide to uninstall Envoy Gateway and the example manifest.

Delete the AuthenticationFilter:

```shell
kubectl delete authenticationfilter/jwt-example
```

## Next Steps

Checkout the [Developer Guide](../dev/README.md) to get involved in the project.

[jwt]: https://tools.ietf.org/html/rfc7519
[AuthenticationFilter]: https://github.com/envoyproxy/gateway/blob/main/api/v1alpha1/authenticationfilter_types.go
[jwks]: https://tools.ietf.org/html/rfc7517
1 change: 1 addition & 0 deletions docs/latest/user_docs.rst
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,4 @@ Learn how to deploy, use, and operate Envoy Gateway.
user/tcp-routing
user/udp-routing
user/grpc-routing
user/authn
1 change: 1 addition & 0 deletions examples/kubernetes/authn/jwks.json
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"keys":[{"kty":"RSA","n":"u1SU1LfVLPHCozMxH2Mo4lgOEePzNm0tRgeLezV6ffAt0gunVTLw7onLRnrq0_IzW7yWR7QkrmBL7jTKEn5u-qKhbwKfBstIs-bMY2Zkp18gnTxKLxoS2tFczGkPLPgizskuemMghRniWaoLcyehkd3qqGElvW_VDL5AaWTg0nLVkjRo9z-40RQzuVaE8AkAFmxZzow3x-VJYKdjykkJ0iT9wCS0DRTXu269V264Vf_3jvredZiKRkgwlL9xNAwxXFg0x_XFw005UWVRIkdgcKWTjpBP2dPwVZ4WWC-9aGVd-Gyn1o0CLelf4rEjGoXbAAEgAqeGUxrcIlbjXfbcmw","e":"AQAB","alg":"RS256","use":"sig"}]}
47 changes: 47 additions & 0 deletions examples/kubernetes/authn/jwt.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: AuthenticationFilter
metadata:
name: jwt-example
spec:
type: JWT
jwtProviders:
- name: example
remoteJWKS:
uri: https://raw.githubusercontent.com/envoyproxy/gateway/main/examples/kubernetes/authn/jwks.json
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
name: backend
spec:
parentRefs:
- name: eg
hostnames:
- "www.example.com"
rules:
- backendRefs:
- group: ""
kind: Service
name: backend
port: 3000
weight: 1
filters:
- extensionRef:
group: gateway.envoyproxy.io
kind: AuthenticationFilter
name: jwt-example
type: ExtensionRef
matches:
- path:
type: PathPrefix
value: /foo
- backendRefs:
- group: ""
kind: Service
name: backend
port: 3000
weight: 1
matches:
- path:
type: PathPrefix
value: /bar
1 change: 1 addition & 0 deletions examples/kubernetes/authn/test.jwt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.NHVaYe26MbtOYhSKkoKYdFVomg4i8ZJd8_-RU8VNbftc4TSMb4bXP3l3YlNWACwyXPGffz5aXHc6lty1Y2t4SWRqGteragsVdZufDn5BlnJl9pdR_kdVFUsra2rWKEofkZeIC4yWytE58sMIihvo9H1ScmmVwBcQP6XETqYd0aSHp1gOa9RdUPDvoXQ5oqygTqVtxaDr6wUFKrKItgBMzWIdNZ6y7O9E0DhEPTbE9rfBo6KTFsHAZnMg4k68CDp2woYIaXbmYTWcvbzIuHO7_37GT79XdIwkm95QJ7hYC9RiwrV7mesbY4PAahERJawntho0my942XheVLmGwLMBkQ

0 comments on commit 2a431c1

Please sign in to comment.