외부 인증 Envoy 확장

외부 인증 Envoy 확장 (External authorization Envoy extension)

이 주제는 Envoy 프록시가 외부 서비스에 인증을 요청하도록 구성하는 외부 인증(ext-authz) Envoy 확장을 구성하는 방법을 설명해요. Envoy는 외부 서비스의 응답에 따라 요청을 허용하거나 거부해요.

출처: 문서

본문

이 주제는 Envoy 프록시가 외부 서비스에 인증을 요청하도록 구성하는 외부 인증 Envoy 확장을 구성하는 방법을 설명합니다. 이 확장은 Envoy 프록시가 외부 서비스에 인증을 요청하도록 구성합니다.

구성 모델 (Configuration model)

다음 목록은 외부 인증 구성의 필드 계층, 데이터 유형, 요구 사항을 설명합니다. 구성을 프록시 기본값(proxy defaults) 또는 서비스 기본값(service defaults) 구성 항목의 EnvoyExtension.Arguments 필드 안에 배치하세요. 추가 정보는 다음 문서를 참조하세요:

속성 이름을 클릭하면 기본값을 포함한 추가 세부 정보를 볼 수 있습니다.

Name: string | required | must be set to builtin/ext-authz
Arguments: map | required
- ProxyType: string | required | connect-proxy
- ListenerType: string | required | inbound
- InsertOptions: map
  - Location: string
  - FilterName: string
- Config: map | required
  - BootstrapMetadataLabelsKey: string
  - ClearRouteCache: boolean | false | HTTP only
  - AllowedHeaders: list
    - Contains: string
    - Exact: string
    - IgnoreCase: boolean
    - Prefix: string
    - SafeRegex: string
    - Suffix: string
  - DisallowedHeaders: list
    - Contains: string
    - Exact: string
    - IgnoreCase: boolean
    - Prefix: string
    - SafeRegex: string
    - Suffix: string
  - GrpcService: map
    - Target: map | required
      - Service: map
        
        Name: string
        
        Namespace: string |

Enterprise

        * [`Partition`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-grpcservice-target-service): string |

Enterprise

      * [`URI`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-grpcservice-target-uri): string 
      * [`Timeout`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-grpcservice-target-uri): string | `1s`
    * [`Authority`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-grpcservice-authority): string 
    * [`InitialMetadata`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-grpcservice-initialmetadata): list
      * [`Key`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-grpcservice-initialmetadata): string 
      * [`Value`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-grpcservice-initialmetadata): string 
  * [`HttpService`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice): map
    * [`Target`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-target): map | required
      * [`Service`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice): string
        * [`Name`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-target-service): string
        * [`Namespace`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-target-service): string |

Enterprise

        * [`Partition`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-target-service): string |

