From 73c25dffccb32786bee55fbb52cd8d29b3ea11be Mon Sep 17 00:00:00 2001 From: Jim Fitzpatrick Date: Fri, 10 Nov 2023 14:27:41 +0000 Subject: [PATCH 01/16] Fix list rendering --- docs/contributing.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 9a510f66..02a7b1ed 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -19,6 +19,7 @@ ## Technology stack for developers Minimum requirements to contribute to Authorino are: + - [Golang v1.20+](https://golang.org) - [Docker](https://docker.com) @@ -27,17 +28,17 @@ Authorino's code was originally bundled using the [Operator SDK](https://sdk.ope The following tools can be installed as part of the development workflow: - _Installed with `go install` to the `$PROJECT_DIR/bin` directory:_ - - [controller-gen](https://book.kubebuilder.io/reference/controller-gen.html): for building custom types and manifests - - [Kustomize](https://kustomize.io/): for assembling flavoured manifests and installing/deploying - - [setup-envtest](https://v0-19-x.sdk.operatorframework.io/docs/golang/references/env-test-setup): for running the tests – extra tools installed to `./testbin` - - [benchstat](https://cs.opensource.google/go/x/perf): for human-friendly test benchmark reports - - [mockgen](https://github.com/golang/mock/mockgen): to generate mocks for tests – e.g. `./bin/mockgen -source=pkg/auth/auth.go -destination=pkg/auth/mocks/mock_auth.go` - - [Kind](https://kind.sigs.k8s.io): for deploying a containerized Kubernetes cluster for integration testing purposes + - [controller-gen](https://book.kubebuilder.io/reference/controller-gen.html): for building custom types and manifests + - [Kustomize](https://kustomize.io/): for assembling flavoured manifests and installing/deploying + - [setup-envtest](https://v0-19-x.sdk.operatorframework.io/docs/golang/references/env-test-setup): for running the tests – extra tools installed to `./testbin` + - [benchstat](https://cs.opensource.google/go/x/perf): for human-friendly test benchmark reports + - [mockgen](https://github.com/golang/mock/mockgen): to generate mocks for tests – e.g. `./bin/mockgen -source=pkg/auth/auth.go -destination=pkg/auth/mocks/mock_auth.go` + - [Kind](https://kind.sigs.k8s.io): for deploying a containerized Kubernetes cluster for integration testing purposes - _Other recommended tools to have installed:_ - - [jq](https://stedolan.github.io/jq/) - - [yq](http://mikefarah.github.io/yq/) - - [gnu-sed](https://www.gnu.org/software/sed/) + - [jq](https://stedolan.github.io/jq/) + - [yq](http://mikefarah.github.io/yq/) + - [gnu-sed](https://www.gnu.org/software/sed/) ## Workflow @@ -71,6 +72,7 @@ make help ### Make your changes Good changes... + - follow the [Golang conventions](https://golang.org/doc/effective_go) - have proper test coverage - address corresponding updates to the [docs](./) @@ -89,6 +91,7 @@ make test #### Build, deploy and try Authorino in a local cluster The following command will: + - Start a local Kubernetes cluster (using Kind) - Install [cert-manager](https://github.com/jetstack/cert-manager) in the cluster - Install the [Authorino Operator](https://github.com/kuadrant/authorino-operator) and Authorino CRDs @@ -247,6 +250,7 @@ All commits to be accepted to Authorino's code are required to be signed. Refer ## Logging policy A few guidelines for adding logging messages in your code: + 1. Make sure you understand Authorino's [Logging](./user-guides/observability.md#logging) architecture and policy regarding log levels, log modes, tracing IDs, etc. 2. Respect controller-runtime's [Logging Guidelines](https://github.com/kubernetes-sigs/controller-runtime/blob/master/TMP-LOGGING.md). 3. Do not add sensitive data to your `info` log messages; instead, redact all sensitive data in your log messages or use `debug` log level by mutating the logger with `V(1)` before outputting the message. From 7fd0bc2ad21108cdd025d31aa7f9227d45782ffa Mon Sep 17 00:00:00 2001 From: Jim Fitzpatrick Date: Wed, 8 Nov 2023 12:39:42 +0000 Subject: [PATCH 02/16] Remove table of contents The table has being removed in favour for better rendering on docs.kuadrant.io --- docs/contributing.md | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 02a7b1ed..6c25d4c0 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,21 +1,5 @@ # Developer's Guide -- [Technology stack for developers](#technology-stack-for-developers) -- [Workflow](#workflow) - - [Check the issues](#check-the-issues) - - [Clone the repo and setup the local environment](#clone-the-repo-and-setup-the-local-environment) - - [Make your changes](#make-your-changes) - - [Run the tests](#run-the-tests) - - [Try locally](#try-locally) - - [Build, deploy and try Authorino in a local cluster](#build-deploy-and-try-authorino-in-a-local-cluster) - - [Additional tools (for specific use-cases)](#additional-tools-for-specific-use-cases) - - [Re-build and rollout latest](#re-build-and-rollout-latest) - - [Clean-up](#clean-up) - - [Sign your commits](#sign-your-commits) -- [Logging policy](#logging-policy) -- [Additional resources](#additional-resources) -- [Reach out](#reach-out) - ## Technology stack for developers Minimum requirements to contribute to Authorino are: From 0c74a99a7f8afe70672818e92cce29c5265eb7cb Mon Sep 17 00:00:00 2001 From: Jim Fitzpatrick Date: Fri, 10 Nov 2023 14:28:38 +0000 Subject: [PATCH 03/16] Fixing broken links --- docs/contributing.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 6c25d4c0..20474727 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -14,14 +14,14 @@ The following tools can be installed as part of the development workflow: - _Installed with `go install` to the `$PROJECT_DIR/bin` directory:_ - [controller-gen](https://book.kubebuilder.io/reference/controller-gen.html): for building custom types and manifests - [Kustomize](https://kustomize.io/): for assembling flavoured manifests and installing/deploying - - [setup-envtest](https://v0-19-x.sdk.operatorframework.io/docs/golang/references/env-test-setup): for running the tests – extra tools installed to `./testbin` + - [setup-envtest](https://book.kubebuilder.io/reference/envtest.html): for running the tests – extra tools installed to `./testbin` - [benchstat](https://cs.opensource.google/go/x/perf): for human-friendly test benchmark reports - - [mockgen](https://github.com/golang/mock/mockgen): to generate mocks for tests – e.g. `./bin/mockgen -source=pkg/auth/auth.go -destination=pkg/auth/mocks/mock_auth.go` + - [mockgen](https://github.com/golang/mock): to generate mocks for tests – e.g. `./bin/mockgen -source=pkg/auth/auth.go -destination=pkg/auth/mocks/mock_auth.go` - [Kind](https://kind.sigs.k8s.io): for deploying a containerized Kubernetes cluster for integration testing purposes - _Other recommended tools to have installed:_ - [jq](https://stedolan.github.io/jq/) - - [yq](http://mikefarah.github.io/yq/) + - [yq](https://mikefarah.github.io/yq/) - [gnu-sed](https://www.gnu.org/software/sed/) ## Workflow From da60e847b9b47bb50eb9a7f952ce5e2851a9329e Mon Sep 17 00:00:00 2001 From: Jim Fitzpatrick Date: Wed, 8 Nov 2023 15:22:32 +0000 Subject: [PATCH 04/16] Update for list layout Change formatting to get better rendering on docs.kuadrant.io --- docs/user-guides/sharding.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/user-guides/sharding.md b/docs/user-guides/sharding.md index 647d4bfc..950a3bb3 100644 --- a/docs/user-guides/sharding.md +++ b/docs/user-guides/sharding.md @@ -1,6 +1,7 @@ # User guide: Reducing the operational space By default, Authorino will watch events related to all `AuthConfig` custom resources in the reconciliation space (namespace or entire cluster). Instances can be configured though to only watch a subset of the resources, thus allowing such as: + - to reduce noise and lower memory usage inside instances meant for restricted scope (e.g. Authorino deployed as a dedicated sidecar to protect only one host); - sharding auth config data across multiple instances; - multiple environments (e.g. staging, production) inside of a same cluster/namespace; From 2529f35810deeb5e97e38fbd9ef8cd5fb5b63de7 Mon Sep 17 00:00:00 2001 From: Jim Fitzpatrick Date: Wed, 8 Nov 2023 16:10:01 +0000 Subject: [PATCH 05/16] Fix list rendering Reformat the list to work on docs.kuadrant.io --- docs/user-guides/host-override.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/user-guides/host-override.md b/docs/user-guides/host-override.md index 1f28ef9e..331488ef 100644 --- a/docs/user-guides/host-override.md +++ b/docs/user-guides/host-override.md @@ -18,6 +18,7 @@ Overriding the host attribute of the HTTP request can be useful to support use c
In this guide: + - [Example of host override for path prefix-based lookup](#example-of-host-override-for-path-prefix-based-lookup) - [Example of host override for wildcard subdomain lookup](#example-of-host-override-for-wildcard-subdomain-lookup) @@ -26,6 +27,7 @@ In this guide: ## Example of host override for path prefix-based lookup In this use case, 2 different APIs (i.e. **Dogs API** and **Cats API**) are served under the same base domain, and differentiated by the path prefix: + - `pets.com/dogs` → Dogs API - `pets.com/cats` → Cats API @@ -91,6 +93,7 @@ Notice that the host subdomains `dogs.pets.com` and `cats.pets.com` are not real ## Example of host override for wildcard subdomain lookup In this use case, a single **Pets API** serves requests for any subdomain that matches `*.pets.com`, e.g.: + - `dogs.pets.com` → Pets API - `cats.pets.com` → Pets API From 3c09da042b02fa8abe6775baf3ca38ba63d0bb72 Mon Sep 17 00:00:00 2001 From: Jim Fitzpatrick Date: Fri, 10 Nov 2023 14:30:38 +0000 Subject: [PATCH 06/16] Fixing layouts in
blocks --- docs/contributing.md | 2 +- docs/getting-started.md | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 20474727..d25fbb2a 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -127,7 +127,7 @@ kubectl port-forward deployment/envoy 8000:8000 & Authorino examples include a bundle of [Keycloak](https://www.keycloak.org) preloaded with the following realm setup: - - Admin console: http://localhost:8080/auth/admin (admin/p) + - Admin console: [http://localhost:8080/auth/admin](http://localhost:8080/auth/admin) (admin/p) - Preloaded realm: **kuadrant** - Preloaded clients: - **demo**: to which API consumers delegate access and therefore the one which access tokens are issued to diff --git a/docs/getting-started.md b/docs/getting-started.md index 0ba79b2d..a3fd1f9f 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -18,19 +18,19 @@ These are the platform requirements to use Authorino: - [**Kubernetes**](https://kubernetes.io) server (recommended v1.20 or later), with permission to create Kubernetes Custom Resource Definitions (CRDs) (for bootstrapping Authorino and Authorino Operator) -
- Alternative: K8s distros and platforms +
+Alternative: K8s distros and platforms - Alternatively to upstream Kubernetes, you should be able to use any other Kubernetes distribution or Kubernetes Management Platform (KMP) with support for Kubernetes Custom Resources Definitions (CRD) and custom controllers, such as Red Hat OpenShift, IBM Cloud Kubernetes Service (IKS), Google Kubernetes Engine (GKE), Amazon Elastic Kubernetes Service (EKS) and Azure Kubernetes Service (AKS). -
+Alternatively to upstream Kubernetes, you should be able to use any other Kubernetes distribution or Kubernetes Management Platform (KMP) with support for Kubernetes Custom Resources Definitions (CRD) and custom controllers, such as Red Hat OpenShift, IBM Cloud Kubernetes Service (IKS), Google Kubernetes Engine (GKE), Amazon Elastic Kubernetes Service (EKS) and Azure Kubernetes Service (AKS). +
- [**Envoy**](https://www.envoyproxy.io) proxy (recommended v1.19 or later), to wire up Upstream services (i.e. the services to be protected with Authorino) and external authorization filter (Authorino) for integrations based on the reverse-proxy architecture - [example](https://github.com/kuadrant/authorino-examples#envoy) -
- Alternative: Non-reverse-proxy integration +
+Alternative: Non-reverse-proxy integration - Technically, any client that implements Envoy's external authorization gRPC protocol should be compatible with Authorino. For integrations based on the reverse-proxy architecture nevertheless, we strongly recommended that you leverage Envoy alongside Authorino. -
+Technically, any client that implements Envoy's external authorization gRPC protocol should be compatible with Authorino. For integrations based on the reverse-proxy architecture nevertheless, we strongly recommended that you leverage Envoy alongside Authorino. +
### Feature-specific requirements From d6c961a5edab450684c9f61bd6a7eef5bcf6208e Mon Sep 17 00:00:00 2001 From: Jim Fitzpatrick Date: Thu, 9 Nov 2023 10:58:25 +0000 Subject: [PATCH 07/16] fixing broken links --- docs/user-guides/sharding.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/user-guides/sharding.md b/docs/user-guides/sharding.md index 950a3bb3..6e1c978b 100644 --- a/docs/user-guides/sharding.md +++ b/docs/user-guides/sharding.md @@ -19,12 +19,14 @@ By default, Authorino will watch events related to all `AuthConfig` custom resou
- + Authorino capabilities featured in this guide:
    -
  • Sharding
    • -
  • Identity verification & authentication → API key
    • +
  • [Sharding](../architecture.md#sharding)
    • +
  • Identity verification & authentication → [API key](../features.md#api-key-authenticationapikey)
+ + Check out as well the user guide about [Authentication with API keys](api-key-authentication.md). From 1e27c623048809ad5d7b74ee821d35c1be557b8e Mon Sep 17 00:00:00 2001 From: Jim Fitzpatrick Date: Thu, 9 Nov 2023 11:42:47 +0000 Subject: [PATCH 08/16] Update page - remove toc - fix broken links --- docs/features.md | 43 +------------------------------------------ 1 file changed, 1 insertion(+), 42 deletions(-) diff --git a/docs/features.md b/docs/features.md index 136d736d..644deb74 100644 --- a/docs/features.md +++ b/docs/features.md @@ -1,46 +1,5 @@ # Features -- [Overview](#overview) -- [Common feature: JSON paths (`selector`)](#common-feature-json-paths-selector) - - [Syntax](#syntax) - - [String modifiers](#string-modifiers) - - [Interpolation](#interpolation) -- [Identity verification \& authentication features (`authentication`)](#identity-verification--authentication-features-authentication) - - [API key (`authentication.apiKey`)](#api-key-authenticationapikey) - - [Kubernetes TokenReview (`authentication.kubernetesTokenReview`)](#kubernetes-tokenreview-authenticationkubernetestokenreview) - - [JWT verification (`authentication.jwt`)](#jwt-verification-authenticationjwt) - - [OAuth 2.0 introspection (`authentication.oauth2Introspection`)](#oauth-20-introspection-authenticationoauth2introspection) - - [X.509 client certificate authentication (`authentication.x509`)](#x509-client-certificate-authentication-authenticationx509) - - [Plain (`authentication.plain`)](#plain-authenticationplain) - - [Anonymous access (`authentication.anonymous`)](#anonymous-access-authenticationanonymous) - - [Festival Wristband authentication](#festival-wristband-authentication) - - [_Extra:_ Auth credentials (`authentication.credentials`)](#extra-auth-credentials-authenticationcredentials) - - [_Extra:_ Identity extension (`authentication.defaults` and `authentication.overrides`)](#extra-identity-extension-authenticationdefaults-and-authenticationoverrides) -- [External auth metadata features (`metadata`)](#external-auth-metadata-features-metadata) - - [HTTP GET/GET-by-POST (`metadata.http`)](#http-getget-by-post-metadatahttp) - - [OIDC UserInfo (`metadata.userInfo`)](#oidc-userinfo-metadatauserinfo) - - [User-Managed Access (UMA) resource registry (`metadata.uma`)](#user-managed-access-uma-resource-registry-metadatauma) -- [Authorization features (`authorization`)](#authorization-features-authorization) - - [Pattern-matching authorization (`authorization.patternMatching`)](#pattern-matching-authorization-authorizationpatternmatching) - - [Open Policy Agent (OPA) Rego policies (`authorization.opa`)](#open-policy-agent-opa-rego-policies-authorizationopa) - - [Kubernetes SubjectAccessReview (`authorization.kubernetesSubjectAccessReview`)](#kubernetes-subjectaccessreview-authorizationkubernetessubjectaccessreview) - - [SpiceDB (`authorization.spicedb`)](#spicedb-authorizationspicedb) -- [Custom response features (`response`)](#custom-response-features-response) - - [Custom response forms: successful authorization vs custom denial status](#custom-response-forms-successful-authorization-vs-custom-denial-status) - - [Added HTTP headers](#added-http-headers) - - [Envoy Dynamic Metadata](#envoy-dynamic-metadata) - - [Custom denial status (`response.unauthenticated` and `response.unauthorized`)](#custom-denial-status-responseunauthenticated-and-responseunauthorized) - - [Custom response methods](#custom-response-methods) - - [Plain text (`response.success..plain`)](#plain-text-responsesuccessheadersdynamicmetadataplain) - - [JSON injection (`response.success..json`)](#json-injection-responsesuccessheadersdynamicmetadatajson) - - [Festival Wristband tokens (`response.success..wristband`)](#festival-wristband-tokens-responsesuccessheadersdynamicmetadatawristband) -- [Callbacks (`callbacks`)](#callbacks-callbacks) - - [HTTP endpoints (`callbacks.http`)](#http-endpoints-callbackshttp) -- [Common feature: Priorities](#common-feature-priorities) -- [Common feature: Conditions (`when`)](#common-feature-conditions-when) -- [Common feature: Caching (`cache`)](#common-feature-caching-cache) -- [Common feature: Metrics (`metrics`)](#common-feature-metrics-metrics) - ## Overview We call _features_ of Authorino the different things one can do to enforce identity verification & authentication and authorization on requests to protected services. These can be a specific identity verification method based on a supported authentication protocol, or a method to fetch additional auth metadata in request-time, etc. @@ -49,7 +8,7 @@ Most features of Authorino relate to the different phases of the [Auth Pipeline] At a deeper level, a _feature_ can also be an additional functionality within a bigger feature, usually applicable to the whole class the bigger feature belongs to. For instance, the configuration of how [auth credentials](#extra-auth-credentials-authenticationcredentials) expected to be carried in the request, which is broadly available for any identity verification method. Other examples are: [_Identity extension_](#extra-identity-extension-authenticationdefaults-and-authenticationoverrides) and [Priorities](#common-feature-priorities). -A full specification of all features of Authorino that can be configured in an `AuthConfig` can be found in the official [spec](../install/crd/authorino.kuadrant.io_authconfigs.yaml) of the custom resource definition. +A full specification of all features of Authorino that can be configured in an `AuthConfig` can be found in the official [spec](https://github.com/Kuadrant/authorino/blob/main/install/crd/authorino.kuadrant.io_authconfigs.yaml) of the custom resource definition. You can also learn about Authorino features by using the [`kubectl explain`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#explain) command in a Kubernetes cluster where the Authorino CRD has been installed. E.g. `kubectl explain authconfigs.spec.authentication.credentials`. From 9e29bdae8e1f099f0fa3e51541b0302da32b7833 Mon Sep 17 00:00:00 2001 From: Jim Fitzpatrick Date: Thu, 9 Nov 2023 12:25:58 +0000 Subject: [PATCH 09/16] Updating architecture doc - remove TOC - fix list rendering - fix broken links --- docs/architecture.md | 29 +++++------------------------ 1 file changed, 5 insertions(+), 24 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index d65589a4..2aa12187 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,27 +1,4 @@ # Architecture -- [Overview](#overview) -- [Topologies](#topologies) - - [Centralized gateway](#centralized-gateway) - - [Centralized authorization service](#centralized-authorization-service) - - [Sidecars](#sidecars) -- [Cluster-wide vs. Namespaced instances](#cluster-wide-vs-namespaced-instances) -- [The Authorino `AuthConfig` Custom Resource Definition (CRD)](#the-authorino-authconfig-custom-resource-definition-crd) -- [Resource reconciliation and status update](#resource-reconciliation-and-status-update) -- [The "Auth Pipeline" (_aka:_ enforcing protection in request-time)](#the-auth-pipeline-aka-enforcing-protection-in-request-time) -- [Host lookup](#host-lookup) - - [Avoiding host name collision](#avoiding-host-name-collision) -- [The Authorization JSON](#the-authorization-json) -- [Raw HTTP Authorization interface](#raw-http-authorization-interface) -- [Caching](#caching) - - [OpenID Connect and User-Managed Access configs](#openid-connect-and-user-managed-access-configs) - - [JSON Web Keys (JWKs) and JSON Web Key Sets (JWKS)](#json-web-keys-jwks-and-json-web-key-sets-jwks) - - [Revoked access tokens](#revoked-access-tokens) - - [External metadata](#external-metadata) - - [Compiled Rego policies](#compiled-rego-policies) - - [Repeated requests](#repeated-requests) -- [Sharding](#sharding) -- [RBAC](#rbac) -- [Observability](#observability) ## Overview @@ -48,6 +25,7 @@ On every request, Authorino's "working memory" is called [**Authorization JSON** Typically, upstream APIs are deployed to the same Kubernetes cluster and namespace where the Envoy proxy and Authorino is running (although not necessarily). Whatever is the case, Envoy must be proxying to the upstream API (see Envoy's [HTTP route components](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto) and virtual hosts) and pointing to Authorino in the external authorization filter. This can be achieved with different topologies: + - Envoy can be a [centralized gateway](#centralized-gateway) with one dedicated instance of Authorino, proxying to one or more upstream services - Envoy can be deployed as a sidecar of each protected service, but still contacting from a [centralized Authorino authorization service](#centralized-authorization-service) - Both Envoy and Authorino deployed as [sidecars](#sidecars) of the protected service, restricting all communication between them to localhost @@ -78,7 +56,7 @@ Apart from that, protected service should only listen on `localhost` and all tra Authorino instances can run in either **cluster-wide** or **namespaced** mode. -Namespace-scoped instances only watch resources (`AuthConfig`s and `Secret`s) created in a given namespace. This deployment mode does not require admin privileges over the Kubernetes cluster to deploy the instance of the service (given Authorino's CRDs have been installed beforehand, such as when Authorino is installed using the [Authorino Operator](https://github.com/kuadrant-authorino-operator)). +Namespace-scoped instances only watch resources (`AuthConfig`s and `Secret`s) created in a given namespace. This deployment mode does not require admin privileges over the Kubernetes cluster to deploy the instance of the service (given Authorino's CRDs have been installed beforehand, such as when Authorino is installed using the [Authorino Operator](https://github.com/kuadrant/authorino-operator)). Cluster-wide deployment mode, in contraposition, deploys instances of Authorino that watch resources across the entire cluster, consolidating all resources into a multi-namespace index of auth configs. Admin privileges over the Kubernetes cluster is required to deploy Authorino in cluster-wide mode. @@ -221,6 +199,7 @@ When more than one host name is specified in the `AuthConfig`, all of them can b ![Domain tree](http://www.plantuml.com/plantuml/png/RP71ReCm38RlVWhKuoGcjN2U-YPLb6MTDS0e9E-_v8zgNC4fyVU5nFo-Ryd5bEU9Ol39BSyfT9VFI-UsBeeaijZB355MYzUGDl2wiU93wQE-OfNpSu2jcpUnil97AOxtmU0-wrWWMOuVi1oUNtY5Agl5oKr_8VQl7bg9BiXpzEWlfrylomy_-oiELN0zqpVLjpCzg1xEzAXw92g1TtrU-pQI6YXA3AB6iLSQTaEOo2lAXX2uPcWOiPX7M8ndePAKxlTSW90Y4O80-DB8yVUDsJGjrev1XqPr_82ZXJXw3yjtdgT_) The domain tree above induces the following relation: + - `foo.nip.io` → `authconfig-1` (matches `*.io`) - `talker-api.nip.io` → `authconfig-2` (matches `talker-api.nip.io`) - `dogs.pets.com` → `authconfig-2` (matches `*.pets.com`) @@ -312,6 +291,7 @@ For information about reading and fetching data from the Authorization JSON (syn ## Raw HTTP Authorization interface Besides providing the gRPC authorization interface – that implements the Envoy gRPC authorization server –, Authorino also provides another interface for **raw HTTP authorization**. This second interface responds to `GET` and `POST` HTTP requests sent to `:5001/check`, and is suitable for other forms of integration, such as: + - using Authorino as Kubernetes ValidatingWebhook service ([example](./user-guides/validating-webhook.md)); - other HTTP proxies and API gateways; - old versions of Envoy incompatible with the latest version of gRPC external authorization protocol (Authorino is based on v3.19.1 of Envoy external authorization API) @@ -373,6 +353,7 @@ By default, Authorino instances will watch `AuthConfig` CRs in the entire space The benefits of limiting the space of reconciliation of an Authorino instance include avoiding unnecessary caching and workload in instances that do not receive corresponding traffic (according to your routing settings) and preventing leaders of multiple instances (sets of replicas) to compete on resource status updates (see [Resource reconciliation and status update](#resource-reconciliation-and-status-update) for details). Use-cases for sharding of `AuthConfig`s: + - Horizontal load balancing of traffic of authorization requests - Supporting for managed centralized instances of Authorino to API owners who create and maintain their own `AuthConfig`s within their own user namespaces. From 3555edb3f311fe996342ff714f59fed35953882b Mon Sep 17 00:00:00 2001 From: Jim Fitzpatrick Date: Thu, 9 Nov 2023 12:40:23 +0000 Subject: [PATCH 10/16] hello world formatting update - remove extra spacing - fix list rendering for website --- docs/user-guides/hello-world.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/docs/user-guides/hello-world.md b/docs/user-guides/hello-world.md index 76d5d24a..5eeb46ea 100644 --- a/docs/user-guides/hello-world.md +++ b/docs/user-guides/hello-world.md @@ -1,7 +1,5 @@ # User guide: Hello World -
- ## Requirements - Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) @@ -12,8 +10,6 @@ If you do not own a Kubernetes server already and just want to try out the steps kind create cluster --name authorino-tutorial ``` -
- The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. @@ -33,8 +29,6 @@ The next steps walk you through installing Authorino, deploying and configuring
-
- ## ❶ Create the namespace ```sh @@ -145,6 +139,7 @@ curl http://talker-api.127.0.0.1.nip.io:8000/hello -i Check out other [user guides](../user-guides.md) for several use-cases of authentication and authorization, and the instructions to implement them using Authorino. A few examples of available ser guides: + - [Authentication with API keys](api-key-authentication.md) - [Authentication with JWTs and OpenID Connect Discovery](oidc-jwt-authentication.md) - [Authentication with Kubernetes tokens (TokenReview API)](kubernetes-tokenreview.md) From 7edeeec48d1f32dcdb53522d38e917b3e072aaad Mon Sep 17 00:00:00 2001 From: Jim Fitzpatrick Date: Thu, 9 Nov 2023 12:54:49 +0000 Subject: [PATCH 11/16] Updating getting started guide - remove TOC - fix list for website reneder - fix links --- docs/getting-started.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index a3fd1f9f..3a0044d4 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -4,12 +4,6 @@ This page covers requirements and instructions to deploy Authorino on a Kubernet If you prefer learning with an example, check out our [Hello World](./user-guides/hello-world.md). -- [Requirements](#requirements) -- [Installation](#installation) -- [Protect a service](#protect-a-service) -- [Clean-up](#clean-up) -- [Next steps](#next-steps) - ## Requirements ### Platform requirements @@ -38,7 +32,7 @@ A few examples are: - For **OpenID Connect**, make sure you have access to an identity provider (IdP) and an authority that can issue ID tokens (JWTs). Check out [Keycloak](https://www.keycloak.org) which can solve both and connect to external identity sources and user federation like LDAP. -- For **Kubernetes authentication** tokens, platform support for the TokenReview and SubjectAccessReview APIs of Kubernetes shall be required. In case you want to be able to requests access tokens for clients running outside the custer, you may also want to check out the requisites for using Kubernetes [TokenRequest API](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#tokenrequest-v1-storage-k8s-io) (GA in v1.20). +- For **Kubernetes authentication** tokens, platform support for the TokenReview and SubjectAccessReview APIs of Kubernetes shall be required. In case you want to be able to requests access tokens for clients running outside the custer, you may also want to check out the requisites for using Kubernetes [TokenRequest API](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-request-v1/) (GA in v1.20). - For **User-Managed Access (UMA)** resource data, you will need a UMA-compliant server running as well. This can be an implementation of the UMA protocol by each upstream API itself or (more typically) an external server that knows about the resources. Again, Keycloak can be a good fit here as well. Just keep in mind that, whatever resource server you choose, changing-state actions commanded in the upstream APIs or other parties will have to be reflected in the resource server. Authorino will not do that for you. @@ -58,7 +52,7 @@ The above will install the latest build of the Authorino Operator and latest ver This step will also install [cert-manager](https://github.com/jetstack/cert-manager) in the cluster (required). -Alternatively, you can deploy the Authorino Operator using the Operator Lifecycle Manager bundles. For instructions, check out [Installing via OLM](https://github.com/kuadrant/authorino-operator#installing-via-olm). +Alternatively, you can deploy the Authorino Operator using the Operator Lifecycle Manager bundles. For instructions, check out [Installing via OLM](https://docs.kuadrant.io/authorino-operator/#installing-via-olm). ### Step: Request an Authorino instance @@ -196,6 +190,7 @@ The most typical integration to protect services with Authorino is by putting th To do that, make sure you have your **upstream service deployed and running**, usually in the same Kubernetes server where you installed Authorino. Then, setup an [Envoy](https://www.envoyproxy.io) proxy and create an Authorino `AuthConfig` for your service. Authorino exposes 2 interfaces to serve the authorization requests: + - a gRPC interface that implements Envoy's [External Authorization protocol](https://www.envoyproxy.io/docs/envoy/latest/start/sandboxes/ext_authz); - a raw HTTP authorization interface, suitable for using Authorino with Kubernetes ValidatingWebhook, for Envoy external authorization via HTTP, and other integrations (e.g. other proxies). @@ -256,7 +251,7 @@ static_resources: filename: /etc/ssl/certs/authorino-ca-cert.crt ``` -For a complete Envoy `ConfigMap` containing an upstream API protected with Authorino, with TLS enabled and option for rate limiting with [Limitador](https://github.com/kuadrant/limitador), plus a webapp served with under the same domain of the protected API, check out this [example](https://github.com/Kuadrant/authorino-examples/blob/main/envoy/envoy-tls-deploy.yaml). +For a complete Envoy `ConfigMap` containing an upstream API protected with Authorino, with TLS enabled and option for rate limiting with [Limitador](https://docs.kuadrant.io/limitador/), plus a webapp served with under the same domain of the protected API, check out this [example](https://github.com/Kuadrant/authorino-examples/blob/main/envoy/envoy-tls-deploy.yaml). After creating the `ConfigMap` with the Envoy configuration, create an Envoy `Deployment` and `Service`. E.g.: From ebdf4139576ba3f99eae741f56787abd7d757067 Mon Sep 17 00:00:00 2001 From: Jim Fitzpatrick Date: Thu, 9 Nov 2023 15:44:14 +0000 Subject: [PATCH 12/16] Readme updates - Formatting for list render on website - Update links --- README.md | 19 +++++-------------- 1 file changed, 5 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index bed79187..95e42ddc 100644 --- a/README.md +++ b/README.md @@ -11,17 +11,6 @@ Authorino is not about inventing anything new. It's about making the best things [![End-to-end Tests](https://github.com/Kuadrant/authorino/actions/workflows/e2e-test.yaml/badge.svg)](https://github.com/Kuadrant/authorino/actions/workflows/e2e-test.yaml) [![Smoke Tests](https://github.com/Kuadrant/authorino/actions/workflows/integration-test.yaml/badge.svg)](https://github.com/Kuadrant/authorino/actions/workflows/integration-test.yaml) -## Table of contents - -- [Getting started](#getting-started) -- [Use-cases](#use-cases) -- [How it works](#how-it-works) -- [List of features](#list-of-features) -- [Documentation](./docs/README.md) -- [FAQ](#faq) -- [Benchmarks](#benchmarks) -- [Contributing](#contributing) - ## Getting started 1. Deploy with the [Authorino Operator](https://github.com/kuadrant/authorino-operator) @@ -240,7 +229,7 @@ For a detailed description of the features above, refer to the [Features](./docs The only attribute of the authorization request that is strictly required is the host name. (See [Host lookup](./docs/architecture.md#host-lookup) for more information.) The other attributes, such as method, path, headers, etc, might as well be required, depending on each `AuthConfig`. In the case of the gRPC [`CheckRequest`](https://pkg.go.dev/github.com/envoyproxy/go-control-plane/envoy/service/auth/v3?utm_source=gopls#CheckRequest) method, the host is supplied in `Attributes.Request.Http.Host` and alternatively in `Attributes.ContextExtensions["host"]`. For raw HTTP authorization requests, the host must be supplied in `Host` HTTP header. - Check out [Kuadrant](https://github.com/kuadrant/kuadrant-controller) for easy-to-use Envoy and Authorino deployment & configuration for API management use-cases, using Kubernetes Custom Resources. + Check out [Kuadrant](https://docs.kuadrant.io/kuadrant-operator) for easy-to-use Envoy and Authorino deployment & configuration for API management use-cases, using Kubernetes Custom Resources.
@@ -303,7 +292,7 @@ For a detailed description of the features above, refer to the [Features](./docs There are lots of similarities, but also complementarity between Authorino and Istio and [Istio Authorization](https://istio.io/latest/docs/concepts/security/#authorization) in special. - Istio provides a simple way to enable features that are, in many cases, features of Envoy, such as authorization based on JWTs, authorization based on attributes of the request, and activation of external authorization services, without having to deal with complex Envoy config files. See [Kuadrant](https://github.com/kuadrant/kuadrant-controller) for a similar approach, nonetheless leveraging features of Istio as well. + Istio provides a simple way to enable features that are, in many cases, features of Envoy, such as authorization based on JWTs, authorization based on attributes of the request, and activation of external authorization services, without having to deal with complex Envoy config files. See [Kuadrant](https://doc.kuadrant.io/kuadrant-operator) for a similar approach, nonetheless leveraging features of Istio as well. Authorino is an Envoy-compatible external authorization service. One can use Authorino with or without Istio. @@ -312,6 +301,7 @@ For a detailed description of the features above, refer to the [Features](./docs Authorino also provides built-in OPA authorization, several other methods of authentication and identity verification (e.g. Kubernetes token validation, API key-based authentication, OAuth token introspection, OIDC-discoverable JWT verification, etc), and features like fetching of external metadata (HTTP services, OIDC userinfo, UMA resource data), token normalization, wristband tokens and dynamic responses. These all can be used independently or combined, in a simple and straightforward Kubernetes-native fashion. In summary, one might value Authorino when looking for a policy enforcer that offers: + 1. multiple supported methods and protocols for rather hybrid authentication, encompassing future and legacy auth needs; 2. broader expressiveness and more functionalities for the authorization rules; 3. authentication and authorization in one single declarative manifest; @@ -362,7 +352,7 @@ For a detailed description of the features above, refer to the [Features](./docs
Do I have to be admin of the cluster to install Authorino? - To install the Authorino Custom Resource Definition (CRD) and to define cluster roles required by the Authorino service, admin privilege to the Kubernetes cluster is required. This step happens only once per cluster and is usually equivalent to installing the [Authorino Operator](https://github.com/kuadrant/authorino-operator). + To install the Authorino Custom Resource Definition (CRD) and to define cluster roles required by the Authorino service, admin privilege to the Kubernetes cluster is required. This step happens only once per cluster and is usually equivalent to installing the [Authorino Operator](https://docs.kuadrant.io/authorino-operator). Thereafter, deploying instances of the Authorino service and applying `AuthConfig` custom resources to a namespace depend on the permissions set by the cluster administrator – either directly by editing the bindings in the cluster's RBAC, or via options of the operator. In most cases, developers will be granted permissions to create and manage `AuthConfig`s, and sometimes to deploy their own instances of Authorino.
@@ -390,6 +380,7 @@ For a detailed description of the features above, refer to the [Features](./docs ## Benchmarks **Configuration of the tests (Authorino features):** + | Performance test | Identity | Metadata | Authorization | Response | |----------------------------|:---------:|:-------------:|:------------------------------------------------------:|:--------:| | `ReconcileAuthConfig` | OIDC/JWT | UserInfo, UMA | OPA
(inline Rego) | - | From 37c1b137ccab592bb3e307ac81d827409b9fc9a3 Mon Sep 17 00:00:00 2001 From: Jim Fitzpatrick Date: Mon, 13 Nov 2023 15:49:13 +0000 Subject: [PATCH 13/16] PR comments - Fix broken links --- docs/user-guides/sharding.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/user-guides/sharding.md b/docs/user-guides/sharding.md index 6e1c978b..f42b9b0d 100644 --- a/docs/user-guides/sharding.md +++ b/docs/user-guides/sharding.md @@ -22,13 +22,10 @@ By default, Authorino will watch events related to all `AuthConfig` custom resou Authorino capabilities featured in this guide:
    -
  • [Sharding](../architecture.md#sharding)
    • -
  • Identity verification & authentication → [API key](../features.md#api-key-authenticationapikey)
    • +
  • Sharding
    • +
  • Identity verification & authentication → API key
- - - Check out as well the user guide about [Authentication with API keys](api-key-authentication.md). For further details about Authorino features in general, check the [docs](../features.md). From 58a8b0e843001ac2d921d0381fe9c46f473fd203 Mon Sep 17 00:00:00 2001 From: Jim Fitzpatrick Date: Tue, 14 Nov 2023 14:21:06 +0000 Subject: [PATCH 14/16] Update observability guide - fix list rendering - update URLs --- docs/user-guides/observability.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/user-guides/observability.md b/docs/user-guides/observability.md index ba845b45..21bd330c 100644 --- a/docs/user-guides/observability.md +++ b/docs/user-guides/observability.md @@ -1074,6 +1074,7 @@ The [Authorino Operator](https://github.com/kuadrant/authorino-operator) creates ## Readiness check Authorino exposes two main endpoints for health and readiness check of the AuthConfig controller: + - `/healthz`: Health probe (ping) – reports "ok" if the controller is healthy. - `/readyz`: Readiness probe – reports "ok" if the controller is ready to reconcile AuthConfig-related events. @@ -1093,6 +1094,7 @@ The following additional subpath is available and its corresponding check can be Apart from `include` to add the aggregated status of the AuthConfigs, the following additional query string parameters are available: + - `verbose=true|false` - provides more verbose response messages; - `exclude=(check name)` – to exclude a particular readiness check (for future usage). @@ -1103,6 +1105,7 @@ Authorino provides structured log messages ("production") or more log messages o ### Log levels and log modes Authorino outputs 3 levels of log messages: (from lowest to highest level) + 1. `debug` 2. `info` (default) 3. `error` @@ -1114,6 +1117,7 @@ Only `debug` logging will include processing details of each [Auth Pipeline](../ To configure the desired log level, set the `spec.logLevel` field of the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) custom resource (or `--log-level` command-line flag in the Authorino deployment), to one of the supported values listed above. Default log level is `info`. Apart from log level, Authorino can output messages to the logs in 2 different formats: + - `production` (default): each line is a parseable JSON object with properties `{"level":string, "ts":int, "msg":string, "logger":string, extra values...}` - `development`: more human-readable outputs, extra stack traces and logging info, plus extra values output as JSON, in the format: `\t\t\t\t{extra-values-as-json}` @@ -1410,12 +1414,13 @@ The examples below are all with `--log-level=debug` and `--log-mode=production`. ### Request ID Processes related to the authorization request are identified and linked together by a _request ID_. The request ID can be: + * generated outside Authorino and passed in the authorization request – this is essentially the case of requests via GRPC authorization interface initiated by the Envoy; * generated by Authorino – requests via [Raw HTTP Authorization interface](../architecture.md#raw-http-authorization-interface). ### Propagation -Authorino propagates trace identifiers compatible with the W3C Trace Context format (https://www.w3.org/TR/trace-context/) and user-defined baggage data in the W3C Baggage format (https://www.w3.org/TR/baggage). +Authorino propagates trace identifiers compatible with the W3C Trace Context format [https://www.w3.org/TR/trace-context/](https://www.w3.org/TR/trace-context/) and user-defined baggage data in the W3C Baggage format [https://www.w3.org/TR/baggage](https://www.w3.org/TR/baggage). ### Log tracing From 27636e38b480ec5675d887f58058aa6e82e9972b Mon Sep 17 00:00:00 2001 From: Jim Fitzpatrick Date: Tue, 14 Nov 2023 14:53:07 +0000 Subject: [PATCH 15/16] WIP caching guide update - Update list format --- docs/user-guides/caching.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/user-guides/caching.md b/docs/user-guides/caching.md index c6535e46..001fe9b5 100644 --- a/docs/user-guides/caching.md +++ b/docs/user-guides/caching.md @@ -9,6 +9,7 @@ This is particularly useful for configuration bits whose evaluation is significa - Caching of complex Rego policies that involve sending requests to external services Cases where one will **NOT** want to enable caching, due to relatively cheap compared to accessing and managing the cache: + - Validation of OIDC/JWT access tokens - OPA/Rego policies that do not involve external requests - JSON pattern-matching authorization From 7cdb2d6bacac2a1b5e7440800c2b1835c0a4c935 Mon Sep 17 00:00:00 2001 From: Jim Fitzpatrick Date: Mon, 27 Nov 2023 11:43:00 +0000 Subject: [PATCH 16/16] PR Comments - fix display indents - update URL --- docs/contributing.md | 2 +- docs/getting-started.md | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index d25fbb2a..0442f4eb 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -127,7 +127,7 @@ kubectl port-forward deployment/envoy 8000:8000 & Authorino examples include a bundle of [Keycloak](https://www.keycloak.org) preloaded with the following realm setup: - - Admin console: [http://localhost:8080/auth/admin](http://localhost:8080/auth/admin) (admin/p) + - Admin console: [http://localhost:8080/admin](http://localhost:8080/admin) (admin/p) - Preloaded realm: **kuadrant** - Preloaded clients: - **demo**: to which API consumers delegate access and therefore the one which access tokens are issued to diff --git a/docs/getting-started.md b/docs/getting-started.md index 3a0044d4..66ae049b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -12,19 +12,19 @@ These are the platform requirements to use Authorino: - [**Kubernetes**](https://kubernetes.io) server (recommended v1.20 or later), with permission to create Kubernetes Custom Resource Definitions (CRDs) (for bootstrapping Authorino and Authorino Operator) -
-Alternative: K8s distros and platforms +
+ Alternative: K8s distros and platforms -Alternatively to upstream Kubernetes, you should be able to use any other Kubernetes distribution or Kubernetes Management Platform (KMP) with support for Kubernetes Custom Resources Definitions (CRD) and custom controllers, such as Red Hat OpenShift, IBM Cloud Kubernetes Service (IKS), Google Kubernetes Engine (GKE), Amazon Elastic Kubernetes Service (EKS) and Azure Kubernetes Service (AKS). -
+ Alternatively to upstream Kubernetes, you should be able to use any other Kubernetes distribution or Kubernetes Management Platform (KMP) with support for Kubernetes Custom Resources Definitions (CRD) and custom controllers, such as Red Hat OpenShift, IBM Cloud Kubernetes Service (IKS), Google Kubernetes Engine (GKE), Amazon Elastic Kubernetes Service (EKS) and Azure Kubernetes Service (AKS). +
- [**Envoy**](https://www.envoyproxy.io) proxy (recommended v1.19 or later), to wire up Upstream services (i.e. the services to be protected with Authorino) and external authorization filter (Authorino) for integrations based on the reverse-proxy architecture - [example](https://github.com/kuadrant/authorino-examples#envoy) -
-Alternative: Non-reverse-proxy integration +
+ Alternative: Non-reverse-proxy integration -Technically, any client that implements Envoy's external authorization gRPC protocol should be compatible with Authorino. For integrations based on the reverse-proxy architecture nevertheless, we strongly recommended that you leverage Envoy alongside Authorino. -
+ Technically, any client that implements Envoy's external authorization gRPC protocol should be compatible with Authorino. For integrations based on the reverse-proxy architecture nevertheless, we strongly recommended that you leverage Envoy alongside Authorino. +
### Feature-specific requirements