5장. APIcast 정책

3scale Auth Caching 정책은 APIcast에 대한 인증 호출을 캐시합니다. 운영 모드를 선택하여 캐시 작업을 구성할 수 있습니다.

3scale Auth Caching은 다음 모드에서 사용할 수 있습니다.

1. strict - 권한 있는 호출만 캐시합니다.

"제한" 모드는 권한 있는 호출만 캐시합니다. 정책이 "제한" 모드에서 실행되고 호출이 실패하거나 거부되면 정책이 캐시 항목을 무효화합니다. 백엔드에 연결할 수 없게 되면 캐시된 모든 호출이 해당 캐시된 상태와 관계없이 거부됩니다.

2. 복원력 - 백엔드가 다운될 때 마지막 요청에 따라 승인합니다.

"Resilient" 모드는 권한 및 거부된 호출을 모두 캐시합니다. 정책이 "resilient" 모드에서 실행 중인 경우 실패한 호출은 기존 캐시 항목을 무효화하지 않습니다. 백엔드에 연결할 수 없는 경우 호출이 캐시된 상태에 따라 캐시를 계속 인증하거나 거부합니다.

3. allow - 백엔드가 다운되면 이전에 보거나 거부하지 않는 한 모든 항목을 허용하십시오.

"Allow" 모드는 권한 및 거부된 호출을 모두 캐시합니다. 정책이 "허용" 모드에서 실행 중인 경우 캐시된 호출은 캐시된 상태에 따라 계속 거부되거나 허용됩니다. 그러나 새 호출은 인증된 대로 캐시됩니다.

4. none - 캐싱을 비활성화합니다.

"None" 모드는 캐싱을 비활성화합니다. 이 모드는 정책이 활성 상태로 유지되지만 캐싱을 사용하지 않으려는 경우 유용합니다.

구성 속성

정책 오브젝트 예

{
  "name": "caching",
  "version": "builtin",
  "configuration": {
    "caching_type": "allow"
  }
}

정책을 구성하는 방법에 대한 자세한 내용은 문서의 정책 체인 생성 섹션을 참조하십시오.

3scale Batcher 정책은 표준 APIcast 인증 메커니즘에 대한 대안을 제공합니다. 이 메커니즘은 3scale 백엔드(Service Management API)에 대한 호출이 각 API 요청 APIcast 수신에 대해 이루어집니다.

3scale Batcher 정책은 3scale 백엔드에 대한 요청 수를 크게 줄여 대기 시간을 줄이고 처리량을 증가시킵니다. 이를 위해 이 정책은 권한 부여 상태를 캐시하고 사용 보고서를 일괄 처리합니다.

3scale Batcher 정책이 활성화되면 APIcast는 다음과 같은 권한 부여 흐름을 사용합니다.

3scale Batcher 정책은 처리량을 개선하지만 정확도가 감소합니다. 사용 제한 및 현재 사용률은 3scale에 저장되며 APIcast는 3scale 백엔드를 호출할 때만 올바른 권한 부여 상태를 가져올 수 있습니다. 3scale Batcher 정책이 활성화되면 APIcast가 3scale로 호출을 보내지 않는 기간이 있습니다. 이 창에서 호출을 수행하는 애플리케이션은 정의된 제한을 초과할 수 있습니다.

처리량이 속도 제한의 정확도보다 더 중요한 경우 높은 로드 API에 이 정책을 사용합니다. 3scale Batcher 정책은 보고 빈도 및 권한 부여 TTL이 속도 제한 기간보다 훨씬 작으면 보다 나은 정확도를 제공합니다. 예를 들어 제한이 일당이고 보고 빈도 및 권한 부여 TTL이 몇 분으로 구성된 경우.

3scale Batcher 정책은 다음 구성 설정을 지원합니다.

익명 액세스 정책은 인증 없이 서비스를 노출합니다. 예를 들어 인증 매개 변수를 전송하도록 조정할 수 없는 레거시 애플리케이션에 유용할 수 있습니다. 익명 정책은 API 키 및 앱 ID / 앱 키 인증 옵션이 있는 서비스만 지원합니다. 제공된 자격 증명이 없는 API 요청에 정책이 활성화되면 APIcast는 정책에 구성된 기본 인증 정보를 사용하여 호출에 권한을 부여합니다. API 호출을 인증하려면 구성된 인증 정보가 있는 애플리케이션이 존재하고 활성 상태여야 합니다.

애플리케이션 계획을 사용하면 기본 자격 증명에 사용된 애플리케이션에서 속도 제한을 구성할 수 있습니다.

다음은 정책에 필요한 구성 속성입니다.

