Set a Custom Error Status Code for an External Authorizer ​
Learn how to configure the statusOnError field of an external authorizer in the Istio custom resource (CR), so that Istio returns a custom HTTP status code when it cannot reach the external authorization service.
Context ​
When you protect a workload with an external authorizer, every request is first sent to the external authorization service for a decision. If Istio cannot reach that service because of a network error, it returns a status code to the client instead of the authorization decision. By default, this status code is 403.
The statusOnError field overrides this default. You set it on an authorizer in the Istio CR, and Istio returns the configured status code whenever the external authorization service is unreachable.
The statusOnError Field ​
The statusOnError field defines the HTTP status code that Istio returns to the client when a network error to the external authorization service occurs. It applies only to network errors, not to a regular deny decision from the authorization service.
The field accepts a string that contains a 4xx or 5xx HTTP status code, for example, "417". The following rules apply:
- The value must be a three-digit status code in the 4xx or 5xx range. Other values are rejected when you apply the Istio CR.
- The value must be the numeric status code, such as
"403", not the name of the code, such asFORBIDDEN. - The status code must be one of the codes defined in Envoy's
type.v3.StatusCodeenum. Envoy ignores a code that is outside this enum, such as418, and falls back to the default status code403. - If you don't set the field, Istio uses the default status code
403.
Methods of Configuring an External Authorizer ​
You can point an authorizer at the external authorization service in two ways:
- In-cluster workload: The authorizer's service field references a Kubernetes Service that runs in your cluster. Use this method when the authorization service runs as a workload in the mesh.
- ServiceEntry and DestinationRule: The authorizer's service field references a host that you register in Istio's service registry with a ServiceEntry. A DestinationRule configures how Envoy connects to that host. Use this method when the authorization service runs outside the cluster.
This tutorial uses an authorization service that is deliberately unreachable, so you can observe the statusOnError fallback. It shows both configuration methods.
Prerequisites ​
- You have the Istio module in your cluster.
- To expose the workload, choose one of the following approaches:
Use the default domain of your Kyma cluster and the default Gateway
kyma-system/kyma-gateway. This Gateway is available only when you add the API Gateway module.TIP
To find the default domain of your Kyma cluster, run
kubectl get gateways.networking.istio.io -n kyma-system kyma-gateway -o jsonpath='{.spec.servers[0].hosts}'.Use a custom domain and a custom TLS Gateway. See Configure a TLS Gateway in SAP BTP, Kyma Runtime.
Procedure ​
Expose a Sample Workload ​
Export the name of the namespace in which you want to deploy the sample workload:
bashexport NAMESPACE={NAMESPACE_NAME}Create the namespace with Istio sidecar injection enabled, and deploy a sample HTTPBin workload:
bashkubectl create namespace $NAMESPACE kubectl label namespace $NAMESPACE istio-injection=enabled --overwrite kubectl apply --namespace $NAMESPACE --filename https://raw.githubusercontent.com/istio/istio/master/samples/httpbin/httpbin.yamlExport the name of your domain and Gateway:
bashexport DOMAIN_NAME={YOUR_DOMAIN_NAME} export GATEWAY={GATEWAY_NAMESPACE}/{GATEWAY_NAME}Create a VirtualService to expose the workload:
bashcat <<EOF | kubectl apply -f - apiVersion: networking.istio.io/v1 kind: VirtualService metadata: name: httpbin namespace: $NAMESPACE spec: hosts: - "httpbin.$DOMAIN_NAME" gateways: - $GATEWAY http: - match: - uri: prefix: / route: - destination: host: httpbin.$NAMESPACE.svc.cluster.local port: number: 8000 EOF
Configure the External Authorizer ​
Choose one of the following methods to register the external authorizer. Both methods point the authorizer at an unreachable authorization service and set statusOnError to "417".
Method 1: Reference an In-Cluster Workload ​
Deploy a sample authorization service, and then register an authorizer whose service field references its Kubernetes Service.
Note: ​
The Kubernetes Service that the service field references must be deployed in your cluster. If the Service doesn't exist, Istio returns the default status code
403regardless of the statusOnError setting. In this tutorial, the authorization call fails because the port is unreachable, not because the Service is missing.
Export the name of the namespace for the authorization service:
bashexport AUTH_NAMESPACE={AUTH_NAMESPACE_NAME}Create the namespace with Istio sidecar injection enabled:
Note: ​
The authorization service must run in a namespace that has Istio sidecar injection enabled. Without the injected sidecar, the external authorization check isn't applied.
bashkubectl create namespace $AUTH_NAMESPACE kubectl label namespace $AUTH_NAMESPACE istio-injection=enabled --overwriteDeploy a sample HTTPBin workload as the authorization service:
bashkubectl apply --namespace $AUTH_NAMESPACE --filename https://raw.githubusercontent.com/istio/istio/master/samples/httpbin/httpbin.yamlRegister an authorizer whose service field references the HTTPBin Service. Set the port to a port on which no workload listens, so the authorization call fails with a network error:
bashcat <<EOF | kubectl apply -f - apiVersion: operator.kyma-project.io/v1alpha2 kind: Istio metadata: name: default namespace: kyma-system spec: config: authorizers: - name: httpbin-authorizer service: "httpbin.$AUTH_NAMESPACE.svc.cluster.local" port: 9999 timeout: 2s statusOnError: "417" EOF
Method 2: Reference a ServiceEntry and DestinationRule ​
Register an authorizer whose service field references a host that exists only in Istio's service registry. Because the host doesn't resolve to a running service, the authorization call fails with a network error.
Create a ServiceEntry and a DestinationRule for the external host:
Note: ​
The host
ext-authz.example.invaliduses the reserved.invalidtop-level domain, so it never resolves to a real service.bashcat <<EOF | kubectl apply -f - apiVersion: networking.istio.io/v1 kind: ServiceEntry metadata: name: ext-authz namespace: kyma-system spec: hosts: - ext-authz.example.invalid location: MESH_EXTERNAL resolution: DNS ports: - number: 9999 name: http protocol: HTTP --- apiVersion: networking.istio.io/v1 kind: DestinationRule metadata: name: ext-authz namespace: kyma-system spec: host: ext-authz.example.invalid trafficPolicy: connectionPool: tcp: connectTimeout: 1s EOFRegister the authorizer with the ServiceEntry host:
bashcat <<EOF | kubectl apply -f - apiVersion: operator.kyma-project.io/v1alpha2 kind: Istio metadata: name: default namespace: kyma-system spec: config: authorizers: - name: httpbin-authorizer service: "ext-authz.example.invalid" port: 9999 timeout: 2s statusOnError: "417" EOF
Activate the Authorizer ​
Wait until the Istio CR is in the
Readystate:bashkubectl wait --for=jsonpath='{.status.state}'=Ready istio/default --namespace kyma-system --timeout=180sCreate an AuthorizationPolicy CR with the CUSTOM action that references the authorizer:
bashcat <<EOF | kubectl apply -f - apiVersion: security.istio.io/v1 kind: AuthorizationPolicy metadata: name: ext-authz namespace: $NAMESPACE spec: action: CUSTOM provider: name: httpbin-authorizer rules: - to: - operation: paths: ["/*"] EOF
Results ​
Send a request to the exposed workload:
curl -s -o /dev/null -w "%{http_code}\n" "https://httpbin.$DOMAIN_NAME/headers"The authorizer cannot reach the authorization service, so Istio applies the statusOnError fallback. The request returns the status code 417 instead of the default 403.
Note: ​
The CUSTOM-provider configuration takes some time to propagate to the sidecar proxy. If the request returns
200, wait a moment, and then try again.