User guide: Fetching auth metadata from external sources
Get online data from remote HTTP services to enhance authorization rules.
Authorino features in this guide:
- External auth metadata → HTTP GET/GET-by-POST
- Identity verification & authentication → API key
- Authorization → Open Policy Agent (OPA) Rego policies
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).
For further details about Authorino features in general, check the [docs](./../features.md).
Requirements
- Kubernetes server
Create a containerized Kubernetes server locally using Kind:
1. Install the Authorino Operator
curl -sL https://raw.githubusercontent.com/Kuadrant/authorino-operator/main/utils/install.sh | 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 https://raw.githubusercontent.com/kuadrant/authorino-examples/main/talker-api/talker-api-deploy.yaml
3. Deploy Authorino
kubectl apply -f -<<EOF
apiVersion: operator.authorino.kuadrant.io/v1beta1
kind: Authorino
metadata:
name: authorino
spec:
listener:
tls:
enabled: false
oidcServer:
tls:
enabled: false
EOF
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 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:
5. Create the 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.
The implementation relies on the X-Forwarded-For HTTP header to read the client's IP address.
kubectl apply -f -<<EOF
apiVersion: authorino.kuadrant.io/v1beta2
kind: AuthConfig
metadata:
name: talker-api-protection
spec:
hosts:
- talker-api-authorino.127.0.0.1.nip.io
authentication:
"friends":
apiKey:
selector:
matchLabels:
group: friends
credentials:
authorizationHeader:
prefix: APIKEY
metadata:
"geo":
http:
url: 'http://ip-api.com/json/{context.request.http.headers.x-forwarded-for.@extract:{"sep":","}}?fields=countryCode'
headers:
"Accept":
value: application/json
authorization:
"geofence":
opa:
rego: |
import input.context.request.http
allow {
http.method = "GET"
split(http.path, "/") = [_, requested_country, _]
lower(requested_country) == lower(object.get(input.auth.metadata.geo, "countryCode", ""))
}
EOF
Check out the docs for information about the common feature JSON paths for reading from the Authorization JSON, including the description of the @extract string modifier.
6. Create an API key
kubectl apply -f -<<EOF
apiVersion: v1
kind: Secret
metadata:
name: api-key-1
labels:
authorino.kuadrant.io/managed-by: authorino
group: friends
stringData:
api_key: ndyBzreUzF4zqDQsqSPMHkRhriEOtcRx
type: Opaque
EOF
7. Consume the API
From an IP address assigned to the United Kingdom of Great Britain and Northern Ireland (country code GB):
curl -H 'Authorization: APIKEY ndyBzreUzF4zqDQsqSPMHkRhriEOtcRx' \
-H 'X-Forwarded-For: 79.123.45.67' \
http://talker-api-authorino.127.0.0.1.nip.io:8000/gb/hello -i
# HTTP/1.1 200 OK
curl -H 'Authorization: APIKEY ndyBzreUzF4zqDQsqSPMHkRhriEOtcRx' \
-H 'X-Forwarded-For: 79.123.45.67' \
http://talker-api-authorino.127.0.0.1.nip.io:8000/it/hello -i
# HTTP/1.1 403 Forbidden
From an IP address assigned to Italy (country code IT):
curl -H 'Authorization: APIKEY ndyBzreUzF4zqDQsqSPMHkRhriEOtcRx' \
-H 'X-Forwarded-For: 109.112.34.56' \
http://talker-api-authorino.127.0.0.1.nip.io:8000/gb/hello -i
# HTTP/1.1 403 Forbidden
curl -H 'Authorization: APIKEY ndyBzreUzF4zqDQsqSPMHkRhriEOtcRx' \
-H 'X-Forwarded-For: 109.112.34.56' \
http://talker-api-authorino.127.0.0.1.nip.io:8000/it/hello -i
# HTTP/1.1 200 OK
Cleanup
If you have started a Kubernetes cluster locally with Kind to try this user guide, delete it by running:
Otherwise, delete the resources created in each step:
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
To uninstall the Authorino Operator and manifests (CRDs, RBAC, etc), run: