Skip to content

User guide: Hello World


Requirements

  • Kubernetes server

Create a containerized Kubernetes server locally using Kind:

kind create cluster --name authorino-tutorial

1. Create the namespace

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

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.

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

3. Setup Envoy

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

Forward requests on port 8000 to the Envoy pod running inside the cluster:

kubectl -n hello-world port-forward deployment/envoy 8000:8000 &

4. Consume the API (unprotected)

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

5. Protect the API

Install the Authorino Operator

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

Deploy Authorino

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 section of the docs, the Architecture page, and the spec for the Authorino CRD in the Authorino Operator repo.

6. Consume the API behind Envoy and Authorino

curl http://talker-api-authorino.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.

7. Apply an AuthConfig

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

curl http://talker-api-authorino.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 AuthN/AuthZ use-cases and instructions to implement them using Authorino. A few examples are:

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