그림 5.1. 익명 액세스 정책

CORS(CrossOrigin Resource Sharing) 요청 처리 정책을 사용하면 다음을 지정할 수 있으므로 CORS 동작을 제어할 수 있습니다.

CORS 요청 처리 정책은 지정되지 않은 모든 CORS 요청을 차단합니다.

구성 속성

정책 오브젝트 예

{
  "name": "cors",
  "version": "builtin",
  "configuration": {
    "allow_headers": [
      "App-Id", "App-Key",
      "Content-Type", "Accept"
    ],
    "allow_credentials": true,
    "allow_methods": [
      "GET", "POST"
    ],
    "allow_origin": "https://example.com"
  }
}

정책을 구성하는 방법에 대한 자세한 내용은 문서의 정책 체인 생성 섹션을 참조하십시오.

echo 정책은 들어오는 요청을 클라이언트에 다시 출력하고 선택적 HTTP 상태 코드를 출력합니다.

구성 속성

정책 오브젝트 예

{
  "name": "echo",
  "version": "builtin",
  "configuration": {
    "status": 404,
    "exit": "request"
  }
}

정책을 구성하는 방법에 대한 자세한 내용은 문서의 정책 체인 생성 섹션을 참조하십시오.

Edge 제한 정책은 백엔드 API로 전송된 트래픽에 유연한 속도 제한을 제공하는 것을 목표로 하며 기본 3scale 권한 부여와 함께 사용할 수 있습니다. 정책에서 지원하는 사용 사례의 몇 가지 예는 다음과 같습니다.

{
  "key": { "name": "{{ jwt.sub }}", "name_type": "liquid" },
  "count": 10,
  "window": 60
}

"condition": {
  "combine_op": "and",
  "operations": [
    {
      "op": "==",
      "right": "GET",
      "left_type": "liquid",
      "left": "{{ http_method }}",
      "right_type": "plain"
    }
  ]
}

헤더 수정 정책을 사용하면 기존 헤더를 수정하거나 추가 헤더를 정의하여 들어오는 요청 또는 응답에서 추가하거나 제거할 수 있습니다. 응답 헤더와 요청 헤더를 모두 수정할 수 있습니다.

헤더 수정 정책은 다음 구성 매개 변수를 지원합니다.

각 작업은 다음 매개 변수로 구성됩니다.

정책 오브젝트 예

{
  "name": "headers",
  "version": "builtin",
  "configuration": {
    "response": [
      {
        "op": "add",
        "header": "Custom-Header",
        "value_type": "plain",
        "value": "any-value"
      }
    ],
    "request": [
      {
        "op": "set",
        "header": "Authorization",
        "value_type": "plain",
        "value": "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
      },
      {
        "op": "set",
        "header": "Service-ID",
        "value_type": "liquid",
        "value": "{{service.id}}"
      }
    ]
  }
}

정책을 구성하는 방법에 대한 자세한 내용은 문서의 정책 체인 생성 섹션을 참조하십시오.

IP 확인 정책은 IP 목록을 기반으로 요청을 거부하거나 허용하는 데 사용됩니다.

구성 속성

정책 오브젝트 예

{
  "name": "ip_check",
  "configuration": {
    "ips": [ "3.4.5.6", "1.2.3.0/4" ],
    "check_type": "blacklist",
    "client_ip_sources": ["X-Forwarded-For", "X-Real-IP", "last_caller"],
    "error_msg": "A custom error message"
  }
}

정책을 구성하는 방법에 대한 자세한 내용은 문서의 정책 체인 생성 섹션을 참조하십시오.

이 정책은 컨텍스트에서 사용할 수 있는 오브젝트와 값이 포함되어 있고 Liquid 템플릿을 평가하는 데 사용할 수 있는 JSON으로 API 요청에 응답합니다. 3scale APIcast 또는 Upstream 정책과 결합할 때 올바르게 작동하기 위해 Liquid Context Debug를 정책 체인에 배치해야합니다. 순환 참조를 피하기 위해 정책에는 중복된 오브젝트만 한 번만 포함되고 stub 값으로 대체됩니다.

정책이 활성화되면 APIcast에서 반환하는 값의 예입니다.

{
  "jwt": {
    "azp": "972f7b4f",
    "iat": 1537538097,
    ...
    "exp": 1537574096,
    "typ": "Bearer"
  },
  "credentials": {
    "app_id": "972f7b4f"
  },
  "usage": {
    "deltas": {
      "hits": 1
    },
    "metrics": [
      "hits"
    ]
  },
  "service": {
    "id": "2",
    ...
  }
  ...
}

