Edge Authentication Architecture (EAA) is a pattern where more than extracting authentication logics and specifics from the application codebase to a proper authN/authZ layer, this is pushed to the edge of your cloud network, without violating the Zero Trust principle nevertheless.
The very definition of "edge" is subject to discussion, but the underlying idea is that clients (e.g. API clients, IoT devices, etc.) authenticate with a layer that, before moving traffic to inside the network:
- understands the complexity of all the different methods of authentication supported;
- sometimes some token normalization is involved;
- eventually enforces some preliminary authorization policies; and
- possibly filters data bits that are sensitive to privacy concerns (e.g. to comply with local legislation such as GRPD, CCPA, etc)
As a minimum, EAA allows to simplify authentication between applications and microservices inside the network, as well as to reduce authorization to domain-specific rules and policies, rather than having to deal all the complexity to support all types of clients in every node.
Authorino capabilities featured in this guide:
- Dynamic response → Festival Wristband tokens
- Identity verification & authentication → Identity extension
- Identity verification & authentication → API key
- Identity verification & authentication → JWT verification
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.
Check out as well the user guides about Token normalization, Authentication with API keys and OpenID Connect Discovery and authentication with JWTs.
For further details about Authorino features in general, check the docs.
- 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)
- jq, to extract parts of JSON responses
- jwt, to inspect JWTs (optional)
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-tutorialDeploy 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.
kubectl create namespace keycloak
kubectl -n keycloak apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/keycloak/keycloak-deploy.yamlThe 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 For more about using Kuadrant to enforce authorization, check out Kuadrant auth. |
The following command will install the Authorino Operator in the Kubernetes cluster. The operator manages instances of the Authorino authorization service.
curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | bash -sFor 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.
kubectl create namespace authorino
kubectl create namespace edge
kubectl create namespace internalThe following command will request an instance of Authorino as a separate service1 that watches for AuthConfig resources cluster-wide2, with TLS disabled3.
kubectl -n authorino apply -f -<<EOF
apiVersion: operator.authorino.kuadrant.io/v1beta1
kind: Authorino
metadata:
name: authorino
spec:
clusterWide: true
listener:
tls:
enabled: false
oidcServer:
tls:
enabled: false
EOFThe following bundle from the Authorino examples deploys the Envoy proxy and configuration to wire up external authorization with the Authorino instance.4
kubectl -n edge apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/eaa/envoy-edge-deploy.yamlThe 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:
kubectl -n edge port-forward deployment/envoy 9000:9000 2>&1 >/dev/null &Create a required secret that will be used by Authorino to sign the Festival Wristband tokens:
kubectl -n edge apply -f -<<EOF
apiVersion: v1
kind: Secret
metadata:
name: wristband-signing-key
stringData:
key.pem: |
-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIDHvuf81gVlWGo0hmXGTAnA/HVxGuH8vOc7/8jewcVvqoAoGCCqGSM49
AwEHoUQDQgAETJf5NLVKplSYp95TOfhVPqvxvEibRyjrUZwwtpDuQZxJKDysoGwn
cnUvHIu23SgW+Ee9lxSmZGhO4eTdQeKxMA==
-----END EC PRIVATE KEY-----
type: Opaque
EOFCreate the config:
Kuadrant users –
Remember to create an AuthPolicy instead of an AuthConfig.
For more, see Kuadrant auth.
|
kubectl -n edge apply -f -<<EOF
apiVersion: authorino.kuadrant.io/v1beta3
kind: AuthConfig
metadata:
name: edge-auth
spec:
hosts:
- edge.127.0.0.1.nip.io
authentication:
"api-clients":
apiKey:
selector:
matchLabels:
authorino.kuadrant.io/managed-by: authorino
allNamespaces: true
credentials:
authorizationHeader:
prefix: APIKEY
overrides:
"username":
selector: auth.identity.metadata.annotations.authorino\.kuadrant\.io/username
"idp-users":
jwt:
issuerUrl: http://keycloak.keycloak.svc.cluster.local:8080/realms/kuadrant
defaults:
"username":
selector: auth.identity.preferred_username
response:
success:
dynamicMetadata:
"wristband":
wristband:
issuer: http://authorino-authorino-oidc.authorino.svc.cluster.local:8083/edge/edge-auth/wristband
customClaims:
"username":
selector: auth.identity.username
tokenDuration: 300
signingKeyRefs:
- name: wristband-signing-key
algorithm: ES256
EOFThe 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 internal apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yamlThis other 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.
kubectl -n internal apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/eaa/envoy-node-deploy.yamlThe 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 internal port-forward deployment/envoy 8000:8000 2>&1 >/dev/null &
Kuadrant users –
Remember to create an AuthPolicy instead of an AuthConfig.
For more, see Kuadrant auth.
|
kubectl -n internal apply -f -<<EOF
apiVersion: authorino.kuadrant.io/v1beta3
kind: AuthConfig
metadata:
name: talker-api-protection
spec:
hosts:
- talker-api.127.0.0.1.nip.io
authentication:
"edge-authenticated":
jwt:
issuerUrl: http://authorino-authorino-oidc.authorino.svc.cluster.local:8083/edge/edge-auth/wristband
EOFkubectl -n edge apply -f -<<EOF
apiVersion: v1
kind: Secret
metadata:
name: api-key-1
labels:
authorino.kuadrant.io/managed-by: authorino
annotations:
authorino.kuadrant.io/username: alice
authorino.kuadrant.io/email: alice@host
stringData:
api_key: ndyBzreUzF4zqDQsqSPMHkRhriEOtcRx
type: Opaque
EOFAuthenticate at the edge:
WRISTBAND_TOKEN=$(curl -H 'Authorization: APIKEY ndyBzreUzF4zqDQsqSPMHkRhriEOtcRx' http://edge.127.0.0.1.nip.io:9000/auth -is | tr -d '\r' | sed -En 's/^x-wristband-token: (.*)/\1/p')Consume the API:
curl -H "Authorization: Bearer $WRISTBAND_TOKEN" http://talker-api.127.0.0.1.nip.io:8000/hello -i
# HTTP/1.1 200 OKTry to consume the API with authentication token that is only accepted in the edge:
curl -H "Authorization: APIKEY ndyBzreUzF4zqDQsqSPMHkRhriEOtcRx" http://talker-api.127.0.0.1.nip.io:8000/hello -i
# HTTP/1.1 401 Unauthorized
# www-authenticate: Bearer realm="edge-authenticated"
# x-ext-auth-reason: credential not found(Optional) Inspect the wristband token and verify that it only contains restricted info to authenticate and authorize with internal apps.
jwt decode $WRISTBAND_TOKEN
# [...]
#
# Token claims
# ------------
# {
# "exp": 1638452051,
# "iat": 1638451751,
# "iss": "http://authorino-authorino-oidc.authorino.svc.cluster.local:8083/edge/edge-auth/wristband",
# "sub": "02cb51ea0e1c9f3c0960197a2518c8eb4f47e1b9222a968ffc8d4c8e783e4d19",
# "username": "alice"
# }Obtain an access token with the Keycloak server for Jane:
The AuthConfig deployed in the previous step is suitable for validating access tokens requested inside the cluster. This is because Keycloak's iss claim added to the JWTs matches always the host used to request the token and Authorino will later try to match this host to the host that provides the OpenID Connect configuration.
Obtain an access token from within the cluster for the user Jane, whose e-mail has been verified:
ACCESS_TOKEN=$(kubectl -n edge run token --attach --rm --restart=Never -q --image=curlimages/curl -- http://keycloak.keycloak.svc.cluster.local:8080/realms/kuadrant/protocol/openid-connect/token -s -d 'grant_type=password' -d 'client_id=demo' -d 'username=jane' -d 'password=p' -d 'scope=openid' | jq -r .access_token)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.
(Optional) Inspect the access token issue by Keycloak and verify and how it contains more details about the identity than required to authenticate and authorize with internal apps.
jwt decode $ACCESS_TOKEN
# [...]
#
# Token claims
# ------------
# { [...]
# "email": "[email protected]",
# "email_verified": true,
# "exp": 1638452220,
# "family_name": "Smith",
# "given_name": "Jane",
# "iat": 1638451920,
# "iss": "http://keycloak.keycloak.svc.cluster.local:8080/realms/kuadrant",
# "jti": "699f6e49-dea4-4f29-ae2a-929a3a18c94b",
# "name": "Jane Smith",
# "preferred_username": "jane",
# "realm_access": {
# "roles": [
# "offline_access",
# "member",
# "admin",
# "uma_authorization"
# ]
# },
# [...]As Jane, obtain a limited wristband token at the edge:
WRISTBAND_TOKEN=$(curl -H "Authorization: Bearer $ACCESS_TOKEN" http://edge.127.0.0.1.nip.io:9000/auth -is | tr -d '\r' | sed -En 's/^x-wristband-token: (.*)/\1/p')Consume the API:
curl -H "Authorization: Bearer $WRISTBAND_TOKEN" http://talker-api.127.0.0.1.nip.io:8000/hello -i
# HTTP/1.1 200 OKIf you have started a Kubernetes cluster locally with Kind to try this user guide, delete it by running:
kind delete cluster --name authorino-tutorialOtherwise, delete the resources created in each step:
kubectl delete namespace edge
kubectl delete namespace internal
kubectl delete namespace authorino
kubectl delete namespace keycloakTo uninstall the Authorino and Authorino Operator manifests, run:
kubectl delete -f https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/config/deploy/manifests.yamlFootnotes
-
In contrast to a dedicated sidecar of the protected service and other architectures. Check out Architecture > Topologies for all options. ↩
-
cluster-widereconciliation mode. See Cluster-wide vs. Namespaced instances. ↩ -
For other variants and deployment options, check out Getting Started, as well as the
AuthorinoCRD specification. ↩ -
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. ↩