Kuadrant · guicassolato · Nov 10, 2023 · Nov 8, 2023
diff --git a/README.md b/README.md
@@ -82,7 +82,7 @@ Under the hood, Authorino is based on Kubernetes [Custom Resource Definitions](h
 9. If authorized, Envoy triggers other HTTP filters in the chain (if any), pre-injecting eventual dynamic metadata returned by Authorino, and ultimately redirects the request to the _Upstream_
 10. The _Upstream_ serves the requested resource to the consumer
 
-<details>
+<details markdown="1">
   <summary>More</summary>
 
   The [Architecture](./docs/architecture.md) section of the docs covers details of protecting your APIs with Envoy and Authorino, including information about topology (centralized gateway, centralized authorization service or sidecars), deployment modes (cluster-wide reconciliation vs. namespaced instances), an specification of Authorino's [`AuthConfig`](./docs/architecture.md#the-authorino-authconfig-custom-resource-definition-crd) Custom Resource Definition (CRD) and more.
@@ -229,7 +229,7 @@ For a detailed description of the features above, refer to the [Features](./docs
 
 ## FAQ
 
-<details>
+<details markdown="1">
   <summary><strong>Do I need to deploy Envoy?</strong></summary>
 
   Authorino is built from the ground up to work well with Envoy. It is strongly recommended that you leverage Envoy along side Authorino. That said, it is possible to use Authorino without Envoy.
@@ -243,7 +243,7 @@ For a detailed description of the features above, refer to the [Features](./docs
   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.
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Is Authorino an Identity Provider (IdP)?</strong></summary>
 
   No, Authorino is not an Identity Provider (IdP). Neither it is an auth server of any kind, such as an OAuth2 server, an OpenID Connect (OIDC) server, a Single Sign On (SSO) server.
@@ -254,7 +254,7 @@ For a detailed description of the features above, refer to the [Features](./docs
 </details>
 
 
-<details>
+<details markdown="1">
   <summary><strong>How does Authorino compare to Keycloak?</strong></summary>
 
   Keycloak is a proper auth server and identity provider (IdP). It offers a huge set of features for managing identities, identity sources with multiple user federation options, and a platform for authentication and authorization services.
@@ -266,15 +266,15 @@ For a detailed description of the features above, refer to the [Features](./docs
   You can also use Keycloak for storing auth-relevant resource metadata. These can be fetched by Authorino in request-time, to be combined into your authorization policies. See Keycloak Authorization Services and User-Managed Access (UMA) support, as well as Authorino [UMA external metadata](./docs/features.md#user-managed-access-uma-resource-registry-metadatauma) counter-part.
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Why doesn't Authorino handle OAuth flows?</strong></summary>
 
   It has to do with trust. OAuth grants are supposed to be negotiated directly between whoever owns the long-lived credentials in one hand (user, service accounts), and the trustworthy auth server that receives those credentials – ideally with minimum number of hops in the middle – and exchanges them for short-lived access tokens, on the other end.
 
   There are use-cases for Authorino running in the edge (e.g. Edge Authentication Architecture and token normalization), but in most cases Authorino should be seen as a last-mile component that provides decoupled identity verification and authorization policy enforcement to protected services in request-time. In this sense, the OAuth grant is a pre-flight exchange that happens once and as direct and safe as possible, whereas auth enforcement is kept lightweight and efficient.
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Where does Authorino store users and roles?</strong></summary>
 
   Authorino does not store users, roles, role bindings, access control lists, or any raw authorization data. Authorino handles policies, where even these policies can be stored elsewhere (as opposed to stated inline inside of an Authorino `AuthConfig` CR).
@@ -284,7 +284,7 @@ For a detailed description of the features above, refer to the [Features](./docs
   In the case of authentication with API keys, as well as its derivative to model HTTP Basic Auth, user data are stored in Kubernetes `Secret`s. The secret's keys, annotations and labels are usually the structures used to organize the data that later a policy evaluated in Authorino may require. Strictly, those are not Authorino data structures.
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Can't I just use Envoy JWT Authentication and RBAC filters?</strong></summary>
 
   Envoy's [JWT Authentication](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/jwt_authn/v3/config.proto.html) works pretty much similar to Authorino's [JOSE/JWT verification and validation for OpenID Connect](./docs/features.md#jwt-verification-authenticationjwt). In both cases, the JSON Web Key Sets (JWKS) to verify the JWTs are auto-loaded and cached to be used in request-time. Moreover, you can configure for details such as where to extract the JWT from the HTTP request (header, param or cookie) and do some cool tricks regarding how dynamic metadata based on JWT claims can be injected to consecutive filters in the chain.
@@ -296,7 +296,7 @@ For a detailed description of the features above, refer to the [Features](./docs
   In summary, Envoy's JWT Authentication and Envoy RBAC filter are excellent solutions for simple use-cases where JWTs from one single issuer is the only authentication method you are planning to support and limited to no authorization rules suffice. On the other hand, if you need to integrate more identity sources, different types of authentication, authorization policies, etc, you might to consider Authorino.
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Should I use Authorino if I already have Istio configured?</strong></summary>
 
   Istio is a great solution for managing service meshes. It delivers an excellent platform with an interesting layer of abstraction on top of Envoy proxy's virtual omnipresence within the mesh.
@@ -322,7 +322,7 @@ For a detailed description of the features above, refer to the [Features](./docs
   The good news is that, if you have Istio configured, then you have Envoy and the whole platform for wiring Authorino up if you want to. 😉
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Do I have to learn OPA/Rego language to use Authorino?</strong></summary>
 
   No, you do not. However, if you are comfortable with [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/) from Open Policy Agent (OPA), there are some quite interesting things you can do in Authorino, just as you would in any OPA server or OPA plugin, but leveraging Authorino's [built-in OPA module](./docs/features.md#open-policy-agent-opa-rego-policies-authorizationopa) instead. Authorino's OPA module is compiled as part of Authorino's code directly from the Golang packages, and imposes no extra latency to the evaluation of your authorization policies. Even the policies themselves are pre-compiled in reconciliation-time, for fast evaluation afterwards, in request-time.
@@ -334,7 +334,7 @@ For a detailed description of the features above, refer to the [Features](./docs
   Authorino also packages well-established industry standards and protocols for identity verification (JOSE/JWT validation, OAuth token introspection, Kubernetes TokenReview) and ad-hoc request-time metadata fetching (OIDC userinfo, User-Managed Access (UMA)), and corresponding layers of caching, without which such functionalities would have to be implemented by code.
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Can I use Authorino to protect non-REST APIs?</strong></summary>
 
   Yes, you can. In principle, the API format (REST, gRPC, GraphQL, etc) should not matter for the authN/authZ enforcer. There are a couple points to consider though.
@@ -353,21 +353,21 @@ For a detailed description of the features above, refer to the [Features](./docs
   Check out Authorino [OPA authorization](./docs/features.md#open-policy-agent-opa-rego-policies-authorizationopa) and the Rego [Encoding](https://www.openpolicyagent.org/docs/latest/policy-reference/#encoding) functions for options to parse serialized JSON, YAML and URL-encoded params. For XML transformation, an external parsing service connected via Authorino's [HTTP GET/GET-by-POST external metadata](./docs/features.md#http-getget-by-post-metadatahttp) might be required.
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Can I run Authorino other than on Kubernetes?</strong></summary>
 
   As of today, no, you cannot, or at least it wouldn't suit production requirements.
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Do I have to be admin of the cluster to install Authorino?</strong></summary>
 
   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).
 
   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.
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Is it OK to store AuthN/AuthZ configs as Kubernetes objects?</strong></summary>
 
   Authorino's API checks all the bullets to be [aggregated to the Kubernetes cluster APIs](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#should-i-add-a-custom-resource-to-my-kubernetes-cluster), and therefore using Custom Resource Definition (CRD) and the [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator) has always been an easy design decision.
@@ -381,7 +381,7 @@ For a detailed description of the features above, refer to the [Features](./docs
   In other words, there are lots of benefits of using Kubernetes custom resources and custom controllers, and unless you are planning on bursting your server with more services than it can keep record, it is totally 👍 to store your AuthN/AuthZ configs as cluster API objects.
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Can I use Authorino for rate limiting?</strong></summary>
 
   You can, but you shouldn't. Check out instead [Limitador](https://github.com/kuadrant/limitador), for simple and efficient global rate limiting. Combine it with Authorino and Authorino's support for [Envoy Dynamic Metadata](./docs/features.md#envoy-dynamic-metadata) for authenticated rate limiting.

diff --git a/docs/contributing.md b/docs/contributing.md
@@ -30,7 +30,7 @@ The following tools can be installed as part of the development workflow:
   - [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
+  - [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
 
@@ -113,7 +113,7 @@ Once the deployment is ready, you can forward the requests on port 8000 to the E
 kubectl port-forward deployment/envoy 8000:8000 &
 ```
 
-<details>
+<details markdown="1">
   <summary>Pro tips</summary>
 
   1. Change the default workload namespace by supplying the `NAMESPACE` argument to your `make local-setup` and other deployment, apps and local cluster related targets. If the namespace does not exist, it will be created.
@@ -125,7 +125,7 @@ kubectl port-forward deployment/envoy 8000:8000 &
 
 #### Additional tools (for specific use-cases)
 
-<details>
+<details markdown="1">
   <summary><strong>Limitador</strong></summary>
 
   To deploy [Limitador](https://github.com/kuadrant/limitador) – pre-configured in Envoy for rate-limiting the Talker API to 5 hits per minute per `user_id` when available in the cluster workload –, run:
@@ -135,10 +135,11 @@ kubectl port-forward deployment/envoy 8000:8000 &
   ```
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Keycloak</strong></summary>
 
-  Authorino examples include a bundle of [Keycloak](https://www.keycloak.org) preloaded with the following realm setup:<br/>
+  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)
   - Preloaded realm: **kuadrant**
   - Preloaded clients:
@@ -171,10 +172,11 @@ kubectl port-forward deployment/envoy 8000:8000 &
   ```
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Dex</strong></summary>
 
-  Authorino examples include a bundle of [Dex](https://dexidp.io) preloaded with the following setup:<br/>
+  Authorino examples include a bundle of [Dex](https://dexidp.io) preloaded with the following setup:
+
   - Preloaded clients:<br/>
     - **demo**: to which API consumers delegate access and therefore the one which access tokens are issued to (Client secret: aaf88e0e-d41d-4325-a068-57c4b0d61d8e)
   - Preloaded users:<br/>
@@ -193,10 +195,11 @@ kubectl port-forward deployment/envoy 8000:8000 &
   ```
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>a12n-server</strong></summary>
 
-  Authorino examples include a bundle of [**a12n-server**](https://github.com/curveball/a12n-server) and corresponding MySQL database, preloaded with the following setup:<br/>
+  Authorino examples include a bundle of [**a12n-server**](https://github.com/curveball/a12n-server) and corresponding MySQL database, preloaded with the following setup:
+
   - Admin console: http://a12n-server:8531 (admin/123456)
   - Preloaded clients:<br/>
     - **service-account-1**: to obtain access tokens via `client_credentials` OAuth2 grant type, to consume the Talker API (Client secret: DbgXROi3uhWYCxNUq_U1ZXjGfLHOIM8X3C2bJLpeEdE); includes metadata privilege: `{ "talker-api": ["read"] }` that can be used to write authorization policies

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -18,15 +18,15 @@ 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)
 
-  <details>
+  <details markdown="1">
     <summary>Alternative: K8s distros and platforms</summary>
 
     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 <a href="https://www.openshift.com">Red Hat OpenShift</a>, <a href="https://www.ibm.com/cloud/kubernetes-service">IBM Cloud Kubernetes Service (IKS)</a>, <a href="http://cloud.google.com/kubernetes-engine">Google Kubernetes Engine (GKE)</a>, <a href="https://aws.amazon.com/eks">Amazon Elastic Kubernetes Service (EKS)</a> and <a href="https://azure.microsoft.com/en-us/services/kubernetes-service">Azure Kubernetes Service (AKS)</a>.
   </details>
 
 - [**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)
 
-  <details>
+  <details markdown="1">
     <summary>Alternative: Non-reverse-proxy integration</summary>
 
     Technically, any client that implements Envoy's <a href="https://www.envoyproxy.io/docs/envoy/latest/start/sandboxes/ext_authz">external authorization</a> 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.
@@ -66,7 +66,7 @@ Choose either [cluster-wide or namespaced deployment mode](./architecture.md#clu
 
 The instructions here are for centralized gateway or centralized authorization service architecture. Check out the [Topologies](./architecture.md#topologies) section of the docs for alternatively running Authorino in a sidecar container.
 
-<details>
+<details markdown="1">
   <summary><strong>Cluster-wide (with TLS)</strong></summary>
 
   Create the namespace:
@@ -103,7 +103,7 @@ The instructions here are for centralized gateway or centralized authorization s
   ```
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Cluster-wide (without TLS)</strong></summary>
 
   ```sh
@@ -127,7 +127,7 @@ The instructions here are for centralized gateway or centralized authorization s
   ```
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Namespaced (with TLS)</strong></summary>
 
   Create the namespace:
@@ -165,7 +165,7 @@ The instructions here are for centralized gateway or centralized authorization s
   ```
 </details>
 
-<details>
+<details markdown="1">
   <summary><strong>Namespaced (without TLS)</strong></summary>
 
   ```sh

diff --git a/docs/user-guides/anonymous-access.md b/docs/user-guides/anonymous-access.md
@@ -2,7 +2,7 @@
 
 Bypass identity verification or fall back to anonymous access when credentials fail to validate
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>

diff --git a/docs/user-guides/api-key-authentication.md b/docs/user-guides/api-key-authentication.md
@@ -2,7 +2,7 @@
 
 Issue API keys stored in Kubernetes `Secret`s for clients to authenticate with your protected hosts.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>

diff --git a/docs/user-guides/authenticated-rate-limiting-envoy-dynamic-metadata.md b/docs/user-guides/authenticated-rate-limiting-envoy-dynamic-metadata.md
@@ -2,7 +2,7 @@
 
 Provide Envoy with dynamic metadata about the external authorization process to be injected into the rate limiting filter.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>

diff --git a/docs/user-guides/authzed.md b/docs/user-guides/authzed.md
@@ -2,7 +2,7 @@
 
 Permission requests sent to a Google Zanzibar-based [Authzed/SpiceDB](https://authzed.com) instance, via gRPC.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>

diff --git a/docs/user-guides/caching.md b/docs/user-guides/caching.md
@@ -15,7 +15,7 @@ Cases where one will **NOT** want to enable caching, due to relatively cheap com
 - Dynamic JSON responses
 - Anonymous access
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>

diff --git a/docs/user-guides/deny-with-redirect-to-login.md b/docs/user-guides/deny-with-redirect-to-login.md
@@ -2,7 +2,7 @@
 
 Customize response status code and headers on failed requests to redirect users of a web application protected with Authorino to a login page instead of a `401 Unauthorized`.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>

diff --git a/docs/user-guides/edge-authentication-architecture-festival-wristbands.md b/docs/user-guides/edge-authentication-architecture-festival-wristbands.md
@@ -10,7 +10,7 @@ The very definition of "edge" is subject to discussion, but the underlying idea
 
 As a minimum, EAA allows to simplify authentication between applications and microservices inside the network, as well as to reduce authorization to domain-specific rules and policies, rather than having to deal all the complexity to support all types of clients in every node.
 
-<details>
+<details markdown="1">
   <summary>
     <strong>Authorino capabilities featured in this guide:</strong>
     <ul>