Enterprise

      * [`URI`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice): string 
      * [`Timeout`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice): string | `1s`
    * [`PathPrefix`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-pathprefix): string 
    * [`AuthorizationRequest`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationrequest): map 
      * [`AllowedHeaders`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationrequest-allowedheaders): list
        * [`Contains`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationrequest-allowedheaders): string 
        * [`Exact`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationrequest-allowedheaders): string 
        * [`IgnoreCase`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationrequest-allowedheaders): boolean 
        * [`Prefix`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationrequest-allowedheaders): string 
        * [`SafeRegex`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationrequest-allowedheaders): string 
      * [`HeadersToAdd`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationrequest-headerstoadd): list
        * [`Key`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationrequest-headerstoadd): string 
        * [`Value`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationrequest-headerstoadd): string 
    * [`AuthorizationResponse`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse): map
      * [`AllowedUpstreamHeaders`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedupstreamheaders): list
        * [`Contains`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedupstreamheaders): string 
        * [`Exact`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedheaders): string 
        * [`IgnoreCase`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedheaders): boolean 
        * [`Prefix`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedheaders): string 
        * [`SafeRegex`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedheaders): string 
        * [`Suffix`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedheaders): string 
      * [`AllowedUpstreamHeadersToAppend`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedupstreamheaderstoappend): list
        * [`Contains`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedupstreamheaderstoappend): string 
        * [`Exact`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedupstreamheaderstoappend): string 
        * [`IgnoreCase`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedupstreamheaderstoappend): boolean 
        * [`Prefix`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedupstreamheaderstoappend): string 
        * [`SafeRegex`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedupstreamheaderstoappend): string 
        * [`Suffix`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedupstreamheaderstoappend): string 
      * [`AllowedClientHeaders`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedclientheaders): list
        * [`Contains`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedclientheaders): string 
        * [`Exact`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedclientheaders): string 
        * [`IgnoreCase`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedclientheaders): boolean 
        * [`Prefix`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedclientheaders): string 
        * [`SafeRegex`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedclientheaders): string 
        * [`Suffix`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedclientheaders): string 
      * [`AllowedClientHeadersOnSuccess`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedclientheadersonsuccess): list
        * [`Contains`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedclientheadersonsuccess): string 
        * [`Exact`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedclientheadersonsuccess): string 
        * [`IgnoreCase`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedclientheadersonsuccess): boolean 
        * [`Prefix`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedclientheadersonsuccess): string 
        * [`SafeRegex`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedclientheadersonsuccess): string 
        * [`Suffix`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-allowedclientheadersonsuccess): string 
      * [`DynamicMetadataFromHeaders`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-dynamicmetadatafromheaders): list
        * [`Contains`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-dynamicmetadatafromheaders): string 
        * [`Exact`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-dynamicmetadatafromheaders): string 
        * [`IgnoreCase`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-dynamicmetadatafromheaders): boolean 
        * [`Prefix`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-dynamicmetadatafromheaders): string 
        * [`SafeRegex`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-dynamicmetadatafromheaders): string 
        * [`Suffix`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-httpservice-authorizationresponse-dynamicmetadatafromheaders): string 
  * [`IncludePeerCertificate`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-includepeercertificate): boolean | `false`
  * [`MetadataContextNamespaces`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-metadatacontextnamespaces): list of strings | HTTP only
  * [`StatusOnError`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-statusonerror): number | `403` | HTTP only
  * [`StatPrefix`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-statprefix): string | `response`
  * [`WithRequestBody`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-withrequestbody): map | HTTP only
    * [`MaxRequestBytes`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-withrequestbody-maxrequestbytes): number
    * [`AllowPartialMessage`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-withrequestbody-allowpartialmessage): boolean | `false`
    * [`PackAsBytes`](/consul/docs/reference/proxy/extensions/ext-authz#arguments-config-withrequestbody-packasbytes): boolean | `false`

전체 구성 (Complete configuration)

모든 필드가 정의되면 ext-authz 구성은 다음과 같은 형식이 됩니다.

Name = "builtin/ext-authz" 
Arguments = {
   ProxyType = "connect-proxy" // or "api-gateway" (Enterprise-only)
   InsertOptions = {
      Location = "<location in the filter chain>" 
      FilterName = "<filter relative to the location>"
   }
   Config = {
      BootstrapMetadataLabelsKey = "<key from bootstrap metadata>"
      ClearRouteCache = false // HTTP only
      AllowedHeaders = [
        {
          Exact = "<only forward client request headers with this exact name to the authorization service>"
        }
      ]
      DisallowedHeaders = [
        {
          Exact = "<never forward client request headers with this exact name to the authorization service>"
        }
      ]
      GrpcService = {
         Target = {
            Service = {
               Name = "<upstream service to send gRPC authorization requests to>"
               Namespace = "<namespace containing the upstream service>"
               Partition = "<partition containing the upstream service>"
            URI = "<URI of the upstream service>"   
            Timeout = "1s"
         Authority = "<authority header to send in the gRPC request>"     
         InitialMetadata = [
            "<Key>" : "<value>"  
      HttpService = {
         Target = {
            Service = {
               Name = "<upstream service to send gRPC authorization requests to>"
               Namespace = "<namespace containing the upstream service>"
               Partition = "<partition containing the upstream service>"
            URI = "<URI of the upstream service>"   
            Timeout = "1s"
            }
         }
         PathPrefix = "/<authorization-request-header-prefix>/"    
         AuthorizationRequest = {
            AllowedHeaders = [
               Contains = "<client request headers must contain this value>",   
               Exact = "<client request headers can only be this value>",   
               IgnoreCase = false,  
               Prefix = "<client request headers must begin with this value>",   
               SafeRegex = "<client request headers can match this regex pattern>"
            ]   
            HeadersToAdd = [ 
               "<header key>" = "<header value>"
            ]
         }  
         AuthorizationResponse = {
            AllowedUpstreamHeaders = [
               Contains = "<authorization response headers must contain this value>",   
               Exact = "<authorization response headers can only be this value>",   
               IgnoreCase = false,  
               Prefix = "<authorization response headers must begin with this value>",   
               SafeRegex = "<authorization response headers can match this regex pattern>"
               Suffix = "<authorization response headers must end with this value>"
            ]   
            AllowedUpstreamHeadersToAppend = [
               Contains = "<authorization response headers must contain this value>",   
               Exact = "<authorization response headers can only be this value>",   
               IgnoreCase = false,  
               Prefix = "<authorization response headers must begin with this value>",   
               SafeRegex = "<authorization response headers can match this regex pattern>"
               Suffix = "<authorization response headers must end with this value>"   
             ]   
            AllowedClientHeaders = [
               Contains = "<client response headers must contain this value>",   
               Exact = "<client response headers can only be this value>",   
               IgnoreCase = false,  
               Prefix = "<client response headers must begin with this value>",   
               SafeRegex = "<client response headers can match this regex pattern>"
               Suffix = "<client response headers must end with the value>"
            ]   
            AllowedClientHeadersOnSuccess = [
               Contains = "<client response headers must contain this value>",   
               Exact = "<client response headers can only be this value>",   
               IgnoreCase = false,  
               Prefix = "<client response headers must begin with this value>",   
               SafeRegex = "<client response headers can match this regex pattern>"
               Suffix = "<client response headers must end with the value>"
            DynamicMetadataFromHeaders = [
               Contains = "<authorization response headers must contain this value>",   
               Exact = "<authorization response headers can only be this value>",   
               IgnoreCase = false,  
               Prefix = "<authorization response headers must begin with this value>",   
               SafeRegex = "<authorization response headers can match this regex pattern>"
               Suffix = "<authorization response headers must end with the value>"
            ]
      IncludePeerCertificate = false
      MetadataContextNamespaces = [ 
         "<metadata namespace>"
      ]
      StatusOnError = 403 // HTTP only
      StatPrefix = "response"
      WithRequestBody = {   //HTTP only
         MaxRequestBytes = <uint32 value specifying the max size of the message body>  
         AllowPartialMessage = false
         PackAsBytes = false

사양 (Specification)

이 섹션은 외부 인증 확장에 대해 구성할 수 있는 필드에 대한 세부 정보를 제공합니다.

`Name`

확장의 이름을 지정합니다. builtin/ext-authz로 설정해야 합니다.

값 (Values)

기본값: 없음
이 필드는 필수입니다.
데이터 유형: builtin/ext-authz로 설정된 문자열 값.

`Arguments`

확장에 대한 전역 구성을 포함합니다.

값 (Values)

기본값: 없음
이 필드는 필수입니다.
데이터 유형: 맵

`Arguments.ProxyType`

이 확장이 적용되는 Envoy 프록시의 유형을 지정합니다. 확장은 이 유형과 일치하는 프록시에만 적용되며 다른 모든 프록시 유형에는 무시됩니다. 지원 값은 connect-proxy이며 Consul Enterprise에서는 api-gateway입니다.

api-gateway로 설정하면 Consul은 API 게이트웨이가 업스트림 서비스로 라우팅하는 요청에 외부 인증을 적용합니다.

Enterprise

api-gateway 프록시 유형 지원은 Consul Enterprise 2.0.2에서 도입되었습니다. api-gateway 프록시 유형은 또한 Target.URI의 localhost 제한을 완화하여 인증 서비스가 원격 호스트에서 실행될 수 있게 합니다. 사용 정보는 API 게이트웨이 인증을 외부 서비스로 위임을 참조하세요.

값 (Values)

기본값: connect-proxy
이 필드는 필수입니다.
데이터 유형은 다음 문자열 값 중 하나입니다:
- connect-proxy
- api-gateway

Enterprise

`Arguments.ListenerType`

확장이 적용되는 리스너의 유형을 지정합니다. 리스너 유형은 inbound 또는 outbound입니다. 리스너 유형이 inbound로 설정되면 Consul은 메시의 다른 서비스가 프록시에 연결된 서비스로 메시지를 보낼 때 외부 인증이 활성화되도록 확장을 적용합니다. 리스너 유형이 outbound로 설정되면 Consul은 연결된 프록시가 메시의 다른 서비스로 메시지를 보낼 때 외부 인증이 활성화되도록 확장을 적용합니다.

값 (Values)

기본값: inbound
이 필드는 필수입니다.
데이터 유형은 다음 문자열 값 중 하나입니다:
- inbound
- outbound

`Arguments.InsertOptions`

Envoy 필터 체인에서 외부 인증 필터의 삽입 지점을 정의하는 옵션을 지정합니다. 기본적으로 외부 인증 필터는 Location 필드의 기본 설정에 따라 필터 체인의 첫 번째 필터로 삽입됩니다.

값 (Values)

기본값: 없음
데이터 유형: 맵

`Arguments.InsertOptions.Location`

Envoy 필터 체인에서 외부 인증 필터의 삽입 지점을 지정합니다. 다음 문자열 값 중 하나를 지정할 수 있습니다:

First: FilterName 필드에 지정된 필터와 관계없이 필터를 필터 체인의 첫 번째 필터로 삽입합니다.
BeforeLast: FilterName 필드에 지정된 필터와 관계없이 필터를 체인의 마지막 필터 앞에 삽입합니다. 이는 필터가 다른 모든 필터 뒤에, 그리고 터미널 필터 바로 앞에 삽입되도록 합니다.
AfterFirstMatch: FilterName 필드의 값과 이름이 일치하는 체인의 첫 번째 필터 뒤에 필터를 삽입합니다.
AfterLastMatch: FilterName 필드의 값과 이름이 일치하는 체인의 마지막 필터 뒤에 필터를 삽입합니다.
BeforeFirstMatch: FilterName 필드의 값과 이름이 일치하는 체인의 첫 번째 필터 앞에 필터를 삽입합니다.
BeforeLastMatch: FilterName 필드의 값과 이름이 일치하는 체인의 마지막 필터 앞에 필터를 삽입합니다.

값 (Values)

기본값: BeforeFirstMatch
데이터 유형: 문자열

`Arguments.InsertOptions.FilterName`

외부 인증 필터를 삽입할 때 일치시킬 체인의 기존 필터 이름을 지정합니다. 필터 이름을 지정하면 체인의 다른 필터 위치를 기준으로 삽입 지점을 구성할 수 있습니다.

값 (Values)

기본값: TCP 서비스의 경우 envoy.filters.network.tcp_proxy. HTTP 서비스의 경우 envoy.filters.http.router.
데이터 유형: 문자열

`Arguments.Config`

확장에 대한 구성 설정을 포함합니다.

값 (Values)

기본값: 없음
이 필드는 필수입니다.
데이터 유형: 맵

`Arguments.Config.BootstrapMetadataLabelsKey`

Envoy 부트스트랩 메타데이터의 키를 지정합니다. Envoy는 키와 연결된 라벨을 인증 요청 컨텍스트에 추가합니다.

값 (Values)

기본값: 없음
데이터 유형: 문자열

`Arguments.Config.ClearRouteCache`

Envoy가 라우트 캐시를 지우도록 지시하여 외부 인증 서비스가 라우팅 결정에 올바르게 영향을 미치도록 합니다. true로 설정하면 필터가 모든 캐시된 라우트를 지웁니다.

Envoy는 또한 인증 서비스에서 반환된 상태가 HTTP 응답의 경우 200이거나 gRPC 응답의 경우 0이면 캐시된 라우트를 지웁니다. Envoy는 또한 적어도 하나의 인증 응답 헤더가 클라이언트 요청에 추가되거나 다른 클라이언트 요청 헤더를 변경하는 데 사용되면 캐시된 라우트를 지웁니다.

값 (Values)

기본값: false
데이터 유형: boolean

`Arguments.Config.AllowedHeaders`

Envoy가 검사(check) 요청에서 외부 인증 서비스로 전달하는 클라이언트 요청 헤더를 제한합니다. 설정하면 이름이 구성된 문자열 매처 중 하나와 일치하는 클라이언트 요청 헤더만 인증 서비스로 전송됩니다. 이 필드는 gRPC 및 HTTP 전송 모두에 적용됩니다.

설정하지 않으면 Envoy는 기본 동작을 유지합니다. 모든 클라이언트 요청 헤더가 gRPC 인증 서비스로 전송되는 반면 HTTP 인증 서비스에는 작은 기본 집합(및 HttpService.AuthorizationRequest.AllowedHeaders)만 전송됩니다. 이 필드는 gRPC 인증 서비스로 전송되는 요청 헤더를 제한하는 유일한 방법입니다.

값 (Values)

기본값: 없음
데이터 유형: 문자열 매처 목록

`Arguments.Config.DisallowedHeaders`

Envoy가 나열된 클라이언트 요청 헤더를 외부 인증 서비스로 전달하지 못하게 합니다. 이름이 구성된 문자열 매처 중 하나와 일치하는 클라이언트 요청 헤더는 AllowedHeaders와도 일치하더라도 인증 서비스로 절대 전송되지 않습니다. 이 필드는 gRPC 및 HTTP 전송 모두에 적용되며 헤더가 둘 다 일치할 때 AllowedHeaders보다 우선합니다.

값 (Values)

기본값: 없음
데이터 유형: 문자열 매처 목록

문자열 매처 구성 (String matcher configuration)

AllowedHeaders와 DisallowedHeaders의 각 항목은 다음 필드 중 정확히 하나를 사용하여 클라이언트 요청 헤더 이름을 일치시킵니다:

매개변수 (Parameter)	설명 (Description)	데이터 유형	기본값
`Contains`	헤더 이름이 이 부분 문자열을 포함하면 일치합니다.	문자열	없음
`Exact`	헤더 이름이 이 값과 정확히 같으면 일치합니다.	문자열	없음
`Prefix`	헤더 이름이 이 값으로 시작하면 일치합니다.	문자열	없음
`SafeRegex`	헤더 이름이 이 RE2 정규 표현식과 일치하면 일치합니다.	문자열	없음
`Suffix`	헤더 이름이 이 값으로 끝나면 일치합니다.	문자열	없음
`IgnoreCase`	`true`이면 일치를 대소문자 구분 없이 수행합니다.	boolean	`false`

`Arguments.Config.GrpcService`

gRPC 요청에 대한 외부 인증 구성을 지정합니다. GrpcService 또는 HttpService 설정을 구성하되 둘 다 구성하지는 마세요.

값 (Values)

기본값: 없음
GrpcService 또는 HttpService 구성 중 하나가 필요합니다.
데이터 유형: 맵

`Arguments.Config.GrpcService.Target`

gRPC 인증 요청을 보낼 서비스를 지정하는 구성입니다. Target 필드는 다음 필드를 포함할 수 있습니다:

Service 또는 Uri
Timeout

값 (Values)

기본값: 없음
이 필드는 필수입니다.
데이터 유형: 맵

`Arguments{}.Config{}.GrpcService{}.Target{}.Service{}`

업스트림 외부 인증 서비스를 지정합니다. 인증 요청이 서비스 메시 내의 업스트림 서비스로 전송될 때 이 필드를 구성하세요. 서비스는 필터가 적용되는 서비스의 업스트림으로 구성되어야 합니다.

Service 필드 또는 Uri 필드를 구성하되 둘 다 구성하지는 마세요.

값 (Values)

기본값: 없음
이 필드 또는 Uri가 필요합니다.
데이터 유형: 맵

다음 표는 Service 필드의 매개변수를 구성하는 방법을 설명합니다:

매개변수 (Parameter)	설명 (Description)	데이터 유형	기본값
`Name`	업스트림 서비스의 이름을 지정합니다.	문자열	없음
`Namespace`	Enterprise 업스트림 서비스가 속한 Consul 네임스페이스를 지정합니다.	문자열	`default`
`Partition`	Enterprise 업스트림 서비스가 속한 Consul admin 파티션을 지정합니다.	문자열	`default`

`Arguments.Config.GrpcService.Target.Uri`

외부 인증 서비스의 URI를 지정합니다. 외부 인증 서비스에 명시적 URI를 제공해야 할 때, 예를 들어 인증 서비스가 같은 호스트나 포드에서 실행되는 경우에 이 필드를 구성하세요. ProxyType이 connect-proxy일 때 이 필드의 값은 localhost:<port>, 127.0.0.1:<port>, 또는 ::1:<port> 중 하나여야 합니다. ProxyType이 api-gateway일 때 이 제한은 완화되며 URI가 원격 호스트를 가리킬 수 있습니다.

Enterprise

Uri 필드 또는 Service 필드를 구성하되 둘 다 구성하지는 마세요.

값 (Values)

기본값: 없음
이 필드 또는 Service가 필요합니다.
데이터 유형: 문자열

`Arguments.Config.GrpcService.Target.Timeout`

요청 시 응답이 도착하는 데 걸릴 수 있는 최대 시간을 지정합니다.

값 (Values)

기본값: 1s
데이터 유형: 문자열

`Arguments.Config.GrpcService.Authority`

gRPC 요청에서 보낼 authority 헤더를 지정합니다. 이 필드가 설정되지 않으면 authority 필드는 클러스터 이름으로 설정됩니다. 이 필드는 Envoy가 외부 인증 서비스로 보내는 SNI를 재정의하지 않습니다.

값 (Values)

기본값: 클러스터 이름
데이터 유형: 문자열

`Arguments.Config.GrpcService.InitialMetadata[]`

GrpcService에 시작된 스트림에 포함할 추가 메타데이터를 지정합니다. 예를 들어 x-foo-bar: baz-key와 같은 추가 임시 인증 헤더를 주입하기 위한 메타데이터를 지정할 수 있습니다. 헤더 값 구문에 대한 세부 정보를 포함한 자세한 내용은 사용자 정의 요청 헤더에 대한 Envoy 문서를 참조하세요.

값 (Values)

기본값: 없음
데이터 유형: 하나 이상의 키-값 쌍 목록:
- KEY: 문자열
- VALUE: 문자열

`Arguments{}.Config{}.HttpService{}`

필터와 외부 인증 서비스 간의 원시 HTTP 통신에 대한 구성을 포함합니다. HttpService 또는 GrpcService 설정을 구성하되 둘 다 구성하지는 마세요.

값 (Values)

기본값: 없음
HttpService 또는 GrpcService 구성 중 하나가 필요합니다.
데이터 유형: 맵

`Arguments{}.Config{}.HttpService{}.Target{}`

HTTP 인증 요청을 보낼 서비스를 지정하는 구성입니다. Target 필드는 다음 필드를 포함할 수 있습니다:

Service 또는 Uri
Timeout

값 (Values)

기본값: 없음
이 필드는 필수입니다.
데이터 유형: 맵

`Arguments{}.Config{}.HttpService{}.Target{}.Service{}`

업스트림 외부 인증 서비스를 지정합니다. HTTP 인증 요청이 서비스 메시 내의 업스트림 서비스로 전송될 때 이 필드를 구성하세요. 서비스는 필터가 적용되는 서비스의 업스트림으로 구성되어야 합니다.

Service 필드 또는 Uri 필드를 구성하되 둘 다 구성하지는 마세요.

값 (Values)

기본값: 없음
이 필드 또는 Uri가 필요합니다.
데이터 유형: 맵

다음 표는 Service 필드의 매개변수를 구성하는 방법을 설명합니다:

매개변수 (Parameter)	설명 (Description)	데이터 유형	기본값
`Name`	업스트림 서비스의 이름을 지정합니다.	문자열	없음
`Namespace`	Enterprise 업스트림 서비스가 속한 Consul 네임스페이스를 지정합니다.	문자열	`default`
`Partition`	Enterprise 업스트림 서비스가 속한 Consul admin 파티션을 지정합니다.	문자열	`default`

`Arguments{}.Config{}.HttpService{}.Target{}.Uri`

Enterprise

Uri 필드 또는 Service 필드를 구성하되 둘 다 구성하지는 마세요.

값 (Values)

기본값: 없음
이 필드 또는 Service가 필요합니다.
데이터 유형: 문자열

`Arguments{}.Config{}.HttpService{}.Target{}.Timeout`

요청 시 응답이 도착하는 데 걸릴 수 있는 최대 시간을 지정합니다.

값 (Values)

기본값: 1s
데이터 유형: 문자열

`Arguments{}.Config{}.HttpService{}.PathPrefix`

인증 요청 헤더 Path의 값에 대한 접두사를 지정합니다. 앞에 오는 슬래시(/)를 포함해야 합니다.

값 (Values)

기본값: 없음
데이터 유형: 문자열

`Arguments{}.Config{}.HttpService{}.AuthorizationRequest{}`

HTTP 인증 요청 메타데이터를 제어하는 HTTP 전용 구성입니다. AuthorizationRequest 필드는 다음 매개변수를 포함할 수 있습니다:

값 (Values)

기본값: 없음
데이터 유형: 맵

`Arguments{}.Config{}.HttpService{}.AuthorizationRequest{}.AllowHeaders[]`

클라이언트 요청 헤더를 일치시키기 위한 규칙 집합을 지정합니다. 규칙 중 하나라도 충족하는 클라이언트 요청 헤더는 외부 인증 서비스에 대한 요청에 포함됩니다. 자세한 설명은 Envoy 문서를 참조하세요.

값 (Values)

기본값: 없음
데이터 유형: 키-값 쌍 목록

다음 표는 AllowHeaders 필드에서 구성할 수 있는 일치 규칙을 설명합니다:

규칙 (Rule)	설명 (Description)	데이터 유형	기본값
`Contains`	입력 문자열이 포함해야 하는 문자열을 지정합니다.	문자열	N/A
`Exact`	입력 문자열이 정확히 일치해야 하는 문자열을 지정합니다.	문자열	N/A
`IgnoreCase`	Envoy가 대소문자를 무시하도록 지시합니다. `true`로 설정하면 구성의 다른 일치 규칙은 대소문자를 구분하지 않습니다. 이 규칙은 `SafeRegex`에는 영향을 주지 않습니다.	boolean	`false`
`Prefix`	입력 문자열이 시작해야 하는 문자열을 지정합니다.	문자열	N/A
`SafeRegex`	입력 문자열을 프로그래밍 방식으로 일치시키기 위한 정규 표현식을 지정합니다. Envoy는 Google의 RE2 regex 엔진을 지원합니다.	문자열	N/A
`Suffix`	입력 문자열이 끝나야 하는 문자열을 지정합니다.	문자열	N/A

`Arguments{}.Config{}.HttpService{}.AuthorizationRequest{}.HeadersToAdd[]`

인증 서비스에 대한 요청에 포함할 헤더 목록을 지정합니다. Envoy는 같은 키를 가진 클라이언트 요청 헤더를 덮어씁니다.

값 (Values)

기본값: 없음
데이터 유형: 하나 이상의 키-값 쌍 목록:
- KEY: 문자열
- VALUE: 문자열

`Arguments{}.Config{}.HttpService{}.AuthorizationResponse{}`

HTTP 인증 응답 메타데이터를 제어하는 HTTP 전용 구성입니다. AuthorizationResponse 필드는 다음 매개변수를 포함할 수 있습니다:

값 (Values)

기본값: 없음
데이터 유형: 맵

`Arguments{}.Config{}.HttpService{}.AuthorizationResponse{}.AllowedUpstreamHeaders[]`

인증 응답 헤더를 일치시키기 위한 규칙 집합을 지정합니다. Envoy는 규칙을 충족하는 외부 인증 서비스의 헤더를 클라이언트 응답에 추가합니다. Envoy는 기존 헤더를 덮어씁니다.

값 (Values)

기본값: 없음
데이터 유형: 맵

다음 표는 AllowedUpstreamHeaders 필드에서 구성할 수 있는 일치 규칙을 설명합니다:

규칙 (Rule)	설명 (Description)	데이터 유형	기본값
`Contains`	입력 문자열이 포함해야 하는 문자열을 지정합니다.	문자열	N/A
`Exact`	입력 문자열이 정확히 일치해야 하는 문자열을 지정합니다.	문자열	N/A
`IgnoreCase`	Envoy가 대소문자를 무시하도록 지시합니다. `true`로 설정하면 구성의 다른 일치 규칙은 대소문자를 구분하지 않습니다. 이 규칙은 `SafeRegex`에는 영향을 주지 않습니다.	boolean	`false`
`Prefix`	입력 문자열이 시작해야 하는 문자열을 지정합니다.	문자열	N/A
`SafeRegex`	입력 문자열을 프로그래밍 방식으로 일치시키기 위한 정규 표현식을 지정합니다. Envoy는 Google의 RE2 regex 엔진을 지원합니다.	문자열	N/A
`Suffix`	입력 문자열이 끝나야 하는 문자열을 지정합니다.	문자열	N/A

`Arguments{}.Config{}.HttpService{}.AuthorizationResponse{}.AllowedUpstreamHeadersToAppend[]`

인증 응답 헤더를 일치시키기 위한 규칙 집합을 지정합니다. Envoy는 규칙을 충족하는 외부 인증 서비스의 헤더를 클라이언트 응답에 추가합니다. Envoy는 기존 헤더를 추가합니다.

값 (Values)

기본값: 없음
데이터 유형: 맵

다음 표는 AllowedUpstreamHeadersToAppend 필드에서 구성할 수 있는 일치 규칙을 설명합니다:

규칙 (Rule)	설명 (Description)	데이터 유형	기본값
`Contains`	입력 문자열이 포함해야 하는 문자열을 지정합니다.	문자열	N/A
`Exact`	입력 문자열이 정확히 일치해야 하는 문자열을 지정합니다.	문자열	N/A
`IgnoreCase`	Envoy가 대소문자를 무시하도록 지시합니다. `true`로 설정하면 구성의 다른 일치 규칙은 대소문자를 구분하지 않습니다. 이 규칙은 `SafeRegex`에는 영향을 주지 않습니다.	boolean	`false`
`Prefix`	입력 문자열이 시작해야 하는 문자열을 지정합니다.	문자열	N/A
`SafeRegex`	입력 문자열을 프로그래밍 방식으로 일치시키기 위한 정규 표현식을 지정합니다. Envoy는 Google의 RE2 regex 엔진을 지원합니다.	문자열	N/A
`Suffix`	입력 문자열이 끝나야 하는 문자열을 지정합니다.	문자열	N/A

`Arguments{}.Config{}.HttpService{}.AuthorizationResponse{}.AllowedClientHeaders[]`

클라이언트 응답 헤더를 일치시키기 위한 규칙 집합을 지정합니다. Envoy는 규칙을 충족하는 외부 인증 서비스의 헤더를 클라이언트 응답에 추가합니다. 목록이 설정되지 않으면 Envoy는 Authority (Host)를 제외한 모든 인증 응답 헤더를 포함합니다. 헤더가 이 목록에 포함되면 Envoy는 자동으로 다음 헤더를 추가합니다:

값 (Values)

기본값: 없음
데이터 유형: 맵

다음 표는 AllowedClientHeaders 필드에서 구성할 수 있는 일치 규칙을 설명합니다:

규칙 (Rule)	설명 (Description)	데이터 유형	기본값
`Contains`	입력 문자열이 포함해야 하는 문자열을 지정합니다.	문자열	N/A
`Exact`	입력 문자열이 정확히 일치해야 하는 문자열을 지정합니다.	문자열	N/A
`IgnoreCase`	Envoy가 대소문자를 무시하도록 지시합니다. `true`로 설정하면 구성의 다른 일치 규칙은 대소문자를 구분하지 않습니다. 이 규칙은 `SafeRegex`에는 영향을 주지 않습니다.	boolean	`false`
`Prefix`	입력 문자열이 시작해야 하는 문자열을 지정합니다.	문자열	N/A
`SafeRegex`	입력 문자열을 프로그래밍 방식으로 일치시키기 위한 정규 표현식을 지정합니다. Envoy는 Google의 RE2 regex 엔진을 지원합니다.	문자열	N/A
`Suffix`	입력 문자열이 끝나야 하는 문자열을 지정합니다.	문자열	N/A

`Arguments{}.Config{}.HttpService{}.AuthorizationResponse{}.AllowedClientHeadersOnSuccess[]`

클라이언트 응답 헤더를 일치시키기 위한 규칙 집합을 지정합니다. Envoy는 헤더가 규칙을 충족하고 인증이 성공하면 외부 인증 서비스의 헤더를 클라이언트 응답에 추가합니다. 헤더가 규칙과 일치하지만 인증이 실패하거나 거부되면 헤더는 추가되지 않습니다. 이 필드가 설정되지 않으면 Envoy는 성공 시 클라이언트 응답에 추가 헤더를 추가하지 않습니다.

값 (Values)

기본값: 없음
데이터 유형: 맵

다음 표는 AllowedClientHeadersOnSuccess 필드에서 구성할 수 있는 일치 규칙을 설명합니다:

규칙 (Rule)	설명 (Description)	데이터 유형	기본값
`Contains`	입력 문자열이 포함해야 하는 문자열을 지정합니다.	문자열	N/A
`Exact`	입력 문자열이 정확히 일치해야 하는 문자열을 지정합니다.	문자열	N/A
`IgnoreCase`	Envoy가 대소문자를 무시하도록 지시합니다. `true`로 설정하면 구성의 다른 일치 규칙은 대소문자를 구분하지 않습니다. 이 규칙은 `SafeRegex`에는 영향을 주지 않습니다.	boolean	`false`
`Prefix`	입력 문자열이 시작해야 하는 문자열을 지정합니다.	문자열	N/A
`SafeRegex`	입력 문자열을 프로그래밍 방식으로 일치시키기 위한 정규 표현식을 지정합니다. Envoy는 Google의 RE2 regex 엔진을 지원합니다.	문자열	N/A
`Suffix`	입력 문자열이 끝나야 하는 문자열을 지정합니다.	문자열	N/A

`Arguments{}.Config{}.HttpService{}.AuthorizationResponse{}.DynamicMetadataFromHeaders[]`

인증 응답 헤더를 일치시키기 위한 규칙 집합을 지정합니다. Envoy는 외부 인증 서비스의 헤더를 체인의 다음 필터가 사용할 수 있는 동적 메타데이터로 내보냅니다.

값 (Values)

기본값: 없음
데이터 유형: 맵

다음 표는 DynamicMetadataFromHeaders 필드에서 구성할 수 있는 일치 규칙을 설명합니다:

규칙 (Rule)	설명 (Description)	데이터 유형	기본값
`Contains`	입력 문자열이 포함해야 하는 문자열을 지정합니다.	문자열	N/A
`Exact`	입력 문자열이 정확히 일치해야 하는 문자열을 지정합니다.	문자열	N/A
`IgnoreCase`	Envoy가 대소문자를 무시하도록 지시합니다. `true`로 설정하면 구성의 다른 일치 규칙은 대소문자를 구분하지 않습니다. 이 규칙은 `SafeRegex`에는 영향을 주지 않습니다.	boolean	`false`
`Prefix`	입력 문자열이 시작해야 하는 문자열을 지정합니다.	문자열	N/A
`SafeRegex`	입력 문자열을 프로그래밍 방식으로 일치시키기 위한 정규 표현식을 지정합니다. Envoy는 Google의 RE2 regex 엔진을 지원합니다.	문자열	N/A
`Suffix`	입력 문자열이 끝나야 하는 문자열을 지정합니다.	문자열	N/A

`Arguments{}.Config{}.IncludePeerCertificate`

true로 설정하면 Envoy는 인증서를 사용할 수 있을 때 피어 X.509 인증서를 인증 요청에 포함합니다.

값 (Values)

기본값: false
데이터 유형: boolean

`Arguments{}.Config{}.MetadataContextNamespace[]`

메타데이터 네임스페이스 목록을 지정하는 HTTP 전용 필드입니다. 네임스페이스의 값은 인증 요청 컨텍스트에 포함됩니다. 구성한 네임스페이스 외에 consul 네임스페이스가 항상 포함됩니다.

값 (Values)

기본값: ["consul"]
데이터 유형: 문자열 값 목록

`Arguments{}.Config{}.StatusOnError`

오류 시 응답할 반환 코드 상태를 지정하는 HTTP 전용 필드입니다. 추가 정보는 Envoy 문서를 참조하세요.

값 (Values)

기본값: 403
데이터 유형: 정수

`Arguments{}.Config{}.StatPrefix`

통계를 쓸 때 추가할 접두사를 지정합니다.

값 (Values)

기본값: response
데이터 유형: 문자열

`Arguments{}.Config{}.WithRequestBody{}`

Envoy가 클라이언트 요청 본문을 버퍼링하고 인증 요청과 함께 보내도록 구성하는 HTTP 전용 필드입니다. 설정하지 않으면 요청 본문은 인증 요청과 함께 전송되지 않습니다.

값 (Values)

기본값: 없음
데이터 유형: 맵

다음 표는 WithRequestBody 필드에 포함할 수 있는 매개변수를 설명합니다:

매개변수 (Parameter)	설명 (Description)	데이터 유형	기본값
`MaxRequestBytes`	필터가 메모리에 보관하는 메시지 본문의 최대 크기를 지정합니다. `AllowPartialMessage`가 `true`로 설정되지 않는 한 버퍼가 이 필드에 설정된 수에 도달하면 Envoy는 HTTP `403`을 반환하고 인증 프로세스를 시작하지 않습니다.	uint32	없음
`AllowPartialMessage`	`true`로 설정하면 Envoy는 `MaxRequestBytes` 값에 도달할 때까지 요청 본문을 버퍼링합니다. 인증 요청은 부분 본문으로 전달되며 필터에 의해 `413` HTTP 오류가 반환되지 않습니다.	boolean	`false`
`PackAsBytes`	`true`로 설정하면 Envoy는 요청 본문을 원시 바이트로 외부 인증에 보냅니다. 그렇지 않으면 Envoy는 요청 본문을 UTF-8 인코딩 문자열로 보냅니다.	boolean	`false`

예제 (Examples)

다음 예제는 특정 사용 사례에 대한 일반적인 구성 패턴을 보여줍니다.

URI에 대한 gRPC 요청 인증 (Authorize gRPC requests to a URI)

다음 예제에서 서비스 기본값 구성 항목에는 ext-authz 구성이 포함됩니다. 이 구성은 api 서비스가 localhost:9191의 서비스에 gRPC 인증 요청을 하도록 허용합니다:

Kind = "service-defaults"
Name = "api"
EnvoyExtensions = [
  {
    Name = "builtin/ext-authz"
    Arguments = {
      ProxyType = "connect-proxy"
      Config = {
        GrpcService = {
          Target = {
            URI = "127.0.0.1:9191"
          }
        }
      }
    }
  }
]

업스트림 인증 (Upstream authorization)

다음 예제에서 서비스 기본값 구성 항목에는 ext-authz 구성이 포함됩니다. 이 구성은 api 서비스가 authz라는 서비스에 gRPC 인증 요청을 하도록 허용합니다:

Kind = "service-defaults"
Name = "api"
EnvoyExtensions = [
  {
    Name = "builtin/ext-authz"
    Arguments = {
      ProxyType = "connect-proxy"
      Config = {
        GrpcService = {
          Target = {
            Service = {
              Name = "authz"
            }
          }
        }
      }
    }
  }
]

Consul Enterprise용 서비스 의도 이후 인증 요청 (Authorization requests after service intentions for Consul Enterprise)

Consul Enterprise의 다음 예제에서 api 서비스는 foo 네임스페이스와 bar 파티션의 authz라는 서비스에 HTTP 인증 요청을 하도록 구성됩니다. Envoy는 또한 envoy.filters.http.rbac 필터 뒤에 외부 인증 필터를 삽입합니다:

Kind = "service-defaults"
Name = "api"
Protocol = "http"
EnvoyExtensions = [
  {
    Name = "builtin/ext-authz"
    Arguments = {
      ProxyType = "connect-proxy"
      InsertOptions = {
        Location   = "AfterLastMatch"
        FilterName = "envoy.filters.http.rbac"
      }
      Config = {
        HttpService = {
          Target = {
            Service = {
              Name      = "authz"
              Namespace = "foo"
              Partition = "bar"
            }
          }
        }
      }
    }
  }
]

원격 인증 서비스에 대한 API 게이트웨이 요청 인증 (Authorize API gateway requests to a remote authorization service)

Enterprise

외부 인증 확장을 API 게이트웨이에 적용하려면 Consul Enterprise 2.0.2 이상이 필요합니다.

Consul Enterprise의 다음 예제에서 서비스 기본값 구성 항목은 확장을 api-gateway라는 API 게이트웨이에 적용합니다. ProxyType이 api-gateway이므로 Target.URI가 원격 인증 서비스를 가리킬 수 있습니다. 이 구성은 또한 Envoy가 인증 서비스로 전달하는 클라이언트 요청 헤더를 제한합니다:

Kind = "service-defaults"
Name = "api-gateway"
Protocol = "http"
EnvoyExtensions = [
  {
    Name = "builtin/ext-authz"
    Arguments = {
      ProxyType = "api-gateway"
      Config = {
        GrpcService = {
          Target = {
            URI = "authz.example.com:9191"
          }
        }
        AllowedHeaders = [
          {
            Prefix = "x-"
          }
        ]
        DisallowedHeaders = [
          {
            Exact      = "authorization"
            IgnoreCase = true
          }
        ]
      }
    }
  }
]

게이트웨이 전체 및 라우트별 인증 동작을 설정하는 방법을 포함한 전체 워크플로는 가상 머신에서 외부 서비스로 API 게이트웨이 인증 위임 및 Kubernetes에서 외부 서비스로 API 게이트웨이 인증 위임을 참조하세요.