Skip to content

User guide: Authentication with Kubernetes tokens (TokenReview API)

Validate Kubernetes Service Account tokens to authenticate requests to your protected hosts.

Authorino features in this guide: Authorino can verify Kubernetes-valid access tokens (using Kubernetes [TokenReview]( API). These tokens can be either `ServiceAccount` tokens or any valid user access tokens issued to users of the Kubernetes server API. 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](./../


  • Kubernetes server
  • Kubernetes user with permission to create TokenRequests (to consume the API from outside the cluster)
  • yq (to parse your ~/.kube/config file to extract user authentication data)

Create a containerized Kubernetes server locally using Kind:

kind create cluster --name authorino-tutorial

1. Install the Authorino Operator

curl -sL | bash -s

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 apply -f

3. Deploy Authorino

kubectl apply -f -<<EOF
kind: Authorino
  name: authorino
      enabled: false
      enabled: false

The command above will deploy Authorino as a separate service (as opposed to a sidecar of the protected API and other architectures), in namespaced reconciliation mode, and with TLS termination disabled. 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.

4. 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 Talker API behind the reverse-proxy and external authorization with the Authorino instance.

For details and instructions to setup Envoy manually, see Protect a service > Setup Envoy in the Getting Started page. For a simpler and straightforward way to manage an API, without having to manually install or configure Envoy and Authorino, check out Kuadrant.

kubectl apply -f

The bundle also creates an Ingress with host name, 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:

kubectl port-forward deployment/envoy 8000:8000 &

5. Create the AuthConfig

kubectl apply -f -<<EOF
kind: AuthConfig
  name: talker-api-protection
  - envoy.default.svc.cluster.local
        - talker-api

6. Create a ServiceAccount

kubectl apply -f -<<EOF
apiVersion: v1
kind: ServiceAccount
  name: api-consumer-1

7. Consume the API from outside the cluster

Obtain a short-lived access token for the api-consumer-1 ServiceAccount:

export ACCESS_TOKEN=$(echo '{ "apiVersion": "", "kind": "TokenRequest", "spec": { "audiences": ["talker-api"], "expirationSeconds": 600 } }' | kubectl create --raw /api/v1/namespaces/default/serviceaccounts/api-consumer-1/token -f - | jq -r .status.token)

Consume the API with a valid Kubernetes token:

curl -H "Authorization: Bearer $ACCESS_TOKEN"
# HTTP/1.1 200 OK

Consume the API with the Kubernetes token expired (10 minutes):

curl -H "Authorization: Bearer $ACCESS_TOKEN"
# HTTP/1.1 401 Unauthorized
# www-authenticate: Bearer realm="authorized-service-accounts"
# x-ext-auth-reason: Not authenticated

8. Consume the API from inside the cluster

Deploy an application that consumes an endpoint of the Talker API, in a loop, every 10 seconds. The application uses a short-lived service account token mounted inside the container using Kubernetes Service Account Token Volume Projection to authenticate.

kubectl apply -f -<<EOF
apiVersion: v1
kind: Pod
  name: api-consumer
  - name: api-consumer
    command: ["./run"]
      - --endpoint=http://envoy.default.svc.cluster.local:8000/hello
      - --token-path=/var/run/secrets/tokens/api-token
      - --interval=10
    - mountPath: /var/run/secrets/tokens
      name: talker-api-access-token
  serviceAccountName: api-consumer-1
  - name: talker-api-access-token
      - serviceAccountToken:
          path: api-token
          expirationSeconds: 7200
          audience: talker-api

Check the logs of api-consumer:

kubectl logs -f api-consumer
# Sending...
# 200
# 200
# 200
# 200
# ...


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 resources created in each step:

kubectl pod/api-consumer
kubectl serviceaccount/api-consumer-1
kubectl delete authconfig/talker-api-protection
kubectl delete authorino/authorino
kubectl delete -f
kubectl delete -f

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

kubectl delete -f