Better External Authorization
AuthorizationPolicy now supports CUSTOM action to delegate the authorization to external system.
Background
Istio’s authorization policy provides access control for services in the mesh. It is fast, powerful and a widely used
feature. We have made continuous improvements to make policy more flexible since its first release in Istio 1.4, including
the DENY
action, exclusion semantics,
X-Forwarded-For
header support, nested JWT claim support
and more. These features improve the flexibility of the authorization policy, but there are still many use cases that
cannot be supported with this model, for example:
You have your own in-house authorization system that cannot be easily migrated to, or cannot be easily replaced by, the authorization policy.
You want to integrate with a 3rd-party solution (e.g. Open Policy Agent or
oauth2
proxy) which may require use of the low-level Envoy configuration APIs in Istio, or may not be possible at all.Authorization policy lacks necessary semantics for your use case.
Solution
In Istio 1.9, we have implemented extensibility into authorization policy by introducing a CUSTOM
action,
which allows you to delegate the access control decision to an external authorization service.
The CUSTOM
action allows you to integrate Istio with an external authorization system that implements its own custom
authorization logic. The following diagram shows the high level architecture of this integration:
At configuration time, the mesh admin configures an authorization policy with a CUSTOM
action to enable the
external authorization on a proxy (either gateway or sidecar). The admin should verify the external auth service is up
and running.
At runtime,
A request is intercepted by the proxy, and the proxy will send check requests to the external auth service, as configured by the user in the authorization policy.
The external auth service will make the decision whether to allow it or not.
If allowed, the request will continue and will be enforced by any local authorization defined by
ALLOW
/DENY
action.If denied, the request will be rejected immediately.
Let’s look at an example authorization policy with the CUSTOM
action:
apiVersion: security.istio.io/v1beta1
kind: AuthorizationPolicy
metadata:
name: ext-authz
namespace: istio-system
spec:
# The selector applies to the ingress gateway in the istio-system namespace.
selector:
matchLabels:
app: istio-ingressgateway
# The action "CUSTOM" delegates the access control to an external authorizer, this is different from
# the ALLOW/DENY action that enforces the access control right inside the proxy.
action: CUSTOM
# The provider specifies the name of the external authorizer defined in the meshconfig, which tells where and how to
# talk to the external auth service. We will cover this more later.
provider:
name: "my-ext-authz-service"
# The rule specifies that the access control is triggered only if the request path has the prefix "/admin/".
# This allows you to easily enable or disable the external authorization based on the requests, avoiding the external
# check request if it is not needed.
rules:
- to:
- operation:
paths: ["/admin/*"]
It refers to a provider called my-ext-authz-service
which is defined in the mesh config:
extensionProviders:
# The name "my-ext-authz-service" is referred to by the authorization policy in its provider field.
- name: "my-ext-authz-service"
# The "envoyExtAuthzGrpc" field specifies the type of the external authorization service is implemented by the Envoy
# ext-authz filter gRPC API. The other supported type is the Envoy ext-authz filter HTTP API.
# See more in https://www.envoyproxy.io/docs/envoy/v1.16.2/intro/arch_overview/security/ext_authz_filter.
envoyExtAuthzGrpc:
# The service and port specifies the address of the external auth service, "ext-authz.istio-system.svc.cluster.local"
# means the service is deployed in the mesh. It can also be defined out of the mesh or even inside the pod as a separate
# container.
service: "ext-authz.istio-system.svc.cluster.local"
port: 9000
The authorization policy of CUSTOM
action
enables the external authorization in runtime, it could be configured to trigger the external authorization conditionally
based on the request using the same rule that you have already been using with other actions.
The external authorization service is currently defined in the meshconfig
API
and referred to by its name. It could be deployed in the mesh with or without proxy. If with the proxy, you could
further use PeerAuthentication
to enable mTLS between the proxy and your external authorization service.
The CUSTOM
action is currently in the experimental stage; the API might change in a non-backward compatible way based on user feedback.
The authorization policy rules currently don’t support authentication fields (e.g. source principal or JWT claim) when used with the
CUSTOM
action. Only one provider is allowed for a given workload, but you can still use different providers on different workloads.
For more information, please see the Better External Authorization design doc.
Example with OPA
In this section, we will demonstrate using the CUSTOM
action with the Open Policy Agent as the external authorizer on
the ingress gateway. We will conditionally enable the external authorization on all paths except /ip
.
You can also refer to the external authorization task for a more
basic introduction that uses a sample ext-authz
server.
Create the example OPA policy
Run the following command create an OPA policy that allows the request if the prefix of the path is matched with the claim “path” (base64 encoded) in the JWT token:
$ cat > policy.rego <<EOF
package envoy.authz
import input.attributes.request.http as http_request
default allow = false
token = {"valid": valid, "payload": payload} {
[_, encoded] := split(http_request.headers.authorization, " ")
[valid, _, payload] := io.jwt.decode_verify(encoded, {"secret": "secret"})
}
allow {
is_token_valid
action_allowed
}
is_token_valid {
token.valid
now := time.now_ns() / 1000000000
token.payload.nbf <= now
now < token.payload.exp
}
action_allowed {
startswith(http_request.path, base64url.decode(token.payload.path))
}
EOF
$ kubectl create secret generic opa-policy --from-file policy.rego
Deploy httpbin and OPA
Enable the sidecar injection:
$ kubectl label ns default istio-injection=enabled
Run the following command to deploy the example application httpbin and OPA. The OPA could be deployed either as a separate container in the httpbin pod or completely in a separate pod:
$ kubectl apply -f - <<EOF
apiVersion: v1
kind: Service
metadata:
name: httpbin-with-opa
labels:
app: httpbin-with-opa
service: httpbin-with-opa
spec:
ports:
- name: http
port: 8000
targetPort: 80
selector:
app: httpbin-with-opa
---
# Define the service entry for the local OPA service on port 9191.
apiVersion: networking.istio.io/v1alpha3
kind: ServiceEntry
metadata:
name: local-opa-grpc
spec:
hosts:
- "local-opa-grpc.local"
endpoints:
- address: "127.0.0.1"
ports:
- name: grpc
number: 9191
protocol: GRPC
resolution: STATIC
---
kind: Deployment
apiVersion: apps/v1
metadata:
name: httpbin-with-opa
labels:
app: httpbin-with-opa
spec:
replicas: 1
selector:
matchLabels:
app: httpbin-with-opa
template:
metadata:
labels:
app: httpbin-with-opa
spec:
containers:
- image: docker.io/kennethreitz/httpbin
imagePullPolicy: IfNotPresent
name: httpbin
ports:
- containerPort: 80
- name: opa
image: openpolicyagent/opa:latest-envoy
securityContext:
runAsUser: 1111
volumeMounts:
- readOnly: true
mountPath: /policy
name: opa-policy
args:
- "run"
- "--server"
- "--addr=localhost:8181"
- "--diagnostic-addr=0.0.0.0:8282"
- "--set=plugins.envoy_ext_authz_grpc.addr=:9191"
- "--set=plugins.envoy_ext_authz_grpc.query=data.envoy.authz.allow"
- "--set=decision_logs.console=true"
- "--ignore=.*"
- "/policy/policy.rego"
livenessProbe:
httpGet:
path: /health?plugins
scheme: HTTP
port: 8282
initialDelaySeconds: 5
periodSeconds: 5
readinessProbe:
httpGet:
path: /health?plugins
scheme: HTTP
port: 8282
initialDelaySeconds: 5
periodSeconds: 5
volumes:
- name: proxy-config
configMap:
name: proxy-config
- name: opa-policy
secret:
secretName: opa-policy
EOF
$ kubectl apply -f - <<EOF
apiVersion: v1
kind: Service
metadata:
name: opa
labels:
app: opa
spec:
ports:
- name: grpc
port: 9191
targetPort: 9191
selector:
app: opa
---
kind: Deployment
apiVersion: apps/v1
metadata:
name: opa
labels:
app: opa
spec:
replicas: 1
selector:
matchLabels:
app: opa
template:
metadata:
labels:
app: opa
spec:
containers:
- name: opa
image: openpolicyagent/opa:latest-envoy
securityContext:
runAsUser: 1111
volumeMounts:
- readOnly: true
mountPath: /policy
name: opa-policy
args:
- "run"
- "--server"
- "--addr=localhost:8181"
- "--diagnostic-addr=0.0.0.0:8282"
- "--set=plugins.envoy_ext_authz_grpc.addr=:9191"
- "--set=plugins.envoy_ext_authz_grpc.query=data.envoy.authz.allow"
- "--set=decision_logs.console=true"
- "--ignore=.*"
- "/policy/policy.rego"
ports:
- containerPort: 9191
livenessProbe:
httpGet:
path: /health?plugins
scheme: HTTP
port: 8282
initialDelaySeconds: 5
periodSeconds: 5
readinessProbe:
httpGet:
path: /health?plugins
scheme: HTTP
port: 8282
initialDelaySeconds: 5
periodSeconds: 5
volumes:
- name: proxy-config
configMap:
name: proxy-config
- name: opa-policy
secret:
secretName: opa-policy
EOF
Deploy the httpbin as well:
$ kubectl apply -f @samples/httpbin/httpbin.yaml@
Define external authorizer
Run the following command to edit the meshconfig
:
$ kubectl edit configmap istio -n istio-system
Add the following extensionProviders
to the meshconfig
:
apiVersion: v1
data:
mesh: |-
# Add the following contents:
extensionProviders:
- name: "opa.local"
envoyExtAuthzGrpc:
service: "local-opa-grpc.local"
port: "9191"
apiVersion: v1
data:
mesh: |-
# Add the following contents:
extensionProviders:
- name: "opa.default"
envoyExtAuthzGrpc:
service: "opa.default.svc.cluster.local"
port: "9191"
Create an AuthorizationPolicy with a CUSTOM action
Run the following command to create the authorization policy that enables the external authorization on all paths
except /ip
:
$ kubectl apply -f - <<EOF
apiVersion: security.istio.io/v1beta1
kind: AuthorizationPolicy
metadata:
name: httpbin-opa
spec:
selector:
matchLabels:
app: httpbin-with-opa
action: CUSTOM
provider:
name: "opa.local"
rules:
- to:
- operation:
notPaths: ["/ip"]
EOF
$ kubectl apply -f - <<EOF
apiVersion: security.istio.io/v1beta1
kind: AuthorizationPolicy
metadata:
name: httpbin-opa
spec:
selector:
matchLabels:
app: httpbin
action: CUSTOM
provider:
name: "opa.default"
rules:
- to:
- operation:
notPaths: ["/ip"]
EOF
Test the OPA policy
Create a client pod to send the request:
$ kubectl apply -f @samples/sleep/sleep.yaml@ $ export SLEEP_POD=$(kubectl get pod -l app=sleep -o jsonpath={.items..metadata.name})
Use a test JWT token signed by the OPA:
$ export TOKEN_PATH_HEADERS="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXRoIjoiTDJobFlXUmxjbk09IiwibmJmIjoxNTAwMDAwMDAwLCJleHAiOjE5MDAwMDAwMDB9.9yl8LcZdq-5UpNLm0Hn0nnoBHXXAnK4e8RSl9vn6l98"
The test JWT token has the following claims:
{ "path": "L2hlYWRlcnM=", "nbf": 1500000000, "exp": 1900000000 }
The
path
claim has valueL2hlYWRlcnM=
which is the base64 encode of/headers
.Send a request to path
/headers
without a token. This should be rejected with 403 because there is no JWT token:$ kubectl exec ${SLEEP_POD} -c sleep -- curl http://httpbin-with-opa:8000/headers -s -o /dev/null -w "%{http_code}\n" 403
Send a request to path
/get
with a valid token. This should be rejected with 403 because the path/get
is not matched with the token/headers
:$ kubectl exec ${SLEEP_POD} -c sleep -- curl http://httpbin-with-opa:8000/get -H "Authorization: Bearer $TOKEN_PATH_HEADERS" -s -o /dev/null -w "%{http_code}\n" 403
Send a request to path
/headers
with valid token. This should be allowed with 200 because the path is matched with the token:$ kubectl exec ${SLEEP_POD} -c sleep -- curl http://httpbin-with-opa:8000/headers -H "Authorization: Bearer $TOKEN_PATH_HEADERS" -s -o /dev/null -w "%{http_code}\n" 200
Send request to path
/ip
without token. This should be allowed with 200 because the path/ip
is excluded from authorization:$ kubectl exec ${SLEEP_POD} -c sleep -- curl http://httpbin-with-opa:8000/ip -s -o /dev/null -w "%{http_code}\n" 200
Check the proxy and OPA logs to confirm the result.
Summary
In Istio 1.9, the CUSTOM
action in the authorization policy allows you to easily integrate Istio with any external
authorization system with the following benefits:
First-class support in the authorization policy API
Ease of usage: define the external authorizer simply with a URL and enable with the authorization policy, no more hassle with the
EnvoyFilter
APIConditional triggering, allowing improved performance
Support for various deployment type of the external authorizer:
A normal service and pod with or without proxy
Inside the workload pod as a separate container
Outside the mesh
We’re working to promote this feature to a more stable stage in following versions and welcome your feedback at discuss.istio.io.
Acknowledgements
Thanks to Craig Box
, Christian Posta
and Limin Wang
for reviewing drafts of this blog.