로깅 정책을 사용하면 각 API 서비스에 대해 APIcast(NGINX) 액세스 로그를 개별적으로 활성화하거나 비활성화할 수 있습니다. 기본적으로 이 정책은 정책 체인에서 활성화되어 있지 않습니다.

이 정책은 enable_access_logs 구성 매개변수만 지원합니다. 서비스에 대한 액세스 로깅을 비활성화하려면 정책을 활성화하고 enable_access_logs 매개변수를 선택한 후 Submit( Submit ) 버튼을 클릭합니다. 액세스 로그를 활성화하려면 enable_access_logs 매개변수를 선택하거나 Logging 정책을 비활성화합니다.

로깅 정책을 액세스 로그의 위치에 대한 글로벌 설정과 결합할 수 있습니다. APIcast 액세스 로그의 위치를 구성하려면 APICAST_ACCESS_LOG_FILE 환경 변수를 설정합니다. 기본적으로 이 변수는 표준 출력 장치인 /dev/stdout 로 설정됩니다. 글로벌 APIcast 매개변수에 대한 자세한 내용은 ??? 을 참조하십시오.

OAuth 2.0 Token Introspection 정책을 사용하면 토큰 발행자(Red Hat Single Sign-On)의 Token Introspection Endpoint(Red Hat Single Sign-On)를 사용하는 OpenID Connect 인증 옵션과 함께 제공되는 서비스에 사용되는 JSON 웹 토큰(JWT) 토큰을 검증할 수 있습니다.

APIcast는 auth_type 필드에서 다음 인증 유형을 지원하여 Token Introspection Endpoint 및 이 끝점을 호출할 때 사용하는 인증 정보 APIcast를 결정합니다.

auth_type 필드의 설정에 관계없이 APIcast는 기본 인증을 사용하여 토큰 의도를 승인합니다 (Authorization: Basic <token> 헤더, 여기서 < token >은 Base64로 인코딩된 < client_id>:<client_secret > 설정).

Token Introspection Endpoint 응답에는 활성 속성이 포함되어 있습니다. APIcast는 이 속성의 값을 확인합니다. 특성 값에 따라 APIcast는 호출을 승인하거나 거부합니다.

이 정책을 통해 토큰을 캐시하여 동일한 JWT 토큰을 호출할 때마다 Token Introspection Endpoint를 호출하지 않도록 할 수 있습니다. Token Introspection 정책의 토큰 캐싱을 활성화하려면 max_cached_tokens 필드를 0 의 값으로 설정하여 기능을 비활성화 합니다. 또한 max_ttl_tokens 필드의 토큰에 대해 Time to Live (TTL) 값을 1 에서 3600 초로 설정할 수 있습니다.

Referrer 정책은 Referrer Filtering 기능을 활성화합니다. 서비스 정책 체인에서 정책이 활성화되면 APIcast는 참조 매개 변수의 Service Management API (AuthRep 호출)에 향후 요청의 Referer 정책 값을 보냅니다. Referrer Filtering 작동 방법에 대한 자세한 내용은 인증 패턴 의 Referrer Filtering 섹션을 참조하십시오.

이 정책은 OpenID Connect 인증 옵션과 함께 사용할 때 역할 검사를 추가합니다. 이 정책은 Red Hat Single Sign-On에서 발행한 액세스 토큰에서 영역 역할 및 클라이언트 역할을 확인합니다. 영역 역할은 모든 클라이언트의 리소스 또는 3Scale에 역할 검사를 추가할 때 지정됩니다.

다음은 type 속성이 정책 구성에서 지정하는 두 가지 유형의 역할 검사입니다.

동일한 정책에서 블랙리스트 와 허용 목록 인 둘 다 구성할 수는 없지만 APIcast 정책 체인에 RH-SSO/Keycloak 역할 검사 정책의 두 개 이상의 인스턴스를 추가할 수 있습니다.

정책 구성의 scopes 속성을 통해 범위 목록을 구성할 수 있습니다.

각 범위 오브젝트에는 다음 속성이 있습니다.

Prometheus는 독립형 오픈 소스 시스템 모니터링 및 경고 툴킷입니다.

Prometheus 지표 가용성

Prometheus와 APIcast 통합은 다음 배포 옵션에 사용할 수 있습니다.

Prometheus 지표 목록

다음 메트릭을 항상 사용할 수 있습니다.

다음 메트릭은 3scale Batcher 정책을 사용하는 경우에만 사용할 수 있습니다.

값이 없는 메트릭

