From 010e1ec0ee82b87ba12cbcaaf2a0379cdf943c59 Mon Sep 17 00:00:00 2001 From: Guilherme Cassolato Date: Tue, 24 Oct 2023 15:42:22 +0200 Subject: [PATCH] docs: instructions for Kuadrant users and enhancements --- docs/user-guides/anonymous-access.md | 87 ++++++++--- docs/user-guides/api-key-authentication.md | 97 +++++++++---- ...ed-rate-limiting-envoy-dynamic-metadata.md | 111 +++++++++----- docs/user-guides/authzed.md | 103 +++++++++---- docs/user-guides/caching.md | 121 +++++++++++----- .../deny-with-redirect-to-login.md | 124 +++++++++++----- ...cation-architecture-festival-wristbands.md | 135 ++++++++++++------ .../envoy-jwt-authn-and-authorino.md | 117 ++++++++++----- docs/user-guides/external-metadata.md | 111 +++++++++----- docs/user-guides/hello-world.md | 103 +++++++++---- docs/user-guides/host-override.md | 18 ++- docs/user-guides/http-basic-authentication.md | 113 ++++++++++----- docs/user-guides/injecting-data.md | 101 +++++++++---- .../json-pattern-matching-authorization.md | 115 ++++++++++----- .../keycloak-authorization-services.md | 105 ++++++++++---- .../kubernetes-subjectaccessreview.md | 113 ++++++++++----- docs/user-guides/kubernetes-tokenreview.md | 110 +++++++++----- docs/user-guides/mtls-authentication.md | 105 ++++++++++---- .../user-guides/oauth2-token-introspection.md | 135 +++++++++++------- docs/user-guides/observability.md | 4 +- docs/user-guides/oidc-jwt-authentication.md | 105 +++++++++----- docs/user-guides/oidc-rbac.md | 115 ++++++++++----- docs/user-guides/oidc-user-info.md | 111 +++++++++----- docs/user-guides/opa-authorization.md | 107 +++++++++----- docs/user-guides/passing-credentials.md | 107 +++++++++----- .../resource-level-authorization-uma.md | 134 ++++++++++------- docs/user-guides/sharding.md | 44 ++++-- docs/user-guides/token-normalization.md | 113 ++++++++++----- docs/user-guides/validating-webhook.md | 115 ++++++++++----- tests/e2e-test.sh | 2 +- tests/v1beta1/authconfig-invalid.yaml | 2 +- tests/v1beta1/authconfig.yaml | 2 +- tests/v1beta2/authconfig-invalid.yaml | 2 +- tests/v1beta2/authconfig.yaml | 2 +- 34 files changed, 2056 insertions(+), 933 deletions(-) diff --git a/docs/user-guides/anonymous-access.md b/docs/user-guides/anonymous-access.md index dfd70762..3325b3ea 100644 --- a/docs/user-guides/anonymous-access.md +++ b/docs/user-guides/anonymous-access.md @@ -4,7 +4,7 @@ Bypass identity verification or fall back to anonymous access when credentials f
- Authorino features in this guide: + Authorino capabilities featured in this guide: @@ -17,29 +17,48 @@ Bypass identity verification or fall back to anonymous access when credentials f ## Requirements -- Kubernetes server +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -## 1. Install the Authorino Operator +
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❺.

+

At step ❺, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
+ +
-## 2. Deploy the Talker API +## ❶ Install the Authorino Operator (cluster admin required) -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 4. Setup Envoy +## ❸ Deploy the Talker API -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❹ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 5. Create the `AuthConfig` +## ❺ Create an `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced: + + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
```sh kubectl apply -f -< - Authorino features in this guide: + Authorino capabilities featured in this guide:
    -
  • Identity verification & authentication → API key
    • +
  • Identity verification & authentication → API key
 @@ -14,36 +14,55 @@ Issue API keys stored in Kubernetes `Secret`s for clients to authenticate with y API key `Secret`s must also include labels that match the `secretLabelSelector` field of the Authorino instance. See [Resource reconciliation and status update](../architecture.md#resource-reconciliation-and-status-update) for details. - For further details about Authorino features in general, check the [docs](./../features.md). + For further details about Authorino features in general, check the [docs](../features.md).

## Requirements -- Kubernetes server +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -## 1. Install the Authorino Operator +
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❺.

+

At step ❺, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
+ +
-## 2. Deploy the Talker API +## ❶ Install the Authorino Operator (cluster admin required) -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 4. Setup Envoy +## ❸ Deploy the Talker API -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❹ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 5. Create the `AuthConfig` +## ❺ Create an `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced: + + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
```sh kubectl apply -f -< - Authorino features in this guide: + Authorino capabilities featured in this guide: - Dynamic JSON objects built out of static values and values fetched from the [Authorization JSON](./../architecture.md#the-authorization-json) can be wrapped to be returned to the reverse-proxy as Envoy Well Known Dynamic Metadata content. Envoy can use those to inject data returned by the external authorization service into the other filters, such as the rate limiting filter. + Dynamic JSON objects built out of static values and values fetched from the [Authorization JSON](../architecture.md#the-authorization-json) can be wrapped to be returned to the reverse-proxy as Envoy Well Known Dynamic Metadata content. Envoy can use those to inject data returned by the external authorization service into the other filters, such as the rate limiting filter. - Check out as well the user guides about [Injecting data in the request](./injecting-data.md) and [Authentication with API keys](./api-key-authentication.md). + Check out as well the user guides about [Injecting data in the request](injecting-data.md) and [Authentication with API keys](api-key-authentication.md). - For further details about Authorino features in general, check the [docs](./../features.md). + For further details about Authorino features in general, check the [docs](../features.md).
## Requirements -- Kubernetes server +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -## 1. Install the Authorino Operator +
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❻.

+

At step ❻, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
+ +
-## 2. Deploy the Talker API +## ❶ Install the Authorino Operator (cluster admin required) -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 4. Deploy Limitador +## ❸ Deploy Limitador [Limitador](https://github.com/kuadrant/limitador) is a lightweight rate limiting service that can be used with Envoy. @@ -75,23 +96,47 @@ On this bundle, we will deploy Limitador pre-configured to limit requests to the kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/limitador/limitador-deploy.yaml ``` -## 5. Setup Envoy +## ❹ Deploy the Talker API -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❺ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 6. Create the `AuthConfig` +## ❻ Create an `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced. + +An annotation `auth-data/username` will be read from the Kubernetes API Key secret and passed as dynamic metadata `{ "ext_auth_data": { "username": «annotations.auth-data/username» } }`. + + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
```sh kubectl apply -f -< - Authorino features in this guide: + Authorino capabilities featured in this guide:
    -
  • Authorization → SpiceDB
    • -
  • Identity verification & authentication → API key
    • +
  • Authorization → SpiceDB
    • +
  • Identity verification & authentication → API key
 @@ -16,29 +16,48 @@ Permission requests sent to a Google Zanzibar-based [Authzed/SpiceDB](https://au ## Requirements -- Kubernetes server +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -## 1. Install the Authorino Operator +
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❻.

+

At step ❻, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
+ +
-## 2. Deploy the Talker API +## ❶ Install the Authorino Operator (cluster admin required) -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 4. Setup Envoy +## ❸ Deploy the Talker API -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❹ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 5. Create the permission database +## ❺ Create the permission database Create the namespace: @@ -131,7 +160,7 @@ spec: EOF ``` -Forward local request to the SpiceDB service: +Forward local request to the SpiceDB service inside the cluster: ```sh kubectl -n spicedb port-forward service/spicedb 8443:8443 2>&1 >/dev/null & @@ -199,7 +228,21 @@ curl -X POST http://localhost:8443/v1/relationships/write \ EOF ``` -## 6. Create the `AuthConfig` +## ❺ Create an `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced. + + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
Store the shared token for Authorino to authenticate with the SpiceDB instance in a Service: @@ -226,7 +269,7 @@ metadata: name: talker-api-protection spec: hosts: - - talker-api-authorino.127.0.0.1.nip.io + - talker-api.127.0.0.1.nip.io authentication: "blog-users": apiKey: @@ -259,7 +302,7 @@ spec: EOF ``` -## 7. Create the API keys +## ❼ Create the API keys For Emilia (writer): @@ -297,14 +340,14 @@ stringData: EOF ``` -## 8. Consume the API +## ❽ Consume the API As Emilia, send a GET request: ```sh curl -H 'Authorization: APIKEY IAMEMILIA' \ -X GET \ - http://talker-api-authorino.127.0.0.1.nip.io:8000/posts/1 -i + http://talker-api.127.0.0.1.nip.io:8000/posts/1 -i # HTTP/1.1 200 OK ``` @@ -313,7 +356,7 @@ As Emilia, send a POST request: ```sh curl -H 'Authorization: APIKEY IAMEMILIA' \ -X POST \ - http://talker-api-authorino.127.0.0.1.nip.io:8000/posts/1 -i + http://talker-api.127.0.0.1.nip.io:8000/posts/1 -i # HTTP/1.1 200 OK ``` @@ -322,7 +365,7 @@ As Beatrice, send a GET request: ```sh curl -H 'Authorization: APIKEY IAMBEATRICE' \ -X GET \ - http://talker-api-authorino.127.0.0.1.nip.io:8000/posts/1 -i + http://talker-api.127.0.0.1.nip.io:8000/posts/1 -i # HTTP/1.1 200 OK ``` @@ -331,7 +374,7 @@ As Beatrice, send a POST request: ```sh curl -H 'Authorization: APIKEY IAMBEATRICE' \ -X POST \ - http://talker-api-authorino.127.0.0.1.nip.io:8000/posts/1 -i + http://talker-api.127.0.0.1.nip.io:8000/posts/1 -i # HTTP/1.1 403 Forbidden # x-ext-auth-reason: PERMISSIONSHIP_NO_PERMISSION;token=GhUKEzE2NzU3MDE3MjAwMDAwMDAwMDA= ``` @@ -349,9 +392,9 @@ Otherwise, delete the resources created in each step: ```sh kubectl delete secret/api-key-1 kubectl delete authconfig/talker-api-protection -kubectl delete authorino/authorino kubectl delete -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml kubectl delete -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +kubectl delete authorino/authorino kubectl delete namespace spicedb ``` diff --git a/docs/user-guides/caching.md b/docs/user-guides/caching.md index 487bdb46..7243ae73 100644 --- a/docs/user-guides/caching.md +++ b/docs/user-guides/caching.md @@ -17,46 +17,65 @@ Cases where one will **NOT** want to enable caching, due to relatively cheap com
- Authorino features in this guide: + Authorino capabilities featured in this guide: - For further details about Authorino features in general, check the [docs](./../features.md). + For further details about Authorino features in general, check the [docs](../features.md).

## Requirements -- Kubernetes server +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -## 1. Install the Authorino Operator +
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❺.

+

