Skip to content

Commit

Permalink
Merge pull request #445 from Kuadrant/md-in-html
Browse files Browse the repository at this point in the history
Markdown in HTML blocks
  • Loading branch information
guicassolato authored Nov 10, 2023
2 parents 48ce125 + 9c6e6c0 commit 0c3253a
Show file tree
Hide file tree
Showing 30 changed files with 68 additions and 65 deletions.
28 changes: 14 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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).
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand Down
21 changes: 12 additions & 9 deletions docs/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.
Expand All @@ -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:
Expand All @@ -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:
Expand Down Expand Up @@ -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/>
Expand All @@ -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
Expand Down
12 changes: 6 additions & 6 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/user-guides/anonymous-access.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
2 changes: 1 addition & 1 deletion docs/user-guides/api-key-authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
2 changes: 1 addition & 1 deletion docs/user-guides/authzed.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
2 changes: 1 addition & 1 deletion docs/user-guides/caching.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
2 changes: 1 addition & 1 deletion docs/user-guides/deny-with-redirect-to-login.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
Loading

0 comments on commit 0c3253a

Please sign in to comment.