istio.io/istio@v0.0.0-20240520182934-d79c90f27776/samples/extauthz/README.md (about)

     1  # Ext Authz Service
     2  
     3  [Ext Authz server](cmd/extauthz) implements the external server for the [Envoy ext_authz filter](https://www.envoyproxy.io/docs/envoy/v1.16.0/intro/arch_overview/security/ext_authz_filter)
     4  as an example of integrating custom authorization system into Istio.
     5  
     6  The Ext Authz server supports authorization check request using either HTTP (port 8000) or gRPC v2/v3 (port 9000) API and
     7  will allow the request if it includes the header `x-ext-authz: allow` or if the service account of the source workload is `a`.
     8  Note that `a` is just a default value for testing. It can be changed with the flag `-allow_service_account` when running the ext authz server.
     9  
    10  ## Usage
    11  
    12  1. Deploy the Ext Authz service in a dedicated pod:
    13  
    14      ```console
    15      $ kubectl apply -f ext-authz.yaml
    16      service/ext-authz created
    17      deployment.apps/ext-authz created
    18      ```
    19  
    20      Note, you can also deploy the Ext Authz service locally with the application container in the same pod, see the example in `local-ext-authz.yaml`.
    21  
    22  1. Verify the Ext Authz server is up and running:
    23  
    24      Deploy a sleep pod to send the request:
    25  
    26      ```console
    27      $ kubectl apply -f ../sleep/sleep.yaml
    28      ```
    29  
    30      Send a check request with header `x-ext-authz: allow` to the Ext Authz server:
    31  
    32      ```console
    33      $ kubectl exec -it $(kubectl get pod -l app=sleep -o jsonpath={.items..metadata.name}) -c sleep -- curl -v ext-authz:8000 -H "x-ext-authz: allow"
    34         *   Trying 10.97.88.183:8000...
    35         * Connected to ext-authz-server (10.97.88.183) port 8000 (#0)
    36         > GET / HTTP/1.1
    37         > Host: ext-authz-server:8000
    38         > User-Agent: curl/7.73.0-DEV
    39         > Accept: */*
    40         > x-ext-authz: allow
    41         >
    42         * Mark bundle as not supporting multiuse
    43         < HTTP/1.1 200 OK
    44         < x-ext-authz-result: allowed
    45         < date: Tue, 03 Nov 2020 03:06:11 GMT
    46         < content-length: 0
    47         < x-envoy-upstream-service-time: 19
    48         < server: envoy
    49         <
    50         * Connection #0 to host ext-authz-server left intact
    51      ```
    52  
    53      As you observe, the check request with header `x-ext-authz: allow` is allowed by the Ext Authz server.
    54  
    55      Send another check request with `x-ext-authz: blabla` to the Ext Authz server:
    56  
    57      ```console
    58      $ kubectl exec -it $(kubectl get pod -l app=sleep -o jsonpath={.items..metadata.name}) -c sleep -- curl -v ext-authz:8000 -H "x-ext-authz: bla"
    59          > GET / HTTP/1.1
    60          > Host: ext-authz-server:8000
    61          > User-Agent: curl/7.73.0-DEV
    62          > Accept: */*
    63          > x-ext-authz: allowx
    64          >
    65          * Mark bundle as not supporting multiuse
    66          < HTTP/1.1 403 Forbidden
    67          < x-ext-authz-check-result: denied
    68          < date: Tue, 03 Nov 2020 03:14:02 GMT
    69          < content-length: 76
    70          < content-type: text/plain; charset=utf-8
    71          < x-envoy-upstream-service-time: 44
    72          < server: envoy
    73          <
    74          * Connection #0 to host ext-authz-server left intact
    75          denied by ext_authz for not found header `x-ext-authz: allow` in the request
    76      ```
    77  
    78      As you observe, the check request with header `x-ext-authz: bla` is denied by the Ext Authz server.
    79  
    80  1. To clean up, execute the following commands:
    81  
    82      ```console
    83      $ kubectl delete -f ../sleep/sleep.yaml
    84      $ kubectl delete -f ext-authz.yaml
    85      ```
    86  
    87  ## Advanced features
    88  
    89  The Ext Authz server supports the following advanced features that are useful for testing:
    90  
    91  - The ext authz server will add the `x-ext-authz-check-received` header to the user request. The content is the dump of
    92    the check request it received from the ext-authz filter. This header is useful in verifying the ext-authz filter sending
    93    the expected request to the ext authz server.
    94  
    95  - The ext authz server will add (or override if it already exists) the header `x-ext-authz-additional-header-override` to
    96    the user request. The value of the header depends on the type of ext-authz server.
    97    The ext authz HTTP server will set it to the value of the same `x-ext-authz-additional-header-override` header in the
    98    check request. The ext authz gRPC server will set it to the constant value `grpc-additional-header-override-value`.
    99    This header is useful in verifying the header override behavior in the ext-authz filter.