메트릭에 값이 없는 경우 메트릭이 숨겨집니다. 예를 들어 nginx_error_log 에 보고에 오류가 없으면 nginx_error_log 메트릭이 표시되지 않습니다. 이 값은 값이 있는 경우에만 표시됩니다.

NetNamespace 정책은 정책에 지정된 매핑 규칙을 사용하여 HTTP 요청의 SOAPAction 또는 Content-Type 헤더에 제공된 SOAP 작업 URI와 일치합니다.

구성 속성

정책 오브젝트 예

{
  "name": "soap",
  "version": "builtin",
  "configuration": {
    "mapping_rules": [
      {
        "pattern": "http://example.com/soap#request",
        "metric_system_name": "soap",
        "delta": 1
      }
    ]
  }
}

정책을 구성하는 방법에 대한 자세한 내용은 문서의 정책 체인 생성 섹션을 참조하십시오.

Upstream 정책을 사용하면 정규식을 사용하여 Host 요청 헤더를 구문 분석하고 Private Base URL에 정의된 업스트림 URL을 다른 URL로 교체할 수 있습니다.

예를 들면 다음과 같습니다.

regex /foo. 및 URL 필드 newexample.com 이 포함된 정책에서 URL https://www.example.com/foo/123/ 을 newexample.com으로 교체합니다.

정책 체인 참조:

정책 오브젝트 예

{
  "name": "upstream",
  "version": "builtin",
  "configuration": {
    "rules": [
      {
        "regex": "^/v1/.*",
        "url": "https://api-v1.example.com",

      }
    ]
  }
}

정책을 구성하는 방법에 대한 자세한 내용은 문서의 정책 체인 생성 섹션을 참조하십시오.

URL 재작성 정책을 사용하면 요청 경로와 쿼리 문자열을 수정할 수 있습니다.

3scale APIcast 정책과 결합하면 URL 재작성 정책이 정책 체인의 3scale APIcast 정책 앞에 배치되면 APIcast 매핑 규칙이 수정된 경로에 적용됩니다. URL 재작성 정책이 정책 체인의 APIcast 뒤에 배치되면 매핑 규칙이 원래 경로에 적용됩니다.

이 정책은 다음 두 가지 작업 세트를 지원합니다.

{
  "name": "url_rewriting",
  "version": "builtin",
  "configuration": {
    "query_args_commands": [
      {
        "op": "add",
        "arg": "addarg",
        "value_type": "plain",
        "value": "addvalue"
      },
      {
        "op": "delete",
        "arg": "user_key",
        "value_type": "plain",
        "value": "any"
      },
      {
        "op": "push",
        "arg": "pusharg",
        "value_type": "plain",
        "value": "pushvalue"
      },
      {
        "op": "set",
        "arg": "setarg",
        "value_type": "plain",
        "value": "setvalue"
      }
    ],
    "commands": [
      {
        "op": "sub",
        "regex": "^/api/v\\d+/",
        "replace": "/internal/",
        "options": "i"
      }
    ]
  }

https://api.example.com/api/v1/products/123/details?user_key=abc123secret&pusharg=first&setarg=original

https://api-backend.example.com/internal/products/123/details?pusharg=first&pusharg=pushvalue&setarg=setvalue

Captures 정책을 사용한 URL 재작성 정책은 5.1.17절. “URL 재작성 정책” 정책의 대안이며 API 백엔드에 전달하기 전에 API 요청의 URL을 다시 작성할 수 있습니다.

Captures 정책을 사용하여 URL 재작성은 URL의 인수를 캡처하고 다시 작성된 URL에서 해당 값을 사용합니다.

정책은 transformations 구성 매개 변수를 지원합니다. 요청 URL에 어떤 변환을 적용하는지 설명하는 오브젝트 목록입니다. 각 tranformation 오브젝트는 두 가지 속성으로 구성됩니다.

원래 URL의 쿼리 매개 변수는 템플릿에 지정된 쿼리 매개 변수와 병합됩니다.

예제

Captures를 사용하여 URL 재작성은 다음과 같이 구성됩니다.

{
  "name": "rewrite_url_captures",
  "version": "builtin",
  "configuration": {
    "transformations": [
      {
        "match_rule": "/api/v1/products/{productId}/details",
        "template": "/internal/products/details?id={productId}&extraparam=anyvalue"
      }
    ]
  }
}

APIcast로 전송된 원래 요청 URI입니다.

https://api.example.com/api/v1/products/123/details?user_key=abc123secret

URL 재작성을 적용한 후 APIcast에서 API 백엔드에 전송하는 URI입니다.

https://api-backend.example.com/internal/products/details?user_key=abc123secret&extraparam=anyvalue&id=123