At step ❺, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
-## 2. Deploy the Talker API +
-The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +## ❶ Install the Authorino Operator (cluster admin required) + +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 4. Setup Envoy +## ❸ Deploy the Talker API -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❹ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 5. Create the `AuthConfig` +## ❺ Create an `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced. + +The example below enables caching for the external source of metadata, which in this case, for convenience, is the same upstream API protected by Authorino (i.e. the Talker API), though consumed directly by Authorino, without passing through the proxy. This API generates a `uuid` random hash that it injects in the JSON response. This value is different in every request processed by the API. + +The example also enables caching of returned OPA virtual documents. `cached-authz` is a trivial Rego policy that always grants access, but generates a timestamp, which Authorino will cache. + +In both cases, the path of the HTTP request is used as cache key. I.e., whenever the path repeats, Authorino reuse the values stored previously in each cache table (`cached-metadata` and `cached-authz`), respectively saving a request to the external source of metadata and the evaluation of the OPA policy. Cache entries will expire in both cases after 60 seconds they were stored in the cache. + +The cached values will be visible in the response returned by the Talker API in `x-authz-data` header injected by Authorino. This way, we can tell when an existing value in the cache was used and when a new one was generated and stored. + + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
```sh kubectl apply -f -< - Authorino features in this guide: + Authorino capabilities featured in this guide: - Authorino's default response status codes, messages and headers for unauthenticated (`401`) and unauthorized (`403`) requests can be customized with static values and values fetched from the [Authorization JSON](./../architecture.md#the-authorization-json). + Authorino's default response status codes, messages and headers for unauthenticated (`401`) and unauthorized (`403`) requests can be customized with static values and values fetched from the [Authorization JSON](../architecture.md#the-authorization-json). - Check out as well the user guides about [HTTP "Basic" Authentication (RFC 7235)](./user-guides/http-basic-authentication.md) and [OpenID Connect Discovery and authentication with JWTs](./oidc-jwt-authentication.md). + Check out as well the user guides about [HTTP "Basic" Authentication (RFC 7235)](user-guides/http-basic-authentication.md) and [OpenID Connect Discovery and authentication with JWTs](oidc-jwt-authentication.md). - For further details about Authorino features in general, check the [docs](./../features.md). + For further details about Authorino features in general, check the [docs](../features.md).
## Requirements -- Kubernetes server +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -## 1. Install the Authorino Operator +
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +The next steps walk you through installing Authorino, deploying and configuring a sample web application called **Matrix Quotes** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❺.

+

At step ❺, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
-## 2. Deploy the Matrix Quotes web application +
-The **Matrix Quotes** is a static web application that contains quotes from the film _The Matrix_. +## ❶ Install the Authorino Operator (cluster admin required) + +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/matrix-quotes/matrix-quotes-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. + +## ❸ Deploy the Matrix Quotes web application -## 4. Setup Envoy +The **Matrix Quotes** is a static web application that contains quotes from the film _The Matrix_. + +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/matrix-quotes/matrix-quotes-deploy.yaml +``` + +## ❹ Setup Envoy -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Matrix Quotes webapp behind the reverse-proxy and external authorization with the Authorino instance. +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Matrix Quotes webapp behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/matrix-quotes/envoy-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `matrix-quotes-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `matrix-quotes.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 5. Create the `AuthConfig` +## ❺ Create an `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced. + +The following defines a JSON object to be injected as an added HTTP header into the request, named after the response config `x-ext-auth-data`. The object includes 3 properties: +1. a static value `authorized: true`; +2. a dynamic value `request-time`, from Envoy-supplied contextual data present in the Authorization JSON; and +3. a greeting message `geeting-message` that interpolates a dynamic value read from an annotation of the Kubernetes `Secret` resource that represents the API key used to authenticate into a static string. + + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
```sh kubectl apply -f -<> /etc/hosts Forward local requests to the instance of Keycloak running in the cluster: ```sh -kubectl port-forward deployment/keycloak 8080:8080 & +kubectl port-forward deployment/keycloak 8080:8080 2>&1 >/dev/null & ``` Create a client: @@ -183,7 +231,7 @@ Create a client: ```sh curl -H "Authorization: Bearer $(curl http://keycloak:8080/auth/realms/master/protocol/openid-connect/token -s -d 'grant_type=password' -d 'client_id=admin-cli' -d 'username=admin' -d 'password=p' | jq -r .access_token)" \ -H 'Content-type: application/json' \ - -d '{ "name": "matrix-quotes", "clientId": "matrix-quotes", "publicClient": true, "redirectUris": ["http://matrix-quotes-authorino.127.0.0.1.nip.io:8000/auth*"], "enabled": true }' \ + -d '{ "name": "matrix-quotes", "clientId": "matrix-quotes", "publicClient": true, "redirectUris": ["http://matrix-quotes.127.0.0.1.nip.io:8000/auth*"], "enabled": true }' \ http://keycloak:8080/auth/admin/realms/kuadrant/clients ``` @@ -203,7 +251,7 @@ metadata: name: matrix-quotes-protection spec: hosts: - - matrix-quotes-authorino.127.0.0.1.nip.io + - matrix-quotes.127.0.0.1.nip.io authentication: "idp-users": jwt: @@ -216,13 +264,13 @@ spec: code: 302 headers: "Location": - selector: "http://keycloak:8080/auth/realms/kuadrant/protocol/openid-connect/auth?client_id=matrix-quotes&redirect_uri=http://matrix-quotes-authorino.127.0.0.1.nip.io:8000/auth?redirect_to={context.request.http.path}&scope=openid&response_type=code" + selector: "http://keycloak:8080/auth/realms/kuadrant/protocol/openid-connect/auth?client_id=matrix-quotes&redirect_uri=http://matrix-quotes.127.0.0.1.nip.io:8000/auth?redirect_to={context.request.http.path}&scope=openid&response_type=code" EOF ``` ### Consume the application again -Refresh the browser window or navigate again to http://matrix-quotes-authorino.127.0.0.1.nip.io:8000. +Refresh the browser window or navigate again to http://matrix-quotes.127.0.0.1.nip.io:8000. Click on the cards to read quotes from characters of the movie. You should be redirected to login page this time served by the Keycloak server. @@ -245,9 +293,9 @@ Otherwise, delete the resources created in each step: ```sh kubectl delete secret/user-credential-1 kubectl delete authconfig/matrix-quotes-protection -kubectl delete authorino/authorino kubectl delete -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml kubectl delete -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/matrix-quotes/matrix-quotes-deploy.yaml +kubectl delete authorino/authorino kubectl delete -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/keycloak/keycloak-deploy.yaml ``` diff --git a/docs/user-guides/edge-authentication-architecture-festival-wristbands.md b/docs/user-guides/edge-authentication-architecture-festival-wristbands.md index 902f9054..16f9d4ae 100644 --- a/docs/user-guides/edge-authentication-architecture-festival-wristbands.md +++ b/docs/user-guides/edge-authentication-architecture-festival-wristbands.md @@ -12,57 +12,78 @@ As a minimum, EAA allows to simplify authentication between applications and mic
- Authorino features in this guide: + Authorino capabilities featured in this guide: - Festival Wristbands are OpenID Connect ID tokens (signed JWTs) issued by Authorino by the end of the Auth Pipeline, for authorized requests. It can be configured to include claims based on static values and values fetched from the [Authorization JSON](./../architecture.md#the-authorization-json). + Festival Wristbands are OpenID Connect ID tokens (signed JWTs) issued by Authorino by the end of the Auth Pipeline, for authorized requests. It can be configured to include claims based on static values and values fetched from the [Authorization JSON](../architecture.md#the-authorization-json). - Check out as well the user guides about [Token normalization](./token-normalization.md), [Authentication with API keys](./api-key-authentication.md) and [OpenID Connect Discovery and authentication with JWTs](./oidc-jwt-authentication.md). + Check out as well the user guides about [Token normalization](token-normalization.md), [Authentication with API keys](api-key-authentication.md) and [OpenID Connect Discovery and authentication with JWTs](oidc-jwt-authentication.md). - For further details about Authorino features in general, check the [docs](./../features.md). + For further details about Authorino features in general, check the [docs](../features.md).

## Requirements -- Kubernetes server -- Auth server / Identity Provider (IdP) that implements OpenID Connect authentication and OpenID Connect Discovery (e.g. [Keycloak](https://www.keycloak.org)) -- [jq](https://stedolan.github.io/jq/), to extract parts of JSON responses +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) +- Identity Provider (IdP) that implements OpenID Connect authentication and OpenID Connect Discovery (e.g. [Keycloak](https://www.keycloak.org)) +- [jq](https://stedolan.github.io/jq), to extract parts of JSON responses - [jwt](https://github.com/mike-engel/jwt-cli), to inspect JWTs (optional) -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -Deploy a Keycloak server preloaded with all the realm settings required for this guide: +Deploy the identity provider and authentication server by executing the command below. For the examples in this guide, we are going to use a Keycloak server preloaded with all required realm settings. ```sh kubectl create namespace keycloak kubectl -n keycloak apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/keycloak/keycloak-deploy.yaml ``` -Forward local requests to the instance of Keycloak running in the cluster: +
-```sh -kubectl -n keycloak port-forward deployment/keycloak 8080:8080 & -``` +The next steps walk you through installing Authorino and configuring 2 environments of an architecture, `edge` and `internal`. + +The first environment is a facade for handling the first layer of authentication and exchanging any valid presented authentication token for a Festival Wristband token. In the second, we will deploy a sample service called **Talker API** that the authorization service will ensure to receive only authenticated traffic presented with a valid Festival Wristband. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❹.

+

At steps ❹ and ❺, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
+ +
-## 1. Install the Authorino Operator +## ❶ Install the Authorino Operator (cluster admin required) + +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 2. Create the namespaces +## ❷ Create the namespaces For simplicity, this examples will set up edge and internal nodes in different namespaces of the same Kubernetes cluster. Those will share a same single cluster-wide Authorino instance. In real-life scenarios, it does not have to be like that. @@ -72,7 +93,9 @@ kubectl create namespace edge kubectl create namespace internal ``` -## 3. Deploy Authorino +## ❸ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources cluster-wide[^2], with TLS disabled[^3]. ```sh kubectl -n authorino apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `cluster-wide` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 5. Setup the Edge +## ❹ Setup the Edge ### Setup Envoy -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up external authorization with the Authorino instance. +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up external authorization with the Authorino instance.[^4] -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl -n edge apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/eaa/envoy-edge-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `edge-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 9000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `edge.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 9000 to the Envoy service running inside the cluster: ```sh -kubectl -n edge port-forward deployment/envoy 9000:9000 & +kubectl -n edge port-forward deployment/envoy 9000:9000 2>&1 >/dev/null & ``` ### Create the `AuthConfig` -Create a required secret, used by Authorino to sign the Festival Wristband tokens: +Create a required secret that will be used by Authorino to sign the Festival Wristband tokens: ```sh kubectl -n edge apply -f -< + + + + Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. + + + + + ```sh kubectl -n edge apply -f -< Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +This other bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance. ```sh kubectl -n internal apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/eaa/envoy-node-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl -n internal port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` ### Create the `AuthConfig` + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
+ ```sh kubectl -n internal apply -f -< - Authorino features in this guide: + Authorino capabilities featured in this guide: - For further details about Authorino features in general, check the [docs](./../features.md). + For further details about Authorino features in general, check the [docs](../features.md).
## Requirements -- Kubernetes server -- Auth server / Identity Provider (IdP) that implements OpenID Connect authentication and OpenID Connect Discovery (e.g. [Keycloak](https://www.keycloak.org)) +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) +- Identity Provider (IdP) that implements OpenID Connect authentication and OpenID Connect Discovery (e.g. [Keycloak](https://www.keycloak.org)) - [jq](https://stedolan.github.io/jq), to extract parts of JSON responses -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -Deploy a Keycloak server preloaded with all the realm settings required for this guide: +Deploy the identity provider and authentication server by executing the command below. For the examples in this guide, we are going to use a Keycloak server preloaded with all required realm settings. ```sh kubectl create namespace keycloak kubectl -n keycloak apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/keycloak/keycloak-deploy.yaml ``` -## 1. Install the Authorino Operator +
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❻.

+

At step ❻, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
+ +
-## 2. Deploy the Talker API +## ❶ Install the Authorino Operator (cluster admin required) -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. + +## ❸ Deploy the Talker API -## 4. Setup Envoy +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -The command below creates the Envoy configuration and deploys the Envoy proxy wire up the Talker API and external authorization with Authorino. +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❹ Setup Envoy + +The following command deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f -<&1 >/dev/null & ``` -## 5. Deploy the IP Location service +## ❺ Deploy the IP Location service + +The **IP Location service** is a simple service that resolves an IPv4 address into geo location info. ```sh kubectl apply -f https://raw.githubusercontent.com/Kuadrant/authorino-examples/main/ip-location/ip-location-deploy.yaml ``` -## 6. Create the `AuthConfig` +## ❻ Create an `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced: + + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
```sh kubectl apply -f -< - Authorino features in this guide: + Authorino capabilities featured in this guide: - You can configure Authorino to fetch additional metadata from external sources in request-time, by sending either GET or POST request to an HTTP service. The service is expected to return a JSON content which is appended to the [Authorization JSON](./../architecture.md#the-authorization-json), thus becoming available for usage in other configs of the Auth Pipeline, such as in authorization policies or custom responses. + You can configure Authorino to fetch additional metadata from external sources in request-time, by sending either GET or POST request to an HTTP service. The service is expected to return a JSON content which is appended to the [Authorization JSON](../architecture.md#the-authorization-json), thus becoming available for usage in other configs of the Auth Pipeline, such as in authorization policies or custom responses. URL, parameters and headers of the request to the external source of metadata can be configured, including with dynamic values. Authentication between Authorino and the service can be set as part of these configuration options, or based on shared authentication token stored in a Kubernetes `Secret`. - Check out as well the user guides about [Authentication with API keys](./api-key-authentication.md) and [Open Policy Agent (OPA) Rego policies](./opa-authorization.md). + Check out as well the user guides about [Authentication with API keys](api-key-authentication.md) and [Open Policy Agent (OPA) Rego policies](opa-authorization.md). - For further details about Authorino features in general, check the [docs](./../features.md). + For further details about Authorino features in general, check the [docs](../features.md).
## Requirements -- Kubernetes server +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -## 1. Install the Authorino Operator +
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❺.

+

At step ❺, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
+ +
-## 2. Deploy the Talker API +## ❶ Install the Authorino Operator (cluster admin required) -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 4. Setup Envoy +## ❸ Deploy the Talker API -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❹ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 5. Create the `AuthConfig` +## ❺ Create an `AuthConfig` -In this example, we will implement a geofence policy for the API, using OPA and metadata fetching from an external service that returns geolocalization JSON data for a given IP address. The policy establishes that only `GET` requests are allowed and the path of the request should be in the form `/{country-code}/*`, where `{country-code}` is the 2-character code of the country where the client is identified as in. +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced. + +In this example, we will implement a geofence policy for the API, using OPA and metadata fetching from an external service that returns geolocalization JSON data for a given IP address. The policy establishes that only `GET` requests are allowed and the path of the request should be in the form `/{country-code}/*`, where `{country-code}` is the 2-character code of the country where the client is identified as being physically present. The implementation relies on the [`X-Forwarded-For`](https://datatracker.ietf.org/doc/html/rfc7239) HTTP header to read the client's IP address. + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
+ ```sh kubectl apply -f -< + +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant, you can skip step ❸. You may already have Authorino installed and running as well. In this case, skip also step ❺. If you even have your workload cluster configured, with sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, go straight to step ❼.

+

At step ❼, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
+ +
+ +## ❶ Create the namespace ```sh kubectl create namespace hello-world # namespace/hello-world created ``` -## 2. Deploy the Talker API +## ❷ Deploy the Talker API -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. ```sh kubectl -n hello-world apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml @@ -29,7 +52,11 @@ kubectl -n hello-world apply -f https://raw.githubusercontent.com/kuadrant/autho # service/talker-api created ``` -## 3. Setup Envoy +## ❸ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl -n hello-world apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/hello-world/envoy-deploy.yaml @@ -38,20 +65,20 @@ kubectl -n hello-world apply -f https://raw.githubusercontent.com/kuadrant/autho # service/envoy created ``` -Forward requests on port 8000 to the Envoy pod running inside the cluster: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl -n hello-world port-forward deployment/envoy 8000:8000 & +kubectl -n hello-world port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 4. Consume the API (unprotected) +## ❹ Consume the API (unprotected) ```sh -curl http://talker-api-authorino.127.0.0.1.nip.io:8000/hello -i +curl http://talker-api.127.0.0.1.nip.io:8000/hello -i # HTTP/1.1 200 OK ``` -## 5. Protect the API +## ❺ Protect the API ### Install the Authorino Operator @@ -61,34 +88,53 @@ curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/util ### Deploy Authorino +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `hello-world` namespace[^2], with TLS disabled[^3]. + ```sh kubectl -n hello-world apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/hello-world/authorino.yaml # authorino.operator.authorino.kuadrant.io/authorino created ``` -The command above will deploy Authorino as a separate service (in contrast to as a sidecar of the Talker API and other architectures). For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +[^1]: In contrast to a dedicated sidecar of the protected service and other architectures. Check out __Architecture > [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. + -## 6. Consume the API behind Envoy and Authorino +## ❻ Consume the API behind Envoy and Authorino ```sh -curl http://talker-api-authorino.127.0.0.1.nip.io:8000/hello -i +curl http://talker-api.127.0.0.1.nip.io:8000/hello -i # HTTP/1.1 404 Not Found # x-ext-auth-reason: Service not found ``` -Authorino does not know about the `talker-api-authorino.127.0.0.1.nip.io` host, hence the `404 Not Found`. Teach it by applying an `AuthConfig`. +Authorino does not know about the `talker-api.127.0.0.1.nip.io` host, hence the `404 Not Found`. Let's teach Authorino about this host by applying an `AuthConfig`. -## 7. Apply an `AuthConfig` +## ❼ Apply the `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced: + + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
```sh kubectl -n hello-world apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/hello-world/authconfig.yaml # authconfig.authorino.kuadrant.io/talker-api-protection created ``` -## 8. Consume the API without credentials +## ❽ Consume the API without credentials ```sh -curl http://talker-api-authorino.127.0.0.1.nip.io:8000/hello -i +curl http://talker-api.127.0.0.1.nip.io:8000/hello -i # HTTP/1.1 401 Unauthorized # www-authenticate: APIKEY realm="api-clients" # x-ext-auth-reason: credential not found @@ -96,16 +142,17 @@ curl http://talker-api-authorino.127.0.0.1.nip.io:8000/hello -i ## Grant access to the API with a tailor-made security scheme -Check out other [user guides](./../user-guides.md) for several AuthN/AuthZ use-cases and instructions to implement them using Authorino. A few examples are: - -- [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) -- [Authorization with Open Policy Agent (OPA) Rego policies](./opa-authorization.md) -- [Authorization with simple JSON pattern-matching rules (e.g. JWT claims)](./json-pattern-matching-authorization.md) -- [Authorization with Kubernetes RBAC (SubjectAccessReview API)](./kubernetes-subjectaccessreview.md) -- [Fetching auth metadata from external sources](./external-metadata.md) -- [Token normalization](./token-normalization.md) +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) +- [Authorization with Open Policy Agent (OPA) Rego policies](opa-authorization.md) +- [Authorization with simple JSON pattern-matching rules (e.g. JWT claims)](json-pattern-matching-authorization.md) +- [Authorization with Kubernetes RBAC (SubjectAccessReview API)](kubernetes-subjectaccessreview.md) +- [Fetching auth metadata from external sources](external-metadata.md) +- [Token normalization](token-normalization.md) ## Cleanup diff --git a/docs/user-guides/host-override.md b/docs/user-guides/host-override.md index 8111f0c8..1f28ef9e 100644 --- a/docs/user-guides/host-override.md +++ b/docs/user-guides/host-override.md @@ -1,13 +1,27 @@ # Host override via context extension -By default, Authorino uses the host information of the HTTP request ([`Attributes.Http.Host`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/attribute_context.proto#service-auth-v3-attributecontext-httprequest)) to lookup for an indexed AuthConfig to be enforced. The host info be overridden by supplying a `host` entry as a (per-route) context extension ([`Attributes.ContextExtensions`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/attribute_context.proto#envoy-v3-api-field-service-auth-v3-attributecontext-context-extensions)), which takes precedence whenever present. +By default, Authorino uses the host information of the HTTP request ([`Attributes.Http.Host`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/attribute_context.proto#service-auth-v3-attributecontext-httprequest)) to lookup for an indexed AuthConfig to be enforced[^1]. The host info be overridden by supplying a `host` entry as a (per-route) context extension ([`Attributes.ContextExtensions`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/attribute_context.proto#envoy-v3-api-field-service-auth-v3-attributecontext-context-extensions)), which takes precedence whenever present. Overriding the host attribute of the HTTP request can be useful to support use cases such as of **path prefix-based lookup** and **wildcard subdomains lookup**. + + + + + + +
+ ⚠️ Important: + This feature may not be available to users of Authorino via Kuadrant. +
+ +
+ +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) -For further details about Authorino lookup of AuthConfig, check out [Host lookup](./../architecture.md#host-lookup). +[^1]: For further details about Authorino lookup of AuthConfig, check out [Host lookup](../architecture.md#host-lookup). ## Example of host override for path prefix-based lookup diff --git a/docs/user-guides/http-basic-authentication.md b/docs/user-guides/http-basic-authentication.md index 415bcca9..c5a7aca4 100644 --- a/docs/user-guides/http-basic-authentication.md +++ b/docs/user-guides/http-basic-authentication.md @@ -4,10 +4,10 @@ Turn Authorino API key `Secret`s settings into HTTP basic auth.
- Authorino features in this guide: + Authorino capabilities featured in this guide: @@ -15,38 +15,57 @@ Turn Authorino API key `Secret`s settings into HTTP basic auth. In Authorino, HTTP "Basic" Authentication can be modeled leveraging the API key authentication feature (stored as Kubernetes `Secret`s with an `api_key` entry and labeled to match selectors specified in `spec.identity.apiKey.selector` of the `AuthConfig`). - Check out as well the user guide about [Authentication with API keys](./api-key-authentication.md). + 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). + For further details about Authorino features in general, check the [docs](../features.md).

## Requirements -- Kubernetes server +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -## 1. Install the Authorino Operator +
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❺.

+

At step ❺, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
+ +
-## 2. Deploy the Talker API +## ❶ Install the Authorino Operator (cluster admin required) -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 4. Setup Envoy +## ❸ Deploy the Talker API -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❹ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 5. Create the `AuthConfig` +## ❺ Create an `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced. + +The config uses API Key secrets to store base64-encoded `username:password` HTTP "Basic" authentication credentials. The config also specifies an Access Control List (ACL) by which only user `john` is authorized to consume the `/bye` endpoint of the API. + + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
```sh kubectl apply -f -< - Authorino features in this guide: + Authorino capabilities featured in this guide: - Inject serialized custom JSON objects as HTTP request headers. Values can be static or fetched from the [Authorization JSON](./../architecture.md#the-authorization-json). + Inject serialized custom JSON objects as HTTP request headers. Values can be static or fetched from the [Authorization JSON](../architecture.md#the-authorization-json). - Check out as well the user guide about [Authentication with API keys](./api-key-authentication.md). + 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). + For further details about Authorino features in general, check the [docs](../features.md).
## Requirements -- Kubernetes server +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -## 1. Install the Authorino Operator +
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❺.

+

At step ❺, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
+ +
-## 2. Deploy the Talker API +## ❶ Install the Authorino Operator (cluster admin required) -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 4. Setup Envoy +## ❸ Deploy the Talker API -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❹ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 5. Create the `AuthConfig` +## ❺ Create an `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced. The following defines a JSON object to be injected as an added HTTP header into the request, named after the response config `x-ext-auth-data`. The object includes 3 properties: 1. a static value `authorized: true`; 2. a dynamic value `request-time`, from Envoy-supplied contextual data present in the Authorization JSON; and 3. a greeting message `geeting-message` that interpolates a dynamic value read from an annotation of the Kubernetes `Secret` resource that represents the API key used to authenticate into a static string. + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
+ ```sh kubectl apply -f -< - Authorino features in this guide: + Authorino capabilities featured in this guide: - Authorino provides a built-in authorization module to check simple pattern-matching rules against the [Authorization JSON](./../architecture.md#the-authorization-json). This is an alternative to [OPA](./../features.md#open-policy-agent-opa-rego-policies-authorizationopa) when all you want is to check for some simple rules, without complex logics, such as match the value of a JWT claim. + Authorino provides a built-in authorization module to check simple pattern-matching rules against the [Authorization JSON](../architecture.md#the-authorization-json). This is an alternative to [OPA](../features.md#open-policy-agent-opa-rego-policies-authorizationopa) when all you want is to check for some simple rules, without complex logics, such as match the value of a JWT claim. - Check out as well the user guide about [OpenID Connect Discovery and authentication with JWTs](./oidc-jwt-authentication.md). + Check out as well the user guide about [OpenID Connect Discovery and authentication with JWTs](oidc-jwt-authentication.md). - For further details about Authorino features in general, check the [docs](./../features.md). + For further details about Authorino features in general, check the [docs](../features.md).
## Requirements -- Kubernetes server -- Auth server / Identity Provider (IdP) that implements OpenID Connect authentication and OpenID Connect Discovery (e.g. [Keycloak](https://www.keycloak.org)) +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) +- Identity Provider (IdP) that implements OpenID Connect authentication and OpenID Connect Discovery (e.g. [Keycloak](https://www.keycloak.org)) - [jq](https://stedolan.github.io/jq), to extract parts of JSON responses -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -Deploy a Keycloak server preloaded with all the realm settings required for this guide: +Deploy the identity provider and authentication server by executing the command below. For the examples in this guide, we are going to use a Keycloak server preloaded with all required realm settings. ```sh kubectl create namespace keycloak kubectl -n keycloak apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/keycloak/keycloak-deploy.yaml ``` -Forward local requests to the instance of Keycloak running in the cluster: - -```sh -kubectl -n keycloak port-forward deployment/keycloak 8080:8080 & -``` +
-## 1. Install the Authorino Operator +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❺.

+

At step ❺, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +
-## 2. Deploy the Talker API +## ❶ Install the Authorino Operator (cluster admin required) -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 4. Setup Envoy +## ❸ Deploy the Talker API -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❹ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 5. Create the `AuthConfig` +## ❺ Create an `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced. The `email-verified-only` authorization policy ensures that users consuming the API from a given network (IP range 192.168.1/24) must have their emails verified. @@ -103,6 +128,18 @@ The `email_verified` claim is a property of the identity added to the JWT by the The implementation relies on the [`X-Forwarded-For`](https://datatracker.ietf.org/doc/html/rfc7239) HTTP header to read the client's IP address. + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
+ ```sh kubectl apply -f -< - Authorino features in this guide: + Authorino capabilities featured in this guide: - For further details about Authorino features in general, check the [docs](./../features.md). + For further details about Authorino features in general, check the [docs](../features.md).
## Requirements -- Kubernetes server +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) - [Keycloak](https://www.keycloak.org) server - [jq](https://stedolan.github.io/jq), to extract parts of JSON responses -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -Deploy a Keycloak server preloaded with all the realm settings required for this guide: +Deploy the identity provider and authentication server by executing the command below. For the examples in this guide, we are going to use a Keycloak server preloaded with all required realm settings. ```sh kubectl create namespace keycloak kubectl -n keycloak apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/keycloak/keycloak-deploy.yaml ``` -Forward local requests to the instance of Keycloak running in the cluster: +Forward local requests to Keycloak running inside the cluster (if using Kind): ```sh -kubectl -n keycloak port-forward deployment/keycloak 8080:8080 & +kubectl -n keycloak port-forward deployment/keycloak 8080:8080 2>&1 >/dev/null & ``` -## 1. Install the Authorino Operator +
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❺.

+

At step ❺, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
+ +
-## 2. Deploy the Talker API +## ❶ Install the Authorino Operator (cluster admin required) -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 4. Setup Envoy +## ❸ Deploy the Talker API -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❹ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 5. Create the `AuthConfig` +## ❺ Create an `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced. In this example, Authorino will accept access tokens (JWTs) issued by the Keycloak server. These JWTs can be either normal Keycloak ID tokens or Requesting Party Tokens (RPT). @@ -105,6 +136,18 @@ In cases of asynchronous user-managed permission control, the first request to t Whenever an RPT with proper permissions is obtained by Authorino, the RPT is supplied back to the API consumer, so it can be used in subsequent requests thus skipping new negotiations of UMA tickets. + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
+ ```sh kubectl apply -f -<" http://talker-api-authorino.127.0.0.1.nip.io:8000/greetings/1 -i +curl -H "Authorization: Bearer " http://talker-api.127.0.0.1.nip.io:8000/greetings/1 -i # HTTP/1.1 200 OK ``` @@ -209,9 +252,9 @@ Otherwise, delete the resources created in each step: ```sh kubectl delete authconfig/talker-api-protection -kubectl delete authorino/authorino kubectl delete -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml kubectl delete -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +kubectl delete authorino/authorino kubectl delete namespace keycloak ``` diff --git a/docs/user-guides/kubernetes-subjectaccessreview.md b/docs/user-guides/kubernetes-subjectaccessreview.md index c74baa72..5439109b 100644 --- a/docs/user-guides/kubernetes-subjectaccessreview.md +++ b/docs/user-guides/kubernetes-subjectaccessreview.md @@ -4,49 +4,67 @@ Manage permissions in the Kubernetes RBAC and let Authorino to check them in req
- Authorino features in this guide: + Authorino capabilities featured in this guide: Authorino can delegate authorization decision to the Kubernetes authorization system, allowing permissions to be stored and managed using the Kubernetes Role-Based Access Control (RBAC) for example. The feature is based on the `SubjectAccessReview` API and can be used for `resourceAttributes` (parameters defined in the `AuthConfig`) or `nonResourceAttributes` (inferring HTTP path and verb from the original request). - Check out as well the user guide about [Authentication with Kubernetes tokens (TokenReview API)](./kubernetes-tokenreview.md). + Check out as well the user guide about [Authentication with Kubernetes tokens (TokenReview API)](kubernetes-tokenreview.md). - For further details about Authorino features in general, check the [docs](./../features.md). + For further details about Authorino features in general, check the [docs](../features.md).

## Requirements -- Kubernetes server -- Kubernetes user with permission to create `TokenRequest`s (to consume the API from outside the cluster) -- [yq](https://github.com/mikefarah/yq) (to parse your `~/.kube/config` file to extract user authentication data) +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) and to create `TokenRequest`s (to consume the protected service from outside the cluster) +- [jq](https://jqlang.github.io/jq/) -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -## 1. Install the Authorino Operator +
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❺.

+

At step ❺, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
+ +
-## 2. Deploy the Talker API +## ❶ Install the Authorino Operator (cluster admin required) -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. + +## ❸ Deploy the Talker API -## 4. Setup Envoy +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❹ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 5. Create the `AuthConfig` +## ❺ Create an `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced. The `AuthConfig` below sets all Kubernetes service accounts as trusted users of the API, and relies on the Kubernetes RBAC to enforce authorization using Kubernetes SubjectAccessReview API for non-resource endpoints: + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
+ ```sh kubectl apply -f -< @@ -310,9 +351,9 @@ kubectl delete clusterrolebinding/talker-api-speaker-rolebinding kubectl delete clusterrole/talker-api-greeter kubectl delete clusterrole/talker-api-speaker kubectl delete authconfig/talker-api-protection -kubectl delete authorino/authorino kubectl delete -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml kubectl delete -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +kubectl delete authorino/authorino ``` To uninstall the Authorino Operator and manifests (CRDs, RBAC, etc), run: diff --git a/docs/user-guides/kubernetes-tokenreview.md b/docs/user-guides/kubernetes-tokenreview.md index 8e69907c..718d80a1 100644 --- a/docs/user-guides/kubernetes-tokenreview.md +++ b/docs/user-guides/kubernetes-tokenreview.md @@ -4,9 +4,9 @@ Validate Kubernetes Service Account tokens to authenticate requests to your prot
- Authorino features in this guide: + Authorino capabilities featured in this guide: @@ -16,38 +16,56 @@ Validate Kubernetes Service Account tokens to authenticate requests to your prot The `audiences` claim of the token must include the requested host and port of the protected API (default), or all audiences specified in `spec.identity.kubernetes.audiences` of the `AuthConfig`. - For further details about Authorino features in general, check the [docs](./../features.md). + For further details about Authorino features in general, check the [docs](../features.md).

## Requirements -- Kubernetes server -- Kubernetes user with permission to create `TokenRequest`s (to consume the API from outside the cluster) -- [yq](https://github.com/mikefarah/yq) (to parse your `~/.kube/config` file to extract user authentication data) +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) and to create `TokenRequest`s (to consume the protected service from outside the cluster) +- [jq](https://jqlang.github.io/jq/) -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -## 1. Install the Authorino Operator +
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❺.

+

At step ❺, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
+ +
-## 2. Deploy the Talker API +## ❶ Install the Authorino Operator (cluster admin required) -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 4. Setup Envoy +## ❸ Deploy the Talker API -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❹ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 5. Create the `AuthConfig` +## ❺ Create an `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced: + + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
```sh kubectl apply -f -< - Authorino features in this guide: + Authorino capabilities featured in this guide: @@ -15,30 +15,55 @@ Verify client X.509 certificates against trusted root CAs stored in Kubernetes ` Trusted root Certificate Authorities (CA) are stored as Kubernetes `kubernetes.io/tls` Secrets labeled according to selectors specified in the AuthConfig, watched and cached by Authorino. - For further details about Authorino features in general, check the [docs](./../features.md). + For further details about Authorino features in general, check the [docs](../features.md).
## Requirements -- Kubernetes server +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -## 1. Install the Authorino Operator +
+ +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❻.

+

At step ❻, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
+ +
+ +## ❶ Install the Authorino Operator (cluster admin required) + +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -This step will also install [cert-manager](https://github.com/jetstack/cert-manager) in the cluster (required). +## ❷ Deploy Authorino -## 2. Deploy Authorino +The following commands will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS enabled[^3]. Create the TLS certificates for the Authorino service: @@ -46,7 +71,7 @@ Create the TLS certificates for the Authorino service: curl -sSL https://raw.githubusercontent.com/Kuadrant/authorino/main/deploy/certs.yaml | sed "s/\$(AUTHORINO_INSTANCE)/authorino/g;s/\$(NAMESPACE)/default/g" | kubectl apply -f - ``` -Deploy an Authorino service: +Request the Authorino instance: ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 3. Deploy the Talker API +## ❸ Deploy the Talker API -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml ``` -## 4. Create a CA +## ❹ Create a CA -Create a CA certificate to issue the client certificates that will be used to authenticate to consume the Talker API: +Create a CA (Certificate Authority) certificate to issue the client certificates that will be used to authenticate clients that send requests to the Talker API: ```sh openssl req -x509 -sha256 -days 365 -nodes -newkey rsa:2048 -subj "/CN=talker-api-ca" -keyout /tmp/ca.key -out /tmp/ca.crt ``` -Store the CA cert in a Kubernetes `Secret`, labeled to be discovered by Authorino: +Store the CA cert in a Kubernetes `Secret`, labeled to be discovered by Authorino and to be mounted in the file system of the Envoy container: ```sh kubectl create secret tls talker-api-ca --cert=/tmp/ca.crt --key=/tmp/ca.key kubectl label secret talker-api-ca authorino.kuadrant.io/managed-by=authorino app=talker-api ``` -## 5. Setup Envoy +## ❺ Setup Envoy + +The following command deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f -<&1 >/dev/null & ``` -## 6. Create the `AuthConfig` +## ❻ Create the `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced: + + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
```sh kubectl apply -f -< - Authorino features in this guide: + Authorino capabilities featured in this guide: @@ -15,66 +15,73 @@ Introspect OAuth 2.0 access tokens (e.g. opaque tokens) for online user data and _Important!_ Authorino does **not** implement [OAuth2 grants](https://datatracker.ietf.org/doc/html/rfc6749#section-4) nor [OIDC authentication flows](https://openid.net/specs/openid-connect-core-1_0.html#Authentication). As a common recommendation of good practice, obtaining and refreshing access tokens is for clients to negotiate directly with the auth servers and token issuers. Authorino will only validate those tokens using the parameters provided by the trusted issuer authorities. - Check out as well the user guides about [OpenID Connect Discovery and authentication with JWTs](./oidc-jwt-authentication.md) and [Simple pattern-matching authorization policies](./user-guides/json-pattern-matching-authorization.md). + Check out as well the user guides about [OpenID Connect Discovery and authentication with JWTs](oidc-jwt-authentication.md) and [Simple pattern-matching authorization policies](json-pattern-matching-authorization.md). - For further details about Authorino features in general, check the [docs](./../features.md). + For further details about Authorino features in general, check the [docs](../features.md).
## Requirements -- Kubernetes server +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) - OAuth 2.0 server that implements the token introspection endpoint ([RFC 7662](https://tools.ietf.org/html/rfc7662)) (e.g. [Keycloak](https://www.keycloak.org) or [a12n-server](https://github.com/curveball/a12n-server)) - [jq](https://stedolan.github.io/jq), to extract parts of JSON responses -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -Deploy a Keycloak server preloaded with all the realm settings required for this guide: +Deploy a Keycloak server preloaded with the realm settings required for this guide: ```sh kubectl create namespace keycloak kubectl -n keycloak apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/keycloak/keycloak-deploy.yaml ``` -Forward local requests to the instance of Keycloak running in the cluster: - -```sh -kubectl -n keycloak port-forward deployment/keycloak 8080:8080 & -``` - -Deploy an a12n-server server preloaded with all the realm settings required for this guide: +Deploy an a12n-server server preloaded with all settings required for this guide: ```sh kubectl create namespace a12n-server kubectl -n a12n-server apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/a12n-server/a12n-server-deploy.yaml ``` -Forward local requests to the instance of a12n-server running in the cluster: - -```sh -kubectl -n a12n-server port-forward deployment/a12n-server 8531:8531 & -``` +
-## 1. Install the Authorino Operator +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❺.

+

At step ❺, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +
-## 2. Deploy the Talker API +## ❶ Install the Authorino Operator (cluster admin required) -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 4. Setup Envoy +## ❸ Deploy the Talker API -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❹ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 5. Create the `AuthConfig` +## ❺ Create an `AuthConfig` -Create a couple required secret, used by Authorino to authenticate with Keycloak and a12n-server during the introspection request: +Create the required secrets that will be used by Authorino to authenticate with Keycloak and a12n-server during the introspection request: ```sh kubectl apply -f -< + + + + Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. + + + + ```sh kubectl apply -f -<&1 >/dev/null & +``` + Obtain an access token with the a12n-server server for service account `service-account-1`: ```sh @@ -243,7 +274,7 @@ echo $ACCESS_TOKEN As `service-account-1`, consumer the API with a valid access token: ```sh -curl -H "Authorization: Bearer $ACCESS_TOKEN" http://talker-api-authorino.127.0.0.1.nip.io:8000/hello +curl -H "Authorization: Bearer $ACCESS_TOKEN" http://talker-api.127.0.0.1.nip.io:8000/hello # HTTP/1.1 200 OK ``` @@ -254,7 +285,7 @@ curl -d "token=$ACCESS_TOKEN" -u service-account-1:FO6LgoMKA8TBDDHgSXZ5-iq1wKNwq ``` ```sh -curl -H "Authorization: Bearer $ACCESS_TOKEN" http://talker-api-authorino.127.0.0.1.nip.io:8000/hello -i +curl -H "Authorization: Bearer $ACCESS_TOKEN" http://talker-api.127.0.0.1.nip.io:8000/hello -i # HTTP/1.1 401 Unauthorized # www-authenticate: Bearer realm="keycloak" # www-authenticate: Bearer realm="a12n-server" @@ -264,7 +295,7 @@ curl -H "Authorization: Bearer $ACCESS_TOKEN" http://talker-api-authorino.127.0. ### Consume the API with a missing or invalid access token ```sh -curl -H "Authorization: Bearer invalid" http://talker-api-authorino.127.0.0.1.nip.io:8000/hello -i +curl -H "Authorization: Bearer invalid" http://talker-api.127.0.0.1.nip.io:8000/hello -i # HTTP/1.1 401 Unauthorized # www-authenticate: Bearer realm="keycloak" # www-authenticate: Bearer realm="a12n-server" @@ -285,9 +316,9 @@ Otherwise, delete the resources created in each step: kubectl delete authconfig/talker-api-protection kubectl delete secret/oauth2-token-introspection-credentials-keycloak kubectl delete secret/oauth2-token-introspection-credentials-a12n-server -kubectl delete authorino/authorino kubectl delete -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml kubectl delete -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +kubectl delete authorino/authorino kubectl delete namespace keycloak kubectl delete namespace a12n-server ``` diff --git a/docs/user-guides/observability.md b/docs/user-guides/observability.md index 77280d3f..c501cffe 100644 --- a/docs/user-guides/observability.md +++ b/docs/user-guides/observability.md @@ -1109,7 +1109,7 @@ Authorino outputs 3 levels of log messages: (from lowest to highest level) `info` logging is restricted to high-level information of the gRPC and HTTP authorization services, limiting messages to incoming request and respective outgoing response logs, with reduced details about the corresponding objects (request payload and authorization result), and without any further detailed logs of the steps in between, except for errors. -Only `debug` logging will include processing details of each [Auth Pipeline](./../architecture.md#the-auth-pipeline-aka-enforcing-protection-in-request-time), such as intermediary requests to validate identities with external auth servers, requests to external sources of auth metadata or authorization policies. +Only `debug` logging will include processing details of each [Auth Pipeline](../architecture.md#the-auth-pipeline-aka-enforcing-protection-in-request-time), such as intermediary requests to validate identities with external auth servers, requests to external sources of auth metadata or authorization policies. 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`. @@ -1271,7 +1271,7 @@ The examples below are all with `--log-level=debug` and `--log-mode=production`. {"level":"debug","ts":1669221208.7535596,"logger":"authorino.controller.secret.apikey","msg":"api key added","reconciler group":"","reconciler kind":"Secret","name":"api-key-1","namespace":"default"} {"level":"info","ts":1669221208.7536132,"logger":"authorino.controller-runtime.manager.controller.secret","msg":"resource reconciled","secret":"default/api-key-1"} {"level":"info","ts":1669221208.753772,"logger":"authorino.controller-runtime.manager.controller.authconfig.statusupdater","msg":"resource status updated","authconfig":"default/talker-api-protection"} - {"level":"debug","ts":1669221208.753835,"logger":"authorino.controller-runtime.manager.controller.authconfig.statusupdater","msg":"resource status changed","authconfig":"default/talker-api-protection","authconfig/status":{"conditions":[{"type":"Available","status":"True","lastTransitionTime":"2022-11-23T16:33:28Z","reason":"HostsLinked"},{"type":"Ready","status":"True","lastTransitionTime":"2022-11-23T16:33:28Z","reason":"Reconciled"}],"summary":{"ready":true,"hostsReady":["talker-api-authorino.127.0.0.1.nip.io"],"numHostsReady":"1/1","numIdentitySources":1,"numMetadataSources":0,"numAuthorizationPolicies":0,"numResponseItems":0,"festivalWristbandEnabled":false}}} + {"level":"debug","ts":1669221208.753835,"logger":"authorino.controller-runtime.manager.controller.authconfig.statusupdater","msg":"resource status changed","authconfig":"default/talker-api-protection","authconfig/status":{"conditions":[{"type":"Available","status":"True","lastTransitionTime":"2022-11-23T16:33:28Z","reason":"HostsLinked"},{"type":"Ready","status":"True","lastTransitionTime":"2022-11-23T16:33:28Z","reason":"Reconciled"}],"summary":{"ready":true,"hostsReady":["talker-api.127.0.0.1.nip.io"],"numHostsReady":"1/1","numIdentitySources":1,"numMetadataSources":0,"numAuthorizationPolicies":0,"numResponseItems":0,"festivalWristbandEnabled":false}}} {"level":"info","ts":1669221208.7571108,"logger":"authorino.controller-runtime.manager.controller.authconfig","msg":"resource reconciled","authconfig":"default/talker-api-protection"} {"level":"info","ts":1669221208.7573664,"logger":"authorino.controller-runtime.manager.controller.authconfig.statusupdater","msg":"resource status updated","authconfig":"default/talker-api-protection"} {"level":"debug","ts":1669221208.757429,"logger":"authorino.controller-runtime.manager.controller.authconfig.statusupdater","msg":"resource status did not change","authconfig":"default/talker-api-protection"} diff --git a/docs/user-guides/oidc-jwt-authentication.md b/docs/user-guides/oidc-jwt-authentication.md index d973c42f..18b64f33 100644 --- a/docs/user-guides/oidc-jwt-authentication.md +++ b/docs/user-guides/oidc-jwt-authentication.md @@ -4,9 +4,9 @@ Validate JSON Web Tokens (JWT) issued and signed by an OpenID Connect server; le
- Authorino features in this guide: + Authorino capabilities featured in this guide: @@ -14,51 +14,64 @@ Validate JSON Web Tokens (JWT) issued and signed by an OpenID Connect server; le _Important!_ Authorino does **not** implement [OAuth2 grants](https://datatracker.ietf.org/doc/html/rfc6749#section-4) nor [OIDC authentication flows](https://openid.net/specs/openid-connect-core-1_0.html#Authentication). As a common recommendation of good practice, obtaining and refreshing access tokens is for clients to negotiate directly with the auth servers and token issuers. Authorino will only validate those tokens using the parameters provided by the trusted issuer authorities. - For further details about Authorino features in general, check the [docs](./../features.md). + For further details about Authorino features in general, check the [docs](../features.md).

## Requirements -- Kubernetes server -- Auth server / Identity Provider (IdP) that implements OpenID Connect authentication and OpenID Connect Discovery (e.g. [Keycloak](https://www.keycloak.org)) +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) +- Identity Provider (IdP) that implements OpenID Connect authentication and OpenID Connect Discovery (e.g. [Keycloak](https://www.keycloak.org)) - [jq](https://stedolan.github.io/jq), to extract parts of JSON responses -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -Deploy a Keycloak server preloaded with all the realm settings required for this guide: +Deploy the identity provider and authentication server by executing the command below. For the examples in this guide, we are going to use a Keycloak server preloaded with all required realm settings. ```sh kubectl create namespace keycloak kubectl -n keycloak apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/keycloak/keycloak-deploy.yaml ``` -Forward local requests to the instance of Keycloak running in the cluster: - -```sh -kubectl -n keycloak port-forward deployment/keycloak 8080:8080 & -``` +
-## 1. Install the Authorino Operator +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❺.

+

At step ❺, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +
-## 2. Deploy the Talker API +## ❶ Install the Authorino Operator (cluster admin required) -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 4. Setup Envoy +## ❸ Deploy the Talker API -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❹ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 5. Create the `AuthConfig` +## ❺ Create an `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced: + + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
```sh kubectl apply -f -< - Authorino features in this guide: + Authorino capabilities featured in this guide: - Check out as well the user guides about [OpenID Connect Discovery and authentication with JWTs](./oidc-jwt-authentication.md) and [Simple pattern-matching authorization policies](./json-pattern-matching-authorization.md). + Check out as well the user guides about [OpenID Connect Discovery and authentication with JWTs](oidc-jwt-authentication.md) and [Simple pattern-matching authorization policies](json-pattern-matching-authorization.md). - For further details about Authorino features in general, check the [docs](./../features.md). + For further details about Authorino features in general, check the [docs](../features.md).
## Requirements -- Kubernetes server -- Auth server / Identity Provider (IdP) that implements OpenID Connect authentication and OpenID Connect Discovery (e.g. [Keycloak](https://www.keycloak.org)) +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) +- Identity Provider (IdP) that implements OpenID Connect authentication and OpenID Connect Discovery (e.g. [Keycloak](https://www.keycloak.org)) - [jq](https://stedolan.github.io/jq), to extract parts of JSON responses -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -Deploy a Keycloak server preloaded with all the realm settings required for this guide: +Deploy the identity provider and authentication server by executing the command below. For the examples in this guide, we are going to use a Keycloak server preloaded with all required realm settings. ```sh kubectl create namespace keycloak kubectl -n keycloak apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/keycloak/keycloak-deploy.yaml ``` -Forward local requests to the instance of Keycloak running in the cluster: - -```sh -kubectl -n keycloak port-forward deployment/keycloak 8080:8080 & -``` +
-## 1. Install the Authorino Operator +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❺.

+

At step ❺, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +
-## 2. Deploy the Talker API +## ❶ Install the Authorino Operator (cluster admin required) -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 4. Setup Envoy +## ❸ Deploy the Talker API -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❹ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 5. Create the `AuthConfig` +## ❺ Create an `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced. In this example, the Keycloak realm defines a few users and 2 realm roles: 'member' and 'admin'. When users authenticate to the Keycloak server by any of the supported OAuth2/OIDC flows, Keycloak adds to the access token JWT a claim `"realm_access": { "roles": array }` that holds the list of roles assigned to the user. Authorino will verify the JWT on requests to the API and read from that claim to enforce the following RBAC rules: @@ -105,6 +130,18 @@ In this example, the Keycloak realm defines a few users and 2 realm roles: 'memb | /resources/{id} | DELETE | admin | | /admin[/*] | * | admin | + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
+ Apply the AuthConfig: ```sh @@ -115,7 +152,7 @@ metadata: name: talker-api-protection spec: hosts: - - talker-api-authorino.127.0.0.1.nip.io + - talker-api.127.0.0.1.nip.io authentication: "keycloak-kuadrant-realm": @@ -168,7 +205,7 @@ spec: EOF ``` -## 6. Obtain an access token and consume the API +## ❻ Obtain an access token and consume the API ### Obtain an access token and consume the API as John (member) @@ -182,26 +219,26 @@ Obtain an access token from within the cluster for the user John, who is assigne ACCESS_TOKEN=$(kubectl run token --attach --rm --restart=Never -q --image=curlimages/curl -- http://keycloak.keycloak.svc.cluster.local:8080/auth/realms/kuadrant/protocol/openid-connect/token -s -d 'grant_type=password' -d 'client_id=demo' -d 'username=john' -d 'password=p' | jq -r .access_token) ``` -If otherwise your Keycloak server is reachable from outside the cluster, feel free to obtain the token directly. Make sure the host name set in the OIDC issuer endpoint in the `AuthConfig` matches the one used to obtain the token and is as well reachable from within the cluster. +If your Keycloak server is reachable from outside the cluster, feel free to obtain the token directly. Make sure the host name set in the OIDC issuer endpoint in the `AuthConfig` matches the one used to obtain the token and is as well reachable from within the cluster. As John, send a `GET` request to **/resources**: ```sh -curl -H "Authorization: Bearer $ACCESS_TOKEN" http://talker-api-authorino.127.0.0.1.nip.io:8000/resources -i +curl -H "Authorization: Bearer $ACCESS_TOKEN" http://talker-api.127.0.0.1.nip.io:8000/resources -i # HTTP/1.1 200 OK ``` As John, send a `DELETE` request to **/resources/123**: ```sh -curl -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE http://talker-api-authorino.127.0.0.1.nip.io:8000/resources/123 -i +curl -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE http://talker-api.127.0.0.1.nip.io:8000/resources/123 -i # HTTP/1.1 403 Forbidden ``` As John, send a `GET` request to **/admin/settings**: ```sh -curl -H "Authorization: Bearer $ACCESS_TOKEN" http://talker-api-authorino.127.0.0.1.nip.io:8000/admin/settings -i +curl -H "Authorization: Bearer $ACCESS_TOKEN" http://talker-api.127.0.0.1.nip.io:8000/admin/settings -i # HTTP/1.1 403 Forbidden ``` @@ -216,21 +253,21 @@ ACCESS_TOKEN=$(kubectl run token --attach --rm --restart=Never -q --image=curlim As Jane, send a `GET` request to **/resources**: ```sh -curl -H "Authorization: Bearer $ACCESS_TOKEN" http://talker-api-authorino.127.0.0.1.nip.io:8000/resources -i +curl -H "Authorization: Bearer $ACCESS_TOKEN" http://talker-api.127.0.0.1.nip.io:8000/resources -i # HTTP/1.1 200 OK ``` As Jane, send a `DELETE` request to **/resources/123**: ```sh -curl -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE http://talker-api-authorino.127.0.0.1.nip.io:8000/resources/123 -i +curl -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE http://talker-api.127.0.0.1.nip.io:8000/resources/123 -i # HTTP/1.1 200 OK ``` As Jane, send a `GET` request to **/admin/settings**: ```sh -curl -H "Authorization: Bearer $ACCESS_TOKEN" http://talker-api-authorino.127.0.0.1.nip.io:8000/admin/settings -i +curl -H "Authorization: Bearer $ACCESS_TOKEN" http://talker-api.127.0.0.1.nip.io:8000/admin/settings -i # HTTP/1.1 200 OK ``` @@ -246,9 +283,9 @@ Otherwise, delete the resources created in each step: ```sh kubectl delete authconfig/talker-api-protection -kubectl delete authorino/authorino kubectl delete -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml kubectl delete -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +kubectl delete authorino/authorino kubectl delete namespace keycloak ``` diff --git a/docs/user-guides/oidc-user-info.md b/docs/user-guides/oidc-user-info.md index e2527cee..33551ae1 100644 --- a/docs/user-guides/oidc-user-info.md +++ b/docs/user-guides/oidc-user-info.md @@ -4,63 +4,76 @@ Fetch user info for OpenID Connect ID tokens in request-time for extra metadata
- Authorino features in this guide: + Authorino capabilities featured in this guide: Apart from possibly complementing information of the JWT, fetching OpenID Connect UserInfo in request-time can be particularly useful for remote checking the state of the session, as opposed to only verifying the JWT/JWS offline. Implementation requires an OpenID Connect issuer ([`spec.identity.oidc`](#openid-connect-oidc-jwtjose-verification-and-validation-identityoidc)) configured in the same `AuthConfig`. - Check out as well the user guide about [OpenID Connect Discovery and authentication with JWTs](./oidc-jwt-authentication.md). + Check out as well the user guide about [OpenID Connect Discovery and authentication with JWTs](oidc-jwt-authentication.md). - For further details about Authorino features in general, check the [docs](./../features.md). + For further details about Authorino features in general, check the [docs](../features.md).

## Requirements -- Kubernetes server -- Auth server / Identity Provider (IdP) that implements OpenID Connect authentication and OpenID Connect Discovery (e.g. [Keycloak](https://www.keycloak.org)) +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) +- Identity Provider (IdP) that implements OpenID Connect authentication and OpenID Connect Discovery (e.g. [Keycloak](https://www.keycloak.org)) - [jq](https://stedolan.github.io/jq), to extract parts of JSON responses -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -Deploy a Keycloak server preloaded with all the realm settings required for this guide: +Deploy the identity provider and authentication server by executing the command below. For the examples in this guide, we are going to use a Keycloak server preloaded with all required realm settings. ```sh kubectl create namespace keycloak kubectl -n keycloak apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/keycloak/keycloak-deploy.yaml ``` -Forward local requests to the instance of Keycloak running in the cluster: - -```sh -kubectl -n keycloak port-forward deployment/keycloak 8080:8080 & -``` +
-## 1. Install the Authorino Operator +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❺.

+

At step ❺, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +
-## 2. Deploy the Talker API +## ❶ Install the Authorino Operator (cluster admin required) -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 4. Setup Envoy +## ❸ Deploy the Talker API -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❹ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 5. Create the `AuthConfig` +## ❺ Create an `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced: + + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
```sh kubectl apply -f -< - Authorino features in this guide: + Authorino capabilities featured in this guide: @@ -15,38 +15,57 @@ Leverage the power of Open Policy Agent (OPA) policies, evaluated against Author Authorino's built-in OPA module precompiles the policies in reconciliation-time and cache them for fast evaluation in request-time, where they receive the Authorization JSON as input. - Check out as well the user guide about [Authentication with API keys](./api-key-authentication.md). + 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). + For further details about Authorino features in general, check the [docs](../features.md).
## Requirements -- Kubernetes server +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -## 1. Install the Authorino Operator +
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❺.

+

At step ❺, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
+ +
-## 2. Deploy the Talker API +## ❶ Install the Authorino Operator (cluster admin required) -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 4. Setup Envoy +## ❸ Deploy the Talker API -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❹ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 5. Create the `AuthConfig` +## ❺ Create an `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced. In this example, we will use OPA to implement a read-only policy for requests coming from outside a trusted network (IP range 192.168.1/24). -The implementation relies on the [`X-Forwarded-For`](https://datatracker.ietf.org/doc/html/rfc7239) HTTP header to read the client's IP address. +The implementation relies on the [`X-Forwarded-For`](https://datatracker.ietf.org/doc/html/rfc7239) HTTP header to read the client's IP address.[^5] + +[^5]: You can also set [`use_remote_address: true`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-use-remote-address) in the Envoy route configuration, so the proxy will append its IP address instead of run in transparent mode. This setting will also ensure real remote address of the client connection passed in the [`x-envoy-external-address`](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#config-http-conn-man-headers-x-envoy-external-address) HTTP header, which can be used to simplify the read-only policy in remote environment. -_Optional._ Set [`use_remote_address: true`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-use-remote-address) in the Envoy route configuration, so the proxy will append its IP address instead of run in transparent mode. This setting will also ensure real remote address of the client connection passed in the [`x-envoy-external-address`](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#config-http-conn-man-headers-x-envoy-external-address) HTTP header, which can be used to simplify the read-only policy in remote environment. + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
```sh kubectl apply -f -< - Authorino features in this guide: + Authorino capabilities featured in this guide:
    -
  • Identity verification & authentication → Auth credentials
    • -
  • Identity verification & authentication → API key
    • +
  • Identity verification & authentication → Auth credentials
    • +
  • Identity verification & authentication → API key
 Authentication tokens can be supplied in the `Authorization` header, in a custom header, cookie or query string parameter. - Check out as well the user guide about [Authentication with API keys](./api-key-authentication.md). + 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). + For further details about Authorino features in general, check the [docs](../features.md).
## Requirements -- Kubernetes server +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -## 1. Install the Authorino Operator +
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❺.

+

At step ❺, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
+ +
-## 2. Deploy the Talker API +## ❶ Install the Authorino Operator (cluster admin required) -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 4. Setup Envoy +## ❸ Deploy the Talker API -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❹ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 5. Create the `AuthConfig` +## ❺ Create an `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced. In this example, `member` users can authenticate supplying the API key in any of 4 different ways: - HTTP header `Authorization: APIKEY ` @@ -90,6 +121,18 @@ In this example, `member` users can authenticate supplying the API key in any of `admin` API keys are only accepted in the (default) HTTP header `Authorization: Bearer `. + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
+ ```sh kubectl apply -f -< - Authorino features in this guide: + Authorino capabilities featured in this guide: - Check out as well the user guides about [OpenID Connect Discovery and authentication with JWTs](./oidc-jwt-authentication.md) and [Open Policy Agent (OPA) Rego policies](./opa-authorization.md). + Check out as well the user guides about [OpenID Connect Discovery and authentication with JWTs](oidc-jwt-authentication.md) and [Open Policy Agent (OPA) Rego policies](opa-authorization.md). - For further details about Authorino features in general, check the [docs](./../features.md). + For further details about Authorino features in general, check the [docs](../features.md).
## Requirements -- Kubernetes server -- Auth server / Identity Provider (IdP) that implements OpenID Connect authentication and OpenID Connect Discovery (e.g. [Keycloak](https://www.keycloak.org)) +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) +- Identity Provider (IdP) that implements OpenID Connect authentication and OpenID Connect Discovery (e.g. [Keycloak](https://www.keycloak.org)) - [jq](https://stedolan.github.io/jq), to extract parts of JSON responses -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -Deploy a Keycloak server preloaded with all the realm settings required for this guide: +Deploy the identity provider and authentication server by executing the command below. For the examples in this guide, we are going to use a Keycloak server preloaded with all required realm settings. ```sh kubectl create namespace keycloak kubectl -n keycloak apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/keycloak/keycloak-deploy.yaml ``` -Forward local requests to the instance of Keycloak running in the cluster: - -```sh -kubectl -n keycloak port-forward deployment/keycloak 8080:8080 & -``` +
-## 1. Install the Authorino Operator +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❺.

+

At step ❺, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +
-## 2. Deploy the Talker API +## ❶ Install the Authorino Operator (cluster admin required) -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 4. Setup Envoy +## ❸ Deploy the Talker API -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❹ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 5. Create the `AuthConfig` +## ❺ Create an `AuthConfig` -This user guide's implementation for resource-level authorization leverages part of Keycloak's User-Managed Access (UMA) support. Authorino will fetch resource attributes stored in a Keycloak resource server client. +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced: + +This example of resource-level authorization leverages part of Keycloak's User-Managed Access (UMA) support. Authorino will fetch resource attributes stored in a Keycloak resource server client. The Keycloak server also provides the identities. The `sub` claim of the Keycloak-issued ID tokens must match the owner of the requested resource, identified by the URI of the request. -Create a required secret, used by Authorino to start the authentication with the UMA registry. + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
+ +Create a required secret that will be used by Authorino to initiate the authentication with the UMA registry. ```sh kubectl apply -f -< + + + + ⚠️ Important: + This feature may not be available to users of Authorino via Kuadrant. + + + + +
- Authorino features in this guide: + Authorino capabilities featured in this guide: - Check out as well the user guide about [Authentication with API keys](./api-key-authentication.md). + 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). + For further details about Authorino features in general, check the [docs](../features.md).

## Requirements -- Kubernetes server +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -## 1. Install the Authorino Operator +
+ +## ❶ Install the Authorino Operator (cluster admin required) + +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 2. Deploy a couple instances of Authorino +## ❷ Deploy instances of Authorino Deploy an instance of Authorino dedicated to `AuthConfig`s and API key `Secrets` labeled with `authorino/environment=staging`: @@ -82,15 +97,18 @@ spec: EOF ``` -The commands above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in `cluster-wide` reconciliation mode, and with TLS termination disabled. For other variants and deployment options, check out the [Getting Started](./../getting-started.md#step-request-an-authorino-instance) section of the docs, the [Architecture](./../architecture.md#topologies) page, and the spec for the [`Authorino`](https://github.com/Kuadrant/authorino-operator/blob/main/config/crd/bases/operator.authorino.kuadrant.io_authorinos.yaml) CRD in the Authorino Operator repo. +The commands above will both request instances of Authorino that watch for `AuthConfig` resources cluster-wide[^1], with TLS disabled[^2]. + +[^1]: `cluster-wide` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^2]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 3. Create a namespace for user resources +## ❸ Create a namespace for user resources ```sh kubectl create namespace myapp ``` -## 4. Create `AuthConfig`s and API key `Secret`s for both instances +## ❹ Create `AuthConfig`s and API key `Secret`s for both instances ### Create resources for `authorino-staging` @@ -194,7 +212,7 @@ kubectl logs $(kubectl get pods -l authorino-resource=authorino-production -o na # {"level":"info","ts":1638383460.3515081,"logger":"authorino.controller-runtime.manager.controller.secret","msg":"resource reconciled","secret":"myapp/api-key-2"} ``` -## 9. Remove a resource from scope +## ❺ Remove a resource from scope ```sh kubectl -n myapp label authconfig/auth-config-2 disabled=true diff --git a/docs/user-guides/token-normalization.md b/docs/user-guides/token-normalization.md index 8d3fbe0b..e2593f97 100644 --- a/docs/user-guides/token-normalization.md +++ b/docs/user-guides/token-normalization.md @@ -4,62 +4,81 @@ Broadly, the term token normalization in authentication systems usually implies The most typical use-case for token normalization involves accepting tokens issued by multiple trusted sources and of often varied authentication protocols, while ensuring that the eventual different data structures adopted by each of those sources are normalized, thus allowing to simplify policies and authorization checks that depend on those values. In general, however, any modification to the identity claims can be for the purpose of normalization. -This user guide focuses on the aspect of mutation of the identity claims resolved from an authentication token, to a certain data format and/or by extending them, so that required attributes can thereafter be trusted to be present among the claims, in a desired form. For such, Authorino allows to extend resolved identity objects with custom attributes (custom claims) of either static values or with values fetched from the [Authorization JSON](./../architecture.md#the-authorization-json). +This user guide focuses on the aspect of mutation of the identity claims resolved from an authentication token, to a certain data format and/or by extending them, so that required attributes can thereafter be trusted to be present among the claims, in a desired form. For such, Authorino allows to extend resolved identity objects with custom attributes (custom claims) of either static values or with values fetched from the [Authorization JSON](../architecture.md#the-authorization-json). -For not only normalizing the identity claims for purpose of writing simpler authorization checks and policies, but also getting Authorino to issue a new token in a normalized format, check the [Festival Wristband tokens](./../features.md#festival-wristband-tokens-responsesuccessheadersdynamicmetadatawristband) feature. +For not only normalizing the identity claims for purpose of writing simpler authorization checks and policies, but also getting Authorino to issue a new token in a normalized format, check the [Festival Wristband tokens](../features.md#festival-wristband-tokens-responsesuccessheadersdynamicmetadatawristband) feature.
- Authorino features in this guide: + Authorino capabilities featured in this guide: - Check out as well the user guides about [Authentication with API keys](./api-key-authentication.md), [OpenID Connect Discovery and authentication with JWTs](./oidc-jwt-authentication.md) and [Simple pattern-matching authorization policies](./user-guides/json-pattern-matching-authorization.md). + Check out as well the user guides about [Authentication with API keys](api-key-authentication.md), [OpenID Connect Discovery and authentication with JWTs](oidc-jwt-authentication.md) and [Simple pattern-matching authorization policies](json-pattern-matching-authorization.md). - For further details about Authorino features in general, check the [docs](./../features.md). + For further details about Authorino features in general, check the [docs](../features.md).

## Requirements -- Kubernetes server -- Auth server / Identity Provider (IdP) that implements OpenID Connect authentication and OpenID Connect Discovery (e.g. [Keycloak](https://www.keycloak.org)) +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) +- Identity Provider (IdP) that implements OpenID Connect authentication and OpenID Connect Discovery (e.g. [Keycloak](https://www.keycloak.org)) - [jq](https://stedolan.github.io/jq), to extract parts of JSON responses -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -Deploy a Keycloak server preloaded with all the realm settings required for this guide: +Deploy the identity provider and authentication server by executing the command below. For the examples in this guide, we are going to use a Keycloak server preloaded with all required realm settings. ```sh kubectl create namespace keycloak kubectl -n keycloak apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/keycloak/keycloak-deploy.yaml ``` -## 1. Install the Authorino Operator +
-```sh -curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s -``` +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant and already have your workload cluster configured and sample service application deployed, as well as your Gateway API network resources applied to route traffic to your service, skip straight to step ❺.

+

At step ❺, instead of creating an AuthConfig custom resource, create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
+ +
-## 2. Deploy the Talker API +## ❶ Install the Authorino Operator (cluster admin required) -The **Talker API** is just an echo API, included in the Authorino examples. We will use it in this guide as the service to be protected with Authorino. +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh -kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -## 3. Deploy Authorino +## ❷ Deploy Authorino + +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources in the `default` namespace[^2], with TLS disabled[^3]. ```sh kubectl apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `namespaced` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 4. Setup Envoy +## ❸ Deploy the Talker API -The following bundle from the Authorino examples (manifest referred in the command below) is to apply Envoy configuration and deploy Envoy proxy, that wire up the Talker API behind the reverse-proxy and external authorization with the Authorino instance. +The **Talker API** is a simple HTTP service that echoes back in the response whatever it gets in the request. We will use it in this guide as the sample service to be protected by Authorino. -For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](./../getting-started.md#step-setup-envoy) page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out [Kuadrant](https://github.com/kuadrant). +```sh +kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml +``` + +## ❹ Setup Envoy + +The following bundle from the Authorino examples deploys the [Envoy](https://envoyproxy.io/) proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.[^4] + +[^4]: For details and instructions to setup Envoy manually, see _Protect a service > Setup Envoy_ in the [Getting Started](../getting-started.md#step-setup-envoy) page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out [Kuadrant](https://kuadrant.io). ```sh kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/envoy/envoy-notls-deploy.yaml ``` -The bundle also creates an `Ingress` with host name `talker-api-authorino.127.0.0.1.nip.io`, but if you are using a local Kubernetes cluster created with Kind, you need to forward requests on port 8000 to inside the cluster in order to actually reach the Envoy service: +The command above creates an `Ingress` with host name `talker-api.127.0.0.1.nip.io`. If you are using a local Kubernetes cluster created with Kind, forward requests from your local port 8000 to the Envoy service running inside the cluster: ```sh -kubectl port-forward deployment/envoy 8000:8000 & +kubectl port-forward deployment/envoy 8000:8000 2>&1 >/dev/null & ``` -## 5. Create the `AuthConfig` +## ❺ Create an `AuthConfig` + +Create an Authorino `AuthConfig` custom resource declaring the auth rules to be enforced. This example implements a policy that only users bound to the `admin` role can send `DELETE` requests. @@ -103,6 +134,18 @@ The config trusts access tokens issued by a Keycloak realm as well as API keys l Without normalizing identity claims from these two different sources, the policy would have to handle the differences of data formats with additional ifs-and-elses. Instead, the config here uses the `identity.extendedProperties` option to ensure a custom `roles` (Array) claim is always present in the identity object. In the case of Keycloak ID tokens, the value is extracted from the `realm_access.roles` claim; for API key-resolved objects, the custom claim is set to the static value `["admin"]`. + + + + + + +
+ Kuadrant users – + Remember to create an AuthPolicy instead of an AuthConfig. + For more, see Kuadrant auth. +
+ ```sh kubectl apply -f -< - Authorino features in this guide: + Authorino capabilities featured in this guide: - For further details about Authorino features in general, check the [docs](./../features.md). + For further details about Authorino features in general, check the [docs](../features.md).
## Requirements -- Kubernetes server -- Auth server / Identity Provider (IdP) that implements OpenID Connect authentication and OpenID Connect Discovery (e.g. [Keycloak](https://www.keycloak.org)) +- Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC) +- Identity Provider (IdP) that implements OpenID Connect authentication and OpenID Connect Discovery (e.g. [Keycloak](https://www.keycloak.org)) -Create a containerized Kubernetes server locally using [Kind](https://kind.sigs.k8s.io): +If you do not own a Kubernetes server already and just want to try out the steps in this guide, you can create a local containerized cluster by executing the command below. In this case, the main requirement is having [Kind](https://kind.sigs.k8s.io) installed, with either [Docker](https://www.docker.com/) or [Podman](https://podman.io/). ```sh kind create cluster --name authorino-tutorial ``` -Deploy a Keycloak server preloaded with all the realm settings required for this guide: +Deploy the identity provider and authentication server. For the examples in this guide, we are going to use a Keycloak server preloaded with all required realm settings. + +The Keycloak server is only needed for trying out validating AuthConfig resources that use the authentication server. ```sh kubectl create namespace keycloak kubectl -n keycloak apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/keycloak/keycloak-deploy.yaml ``` -## 1. Install the Authorino Operator +
+ +The next steps walk you through installing Authorino, deploying and configuring a sample service called **Talker API** to be protected by the authorization service. + + + + + + + + + + + + +
Using Kuadrant
+

If you are a user of Kuadrant you may already have Authorino installed and running. In this case, skip straight to step ❸.

+

At step ❺, alternatively to creating an AuthConfig custom resource, you may create a Kuadrant AuthPolicy one. The schema of the AuthConfig's spec matches the one of the AuthPolicy's, except spec.host, which is not available in the Kuadrant AuthPolicy. Host names in a Kuadrant AuthPolicy are inferred automatically from the Kubernetes network object referred in spec.targetRef and route selectors declared in the policy.

+

For more about using Kuadrant to enforce authorization, check out Kuadrant auth.

+
+ +
+ +## ❶ Install the Authorino Operator (cluster admin required) + +The following command will install the [Authorino Operator](http://github.com/kuadrant/authorino-operator) in the Kubernetes cluster. The operator manages instances of the Authorino authorization service. ```sh curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s ``` -This step will also install [cert-manager](https://github.com/jetstack/cert-manager) in the cluster (required). - -## 2. Deploy Authorino +## ❷ Deploy Authorino Create the namespace: @@ -82,6 +94,8 @@ curl -sSL https://raw.githubusercontent.com/Kuadrant/authorino/main/deploy/certs Create the Authorino instance: +The following command will request an instance of Authorino as a separate service[^1] that watches for `AuthConfig` resources cluster-wide[^2], with TLS enabled[^3]. + ```sh kubectl -n authorino apply -f -< [Topologies](../architecture.md#topologies)__ for all options. +[^2]: `cluster-wide` reconciliation mode. See [Cluster-wide vs. Namespaced instances](../architecture.md#cluster-wide-vs-namespaced-instances). +[^3]: For other variants and deployment options, check out [Getting Started](../getting-started.md#step-request-an-authorino-instance), as well as the [`Authorino`](https://github.com/kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) CRD specification. -## 3. Create the `AuthConfig` and related `ClusterRole` +For convenience, the same instance of Authorino pointed as the validating webhook will also be targeted for the sample AuthConfigs created to test the validation. For using different instances of Authorino for the validating webhook and for protecting applications behind a proxy, check out the section about [sharding](../architecture.md#sharding) in the docs. There is also a [user guide](sharding.md) on the topic, with concrete examples. -Create the `AuthConfig`: +## ❸ Create the `AuthConfig` and related `ClusterRole` + +Create the `AuthConfig` with the auth rules to validate other AuthConfig resources applied to the cluster. + +The AuthConfig to validate other AuthConfigs will enforce the following rules: +- Authorino features that cannot be used by any application in their security schemes: + - Anonymous Access + - Plain identity object extracted from context + - Kubernetes authentication (TokenReview) + - Kubernetes authorization (SubjectAccessReview) + - Festival Wristband tokens +- Authorino features that require a RoleBinding to a specific ClusterRole in the 'authorino' namespace, to be used in a AuthConfig: + - Authorino API key authentication +- All metadata pulled from external sources must be cached for precisely 5 minutes (300 seconds) ```sh kubectl -n authorino apply -f -< + + + + Kuadrant users – + For this and other example AuthConfigs below, if you create a Kuadrant AuthPolicy instead, the output of the commands shall differ. The requested AuthPolicy may be initially accepted, but its state will turn ready or not ready depending on whether the corresponding AuthConfig requested by Kuadrant is accepted or rejected, according to the validating webhook rules. Check the state of the resources to confirm. + For more, see Kuadrant auth. + + + + + ```sh kubectl -n myapp apply -f -<