Skip to content

User guide: Hello World

Requirements

  • Kubernetes server with permissions to install cluster-scoped resources (operator, CRDs and RBAC)

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 installed, with either Docker or Podman.

kind create cluster --name authorino-tutorial

The next steps walk you through installing Authorino, deploying and configuring a sample service called Talker API to be protected by the authorization service.

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

kubectl create namespace hello-world
# namespace/hello-world created

❷ Deploy the Talker API

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.

kubectl -n hello-world apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml
# deployment.apps/talker-api created
# service/talker-api created

❸ Setup Envoy

The following bundle from the Authorino examples deploys the Envoy proxy and configuration to wire up the Talker API behind the reverse-proxy, with external authorization enabled with the Authorino instance.1

kubectl -n hello-world apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/hello-world/envoy-deploy.yaml
# configmap/envoy created
# deployment.apps/envoy created
# service/envoy created

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:

kubectl -n hello-world port-forward deployment/envoy 8000:8000 2>&1 >/dev/null &

❹ Consume the API (unprotected)

curl http://talker-api.127.0.0.1.nip.io:8000/hello -i
# HTTP/1.1 200 OK

❺ Protect the API

Install the Authorino Operator

curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -s

Deploy Authorino

The following command will request an instance of Authorino as a separate service2 that watches for AuthConfig resources in the hello-world namespace3, with TLS disabled4.

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

❻ Consume the API behind Envoy and Authorino

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.127.0.0.1.nip.io host, hence the 404 Not Found. Let's teach Authorino about this host by applying 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. 
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

❽ Consume the API without credentials

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

Grant access to the API with a tailor-made security scheme

Check out other user guides for several use-cases of authentication and authorization, and the instructions to implement them using Authorino.

A few examples of available ser guides:

Cleanup

If you have started a Kubernetes cluster locally with Kind to try this user guide, delete it by running:

kind delete cluster --name authorino-tutorial

Otherwise, delete the namespaces created in step 1 and 5:

kubectl delete namespace hello-world
kubectl delete namespace authorino-operator

To uninstall the Authorino Operator and manifests (CRDs, RBAC, etc), run:

kubectl delete -f https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/config/deploy/manifests.yaml

  1. For details and instructions to setup Envoy manually, see Protect a service > Setup Envoy in the Getting Started page. If you are running your ingress gateway in Kubernetes and wants to avoid setting up and configuring your proxy manually, check out Kuadrant. ↩

  2. In contrast to a dedicated sidecar of the protected service and other architectures. Check out Architecture > Topologies for all options. ↩

  3. namespaced reconciliation mode. See Cluster-wide vs. Namespaced instances. ↩

  4. For other variants and deployment options, check out Getting Started, as well as the Authorino CRD specification. ↩