Add OIDC e2e tests based on Keycloak

.github/workflows/ci.yaml

@@ -69,6 +69,8 @@ jobs:
   e2e:
     needs: check
     runs-on: ubuntu-latest
+    env:
+      E2E_TEST_OPTS: -v -count=1
     steps:
       - uses: docker/setup-qemu-action@v3
         with:
@@ -78,4 +80,17 @@ jobs:
       - uses: actions/setup-go@v5
         with:
           go-version-file: go.mod
+      # Configure the Docker hostname to be able to access the host from the containers
+      - name: Add Docker internal host to /etc/hosts
+        run: echo "127.0.0.1 host.docker.internal" | sudo tee -a /etc/hosts
       - run: make docker e2e
+
+      - name: Upload e2e logs on failure
+        uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: e2e-logs
+          path: |
+            e2e/**/logs/*
+            e2e/**/certs/*
+          if-no-files-found: ignore

CONTRIBUTING.md

@@ -1,28 +1,29 @@
-# How to Contribute
-
-We'd love to accept your patches and contributions to this project. There are
-just a few small guidelines you need to follow.
-
-## Contributor License Agreement
-
-Contributions to this project must be accompanied by a Contributor License
-Agreement. You (or your employer) retain the copyright to your contribution;
-this simply gives us permission to use and redistribute your contributions as
-part of the project. Head over to <https://cla.developers.google.com/> to see
-your current agreements on file or to sign a new one.
-
-You generally only need to submit a CLA once, so if you've already submitted one
-(even if it was for a different project), you probably don't need to do it
-again.
-
-## Code reviews
-
-All submissions, including submissions by project members, require review. We
-use GitHub pull requests for this purpose. Consult
-[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
-information on using pull requests.
-
-## Community Guidelines
-
-This project follows [Google's Open Source Community
-Guidelines](https://opensource.google.com/conduct/).
+# Contributing
+
+We welcome contributions from the community. Please read the following guidelines carefully to
+maximize the chances of your PR being merged.
+
+## Coding Style
+
+* To ensure your change passes format checks, run `make check`. To format your files, you can run `make format`.
+* We follow standard Go table-driven tests and use the `testify` library to assert correctness. 
+  To verify all tests pass, you can run `make test`.
+
+## Code Reviews
+
+* The pull request title should describe what the change does and not embed issue numbers.
+  The pull request should only be blank when the change is minor. Any feature should include
+  a description of the change and what motivated it. If the change or design changes through
+  review, please keep the title and description updated accordingly.
+* A single approval is sufficient to merge. If a reviewer asks for
+  changes in a PR they should be addressed before the PR is merged,
+  even if another reviewer has already approved the PR.
+* During the review, address the comments and commit the changes
+  _without_ squashing the commits. This facilitates incremental reviews
+  since the reviewer does not go through all the code again to find out
+  what has changed since the last review. When a change goes out of sync with main,
+  please rebase and force push, keeping the original commits where practical.
+* Commits are squashed prior to merging a pull request, using the title
+  as commit message by default. Maintainers may request contributors to
+  edit the pull request tite to ensure that it remains descriptive as a
+  commit message. Alternatively, maintainers may change the commit message directly.

DEVELOPMENT.md

@@ -0,0 +1,92 @@
+# Developer guide
+
+All the build targets are self-explanatory and can be listed with:
+
+```bash
+$ make help
+```
+
+The following software and tools are needed to build the project and run the tests:
+
+* [Go](https://golang.org/dl/)
+* [GNU make](https://www.gnu.org/software/make/)
+* [Docker](https://docs.docker.com/get-docker/)
+
+
+## Generating the API code
+
+The configuration options are defined in the [config](config/) directory using [Protocol Buffers](https://protobuf.dev/).
+To generate the configuration API code after doing changes to the `.proto` files, run:
+
+```bash
+$ make generate
+```
+
+There is no need to run `generate` after checking out the code; it's only needed when changes are made to
+the `.proto` files.
+
+
+## Building the binary
+
+To build the binary simply run:
+
+```bash
+$ make build     # Builds a dynamically linked binary
+$ make static    # Builds a statically linked binary
+```
+
+The resulting binaries will be in the `bin/` directory. You can play with the 
+`TARGETS` environment variable to control the operating systems and architectures you want
+to build for.
+
+
+## Docker image
+
+To build the Docker image, run:
+
+```bash
+$ make docker         # Build a single-arch Docker image tagged with "-latest-$arch" 
+$ make docker-push    # Build and push the multi-arch Docker images to the registry
+```
+
+This will automatically build the required binaries and create a Docker image with them.
+
+The `make docker` target will produce images that are suitable to be used in the `e2e` tests.
+The `make docker-push` target will produce multi-arch images and push them to the registry.
+You can use the `DOCKER_TARGETS` environment variable to control the operating systems and architectures
+you want to build the Docker images for.
+
+
+## Testing
+
+The main testing targets are:
+
+```bash
+$ make test     # Run the unit tests
+$ make lint     # Run the linters
+$ make e2e      # Run the end-to-end tests
+```
+
+### e2e tests
+
+The end-to-end tests are found in the [e2e](e2e/) directory. Each subdirectory contains a test suite
+that can be run independently. The `make e2e` target will run all the test suites by default. To run
+individual suites, simply run `make e2e/<suite>`. For example:
+
+```bash
+$ make e2e            # Run all the e2e suites
+$ make e2e/keycloak   # Run the 'keycloak' e2e suite
+
+# Examples with custom test options
+$ E2E_TEST_OPTS="-v -count=1" make e2e  # Run all the e2e suites with verbose output and no caching
+$ E2E_PRESERVE_LOGS=true make e2e       # Preserve the container logs even if tests succeed
+```
+
+> [!Note]
+> The end-to-end tests use the `authservice` Docker image, and it **must be up-to-date**.  
+> Make sure you run `make clean docker` before running the tests
+
+The end-to-end tests use Docker Compose to set up the required infrastructure before running the tests.
+Once the tests are done, the infrastructure is automatically torn down if tests pass, or left running
+if tests fail, to facilitate troubleshooting. Container logs are also captured upon test failure, to
+aid in debugging.

README.md

@@ -6,6 +6,9 @@
 An implementation of [Envoy](https://envoyproxy.io) [External Authorization](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_authz_filter),
 focused on delivering authN/Z solutions for [Istio](https://istio.io) and [Kubernetes](https://kubernetes.io).
 
+This project is a port of the [istio-ecosystem/authservice](https://github.com/istio-ecosystem/authservice)
+project from C++ to Go.
+
 ## Introduction
 
 `authservice` helps delegate the [OIDC Authorization Code Grant Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)
@@ -14,40 +17,26 @@ including [Authentication Policy](https://istio.io/docs/tasks/security/authn-pol
 Together, they allow developers to protect their APIs and web apps without any application code required.
 
 Some of the features it provides:
-- Transparent login and logout
-    - Retrieves OAuth2 Access tokens, ID tokens, and refresh tokens
-- Fine-grained control over which url paths are protected
-- Session management
-    - Configuration of session lifetime and idle timeouts
-    - Refreshes expired tokens automatically
-- Compatible with any standard OIDC Provider
-- Supports multiple OIDC Providers for same application
-- Trusts custom CA certs when talking to OIDC Providers
-- Works either at the sidecar or gateway level
-
-## Using the `authservice` docker image
+* Transparent login and logout
+  * Retrieves OAuth2 Access tokens, ID tokens, and refresh tokens
+* Fine-grained control over which url paths are protected
+* Session management
+  * Configuration of session lifetime and idle timeouts
+  * Refreshes expired tokens automatically
+* Compatible with any standard OIDC Provider
+* Supports multiple OIDC Providers for same application
+* Trusts custom CA certs when talking to OIDC Providers
+* Works either at the sidecar or gateway level
 
-The `authservice` images are hosted on [authservice's GitHub Package Registry](https://github.com/istio-ecosystem/authservice/packages).
 
 ## How does authservice work?
 
-We have created a [flowchart](https://miro.com/app/board/o9J_kvus6b4=/) to explain how authservice makes decisions at different points in the login lifecycle.
+[This flowchart](https://miro.com/app/board/o9J_kvus6b4=/) explains how `authservice`
+makes decisions at different points in the login lifecycle.
 
 ## Contributing
 
-To get started:
-
-- [Contributing guide](./CONTRIBUTING.md)
-
-## Roadmap
-See the [authservice github Project](https://github.com/istio-ecosystem/authservice/projects/1)
-
-Additional features being considered:
-- A more Istio-integrated experience of deploying/configuring/enabling `authservice`
-  (e.g.: extending Istio Authentication Policy to include `authservice` configs).
-
-## Contributing & Contact
+Contributions are very welcome! Please read the [Contributing guidelines](CONTRIBUTING.md)
+to get started.
 
-We welcome feedback and contributions. Aside from submitting Github issues/PRs, you can reach out at `#oidc-proposal`
-or `#security` channel on [Istio’s Slack](https://istio.slack.com/) workspace
-([here's how to join](https://istio.io/about/community/join/)).
+Detailed development instructions can be found in the [Development guide](DEVELOPMENT.md).

e2e/Makefile

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 
-SUITES := mock redis
+SUITES := mock redis keycloak
 
 .PHONY: e2e
 e2e: $(SUITES:%=e2e/%)  ## Run all e2e tests

e2e/keycloak/.gitignore

@@ -0,0 +1 @@
+certs/

e2e/keycloak/Makefile

@@ -0,0 +1,55 @@
+# Copyright 2024 Tetrate
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+CERTS_DIR := certs
+NAME      := host.docker.internal
+SHELL     := bash
+
+.PHONY: e2e-pre
+e2e-pre:: gen
+
+include ../suite.mk
+
+
+gen: gen/ca gen/certs  ## Generates the CA and certificates
+	@chmod -R a+r $(CERTS_DIR)
+
+$(CERTS_DIR):
+	@mkdir -p $(CERTS_DIR)
+
+.PHONY: gen/ca
+gen/ca: $(CERTS_DIR) ## Generates the CA
+	@echo "Generating CA"
+	@openssl genrsa -out "$(CERTS_DIR)/ca.key" 4096
+	@openssl req -x509 -new -sha256 -nodes -days 365 -key "$(CERTS_DIR)/ca.key" -out "$(CERTS_DIR)/ca.crt" \
+		-subj "/C=US/ST=California/O=Tetrate/OU=Engineering/CN=$(NAME)" \
+		-addext "basicConstraints=critical,CA:true,pathlen:1" \
+		-addext "keyUsage=critical,digitalSignature,nonRepudiation,keyEncipherment,keyCertSign" \
+		-addext "subjectAltName=DNS:$(NAME)"
+
+
+.PHONY: gen/certs
+gen/certs: $(CERTS_DIR)  ## Generates the certificates
+	@echo "Generating $(NAME) cert"
+	@openssl genrsa -out "$(CERTS_DIR)/server.key" 2048
+	@openssl req -new -sha256 -key "$(CERTS_DIR)/server.key" -out "$(CERTS_DIR)/server.csr" \
+		-subj "/C=US/ST=California/O=Tetrate/OU=Engineering/CN=$(NAME)" \
+		-addext "subjectAltName=DNS:$(NAME)"
+	@openssl x509 -req -sha256 -days 120 -in "$(CERTS_DIR)/server.csr" -out "$(CERTS_DIR)/server.crt" \
+		-CA "$(CERTS_DIR)/ca.crt" -CAkey "$(CERTS_DIR)/ca.key" -CAcreateserial -CAserial $(CERTS_DIR)/ca.srl \
+		-extfile <(printf "subjectAltName=DNS:$(NAME)")
+
+.PHONY: clean
+clean::
+	@rm -rf $(CERTS_DIR)

e2e/keycloak/README.md

@@ -0,0 +1,22 @@
+# Keycloak e2e tests
+
+The Keycloak e2e test suite contains tests that use the Keycloak OIDC provider. A
+Keycloak instance is deployed and configured in the Docker environment as the backend
+OIDC provider.
+
+The setup is performed in the [setup-keycloak.sh](setup-keycloak.sh) script, which
+configures the default `master` realm with:
+
+* A user named `authservice` with a predefined password.
+* A client named `authservice` with a predefined secret.
+
+The user and client will be used in the e2e tests to verify the entire Authorization Code flow.
+
+## Docker host name resolution
+
+The Keycloak end-to-end tests rely on the host `host.docker.internal` to resolve to the host machine,
+so you may need to add an entry to your `/etc/hosts` file to make it work. For example:
+
+```bash
+$ echo "127.0.0.1  host.docker.internal" >> /etc/hosts
+```

e2e/keycloak/authz-config.json

@@ -0,0 +1,28 @@
+{
+  "listen_address": "0.0.0.0",
+  "listen_port": 10003,
+  "log_level": "debug",
+  "chains": [
+    {
+      "name": "keycloak",
+      "filters": [
+        {
+          "oidc": {
+            "configuration_uri": "http://host.docker.internal:8080/realms/master/.well-known/openid-configuration",
+            "callback_uri": "https://host.docker.internal:8443/callback",
+            "client_id": "authservice",
+            "client_secret": "authservice-secret",
+            "cookie_name_prefix": "authservice",
+            "id_token": {
+              "preamble": "Bearer",
+              "header": "authorization"
+            },
+            "redis_session_store_config": {
+              "server_uri": "redis://redis:6379"
+            }
+          }
+        }
+      ]
+    }
+  ]
+}