github.com/projectcontour/contour@v1.28.2/site/content/docs/v1.17.0/config/client-authorization.md (about)

     1  # Client Authorization
     2  
     3  Contour supports integrating external servers to authorize client requests.
     4  
     5  Envoy implements external authorization in the [ext_authz][1] filter.
     6  This filter intercepts client requests and holds them while it sends a check
     7  request to an external server.
     8  The filter uses the check result to either allow the request to proceed, or to
     9  deny or redirect the request.
    10  
    11  The diagram below shows the sequence of requests involved in the successful
    12  authorization of a HTTP request:
    13  
    14  <p align="center">
    15  <img src="/img/uml/client-auth-sequence.png" alt="client authorization sequence diagram"/>
    16  </p>
    17  
    18  The [external authorization][7] guides demonstrates how to deploy HTTP basic
    19  authentication using Contour and [contour-authserver](https://github.com/projectcontour/contour-authserver).
    20  
    21  ## Extension Services
    22  
    23  The starting point for external authorization in Contour is the
    24  [ExtensionService][2] API.
    25  This API creates a cluster which Envoy can use to send requests to an external server.
    26  In principle, the Envoy cluster can be used for any purpose, but in this
    27  document we are concerned only with how to use it as an authorization service.
    28  
    29  An authorization service is a gRPC service that implements the Envoy [CheckRequest][3] protocol.
    30  Note that Contour requires the extension to implement the "v3" version of the protocol.
    31  Contour is compatible with any authorization server that implements this protocol.
    32  
    33  The primary field of interest in the `ExtensionService` CRD is the
    34  `.spec.services` field.
    35  This field lists the Kubernetes Services that will receive the check requests.
    36  The `.spec.services[].name` field contains the name of the Service, which must
    37  exist in the name namespace as the `ExtensionService` object.
    38  The `ExtensionService` object must exist in the name namespace as the
    39  Services they target to ensure that both objects are under the same
    40  administrative control.
    41  
    42  ### Load Balancing for Extension Services
    43  
    44  An `ExtensionService` can be configured to send traffic to multiple Kubernetes Services.
    45  In this case, requests are divided proportionally across the Services according
    46  to the weight in the `.spec.services[].weight` field.
    47  The service weight can be used to flexibly shift traffic between Services for
    48  reasons like implementing blue-green deployments.
    49  The `.spec.loadBalancerPolicy` field configures how Envoy will load balance
    50  requests to the endpoints within each Service.
    51  
    52  ### TLS Validation for Extension Services
    53  
    54  Since authorizing a client request may involve passing sensitive credentials
    55  from a HTTP request to the authorization service, the connection to the
    56  authorization server should be as secure as possible.
    57  Contour defaults the `.spec.protocol` field to "h2", which configures
    58  Envoy to use HTTP/2 over TLS for the authorization service connection.
    59  
    60  The [.spec.validation][4] field configures how Envoy should verify the TLS
    61  identity of the authorization server.
    62  This is a critical protection against accidentally sending credentials to an
    63  imposter service and should be enabled for all production deployments.
    64  The `.spec.validation` field should specify the expected server name
    65  from the authorization server's TLS certificate, and the trusted CA bundle
    66  that can be used to validate the TLS chain of trust.
    67  
    68  ### Side-car Authorization Server
    69  
    70  Instead of running the authorization server as a separate set of Pods it can
    71  also be run as a side-car alongside each Envoy Pod, accessed over localhost.
    72  To achieve this, create a Service of type ExternalName that resolves to the
    73  localhost IP - for example:
    74  ```
    75  kind: Service
    76  apiVersion: v1
    77  metadata:
    78    name: localhost
    79  spec:
    80    type: ExternalName
    81    externalName: localhost
    82  selector: {}
    83  ```
    84  and set the `.spec.services[].name` field to the name of the Service.
    85  
    86  ## Authorizing Virtual Hosts
    87  
    88  The [.spec.virtualhost.authorization][5] field in the Contour `HTTPProxy`
    89  API connects a virtual host to an authorization server that is bound by an
    90  `ExtensionService` object.
    91  Each virtual host can use a different `ExtensionService`, but only one
    92  `ExtensionService` can be used by a single virtual host.
    93  Authorization servers can only be attached to `HTTPProxy` objects that have TLS
    94  termination enabled.
    95  
    96  ### Migrating from Application Authorization
    97  
    98  When applications perform their own authorization, migrating to centralized
    99  authorization may need some planning.
   100  The `.spec.virtualhost.authorization.failOpen` field controls how client
   101  requests should be handled when the authorization server fails.
   102  During a migration process, this can be set to `true`, so that if the
   103  authorization server becomes unavailable, clients can gracefully fall back to
   104  the existing application authorization mechanism.
   105  
   106  ### Scoping Authorization Policy Settings
   107  
   108  It is common for services to contain some HTTP request paths that require
   109  authorization and some that do not.
   110  The HTTPProxy [authorization policy][6] allows authorization to be
   111  disabled for both an entire virtual host and for specific routes.
   112  
   113  The initial authorization policy is set on the HTTPProxy virtual host
   114  in the `.spec.virtualhost.authorization.authPolicy` field. 
   115  This configures whether authorization is enabled, and the default authorization policy context.
   116  If authorization is disabled on the virtual host, it is also disabled by
   117  default on all the routes for that virtual host that do not specify an authorization policy.
   118  However, a route can configure its own authorization policy (in the
   119  `.spec.routes[].authPolicy` field) that can configure whether authorization
   120  is enabled, irrespective of the virtual host setting.
   121  
   122  The authorization policy context is a way to configure a set of key/value
   123  pairs that will be sent to the authorization server with each request check
   124  request.
   125  The keys and values that should be specified here depend on which authorization
   126  server has been configured.
   127  This facility is intended for configuring authorization-specific information, such as
   128  the basic authentication realm, or OIDC parameters.
   129  
   130  The initial context map can be set on the virtual host.
   131  This sets the context keys that will be sent on every check request.
   132  A route can overwrite the value for a context key by setting it in the
   133  context field of authorization policy for the route.
   134  
   135  [1]: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_authz_filter
   136  [2]: api/#projectcontour.io/v1alpha1.ExtensionService
   137  [3]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/external_auth.proto
   138  [4]: api/#projectcontour.io/v1.UpstreamValidation
   139  [5]: api/#projectcontour.io/v1.AuthorizationServer
   140  [6]: api/#projectcontour.io/v1.AuthorizationPolicy
   141  [7]: /guides/external-authorization.md