배포 옵션

APIcast는 독립 실행형 API 게이트웨이가 아니며 3scale API Manager에 연결되어 있어야 합니다.

두 경우 모두 APIcast 호스팅 또는 자체 관리를 사용할 수 있습니다. 3scale API 관리 플랫폼의 나머지 부분에 대한 연결이 필요합니다.

기본적으로 3scale 계정을 만들 때 다른 두 환경에 기본 제공 APIcast가 제공됩니다.

[your_API_name] > 통합 > 설정으로 이동합니다.

통합 옵션은 오른쪽 상단에 있는 통합 페이지에 표시됩니다. 기본적으로 배포 옵션은 APIcast 호스팅이며 인증 모드는 API 키입니다. 오른쪽 상단에서 통합 설정 편집을 클릭하여 이러한 설정을 변경할 수 있습니다. OAuth 2.0 인증은 자체 관리 배포에서만 사용할 수 있습니다.

API 백엔드의 끝점 호스트인 Private Base URL 필드에 API 백엔드를 선언해야 합니다. APIcast는 모든 인증, 권한 부여, 속도 제한 및 통계가 처리된 후 모든 트래픽을 API 백엔드로 리디렉션합니다.

일반적으로 API의 프라이빗 기본 URL은 관리하는 도메인의 https://api-backend.yourdomain.com:443 (yourdomain.com)과 같습니다. 예를 들어, Twitter API와 통합하려는 경우 개인 기본 URL은 https://api.twitter.com/ 입니다. 이 예제에서는 3scale에서 호스팅하는 Echo API를 사용합니다 - 모든 경로를 수락하고 요청에 대한 정보를 반환하는 간단한 API (path, 요청 매개변수, 헤더 등). 프라이빗 기본 URL은 https://echo-api.3scale.net:443입니다.

View larger image

프라이빗(관리되지 않음) API가 작동하는지 테스트합니다. 예를 들어, Echo API의 경우 curl 명령을 사용하여 다음 호출을 수행할 수 있습니다.

curl "https://echo-api.3scale.net:443"

curl "https://echo-api.3scale.net:443"

다음과 같은 응답을 받습니다.

{
    "method": "GET",
    "path": "/",
    "args": "",
    "body": "",
    "headers": {
      "HTTP_VERSION": "HTTP/1.1",
      "HTTP_HOST": "echo-api.3scale.net",
      "HTTP_ACCEPT": "*/*",
      "HTTP_USER_AGENT": "curl/7.51.0",
      "HTTP_X_FORWARDED_FOR": "2.139.235.79, 10.0.103.58",
      "HTTP_X_FORWARDED_HOST": "echo-api.3scale.net",
      "HTTP_X_FORWARDED_PORT": "443",
      "HTTP_X_FORWARDED_PROTO": "https",
      "HTTP_FORWARDED": "for=10.0.103.58;host=echo-api.3scale.net;proto=https"
    },
    "uuid": "ee626b70-e928-4cb1-a1a4-348b8e361733"
  }

{
    "method": "GET",
    "path": "/",
    "args": "",
    "body": "",
    "headers": {
      "HTTP_VERSION": "HTTP/1.1",
      "HTTP_HOST": "echo-api.3scale.net",
      "HTTP_ACCEPT": "*/*",
      "HTTP_USER_AGENT": "curl/7.51.0",
      "HTTP_X_FORWARDED_FOR": "2.139.235.79, 10.0.103.58",
      "HTTP_X_FORWARDED_HOST": "echo-api.3scale.net",
      "HTTP_X_FORWARDED_PORT": "443",
      "HTTP_X_FORWARDED_PROTO": "https",
      "HTTP_FORWARDED": "for=10.0.103.58;host=echo-api.3scale.net;proto=https"
    },
    "uuid": "ee626b70-e928-4cb1-a1a4-348b8e361733"
  }

API가 작동하는지 확인한 후 호스팅 스테이징 환경에 대한 테스트 호출을 구성해야 합니다. API test GET request 필드 (예: /v1/word/good.json)에 API에 기존 경로를 입력합니다.

페이지 오른쪽 하단의 Update & Test Staging Configuration 버튼을 클릭하여 설정을 저장합니다. 이렇게 하면 APIcast 구성이 3scale 호스트 스테이징 환경에 배포됩니다. 모든 것이 올바르게 구성되면 왼쪽의 수직선이 녹색으로 전환되어야 합니다.

curl "https://XXX.staging.apicast.io:443/v1/word/good.json?user_key=YOUR_USER_KEY"

curl "https://XXX.staging.apicast.io:443/v1/word/good.json?user_key=YOUR_USER_KEY"

매핑 규칙은 API에 대한 요청에 따라 보고할 지표(및 메서드)를 정의합니다.

기본적으로 매우 간단한 매핑 규칙으로 시작합니다.

View larger image

이 규칙은 / 로 시작하는 모든 GET 요청이 지표 적중 을 1씩 증가시킵니다. 이 매핑 규칙은 API에 대한 모든 요청과 일치합니다. 이 규칙은 너무 일반적이므로 대부분 변경할 가능성이 높습니다.

APIcast는 다음과 같은 방법으로 매개변수를 가져옵니다.

매개 변수의 이름은 와일드카드로 지정될 수도 있습니다. 슬래시 또는 슬래시와 점 사이에 와일드카드가 표시될 수 있습니다.

예를 들어 아래에서 Echo API에 대한 규칙을 확인할 수 있습니다.

View larger image

매핑 규칙은 쿼리 문자열 또는 본문에 대한 매개 변수를 포함할 수도 있습니다. /{word}?value={value}.

규칙 일치는 접두사로 수행되며 임의로 복잡할 수 있습니다. 표기법은 Swagger 및 ActiveDocs 사양을 따릅니다.

이 규칙은 자리 표시자 {word} 의 모든 항목과 일치하므로 /morning 과 같은 요청이 규칙과 일치합니다.

슬래시 또는 슬래시와 점 사이에 와일드카드가 표시될 수 있습니다.

APIcast는 GET인 경우 쿼리 문자열에서 매개 변수를 가져오고 POST, DELETE, PUT일 때 본문에서 매개 변수를 가져옵니다.

매개 변수의 이름은 와일드카드로 지정될 수도 있습니다.

기본적으로 지정한 정렬에 따라 모든 매핑 규칙이 처음부터 마지막까지 평가됩니다. 위의 숫자에 규칙 /v1 을 추가하는 경우 /v1로 시작하는 경로가 /v1로 시작하는 요청과 일치합니다. /v1/word 또는 /v1/sentence.

매핑 규칙을 정의하는 의도된 워크플로우는 다음과 같습니다.

이 워크플로우 외에도 다음 두 가지 기능이 있습니다.

(get) /path/to/example/search
(get) /path/to/example/{id}

(get) /path/to/example/search
(get) /path/to/example/{id}

(get) /path/to/example/search 를 사용하여 호출하면 나머지 매핑 규칙 처리가 중지되고 규칙이 일치하는 후 지표가 증가합니다.

고급 구성 옵션은 APIcast 고급 구성 튜토리얼을 확인할 수 있습니다.

이 옵션은 Host 헤더가 예상한 값과 일치하지 않는 한 트래픽을 거부하는 해당 API 백엔드에만 필요합니다. 이러한 경우, API 백엔드 앞에 게이트웨이를 사용하면 호스트가 게이트웨이 중 하나(예: xxx-yyy.staging.apicast.io)이므로 문제가 발생할 수 있습니다.

이 문제를 방지하려면 인증 설정의 Host Header 필드에 필요한 API 백엔드를 정의할 수 있으며 호스트 APIcast 인스턴스는 호스트를 다시 작성합니다.

View larger image

API 통합을 구성하고 Staging 환경에서 작동하는지 확인하면 APIcast 프로덕션 배포 중 하나를 사용할 수 있습니다. 이 문서의 시작 부분에 있는 배포 옵션을 참조하십시오.

통합 페이지 하단에서 Production 섹션을 찾을 수 있습니다. 여기에서 두 개의 필드를 찾을 수 있습니다. Private Base URL 은 Staging 섹션에서 구성한 것과 동일합니다. 이 URL은 Public Base URL 입니다.

Public Base URL 은 개발자가 API에 요청하는데 사용하는 URL이며 3scale로 보호됩니다. 이 URL은 APIcast 인스턴스의 URL입니다.

자체 관리 배포 옵션 중 하나를 사용하는 경우 관리 중인 도메인 이름에 제공된 환경(태그 및 프로덕션) 각각에 대해 고유한 공개 기본 URL을 선택할 수 있습니다. 이 URL은 API 백엔드 중 하나와 달라야 하며 https://api.yourdomain.com:443 처럼 될 수 있습니다. 여기서 yourdomain.com 은 사용자의 도메인입니다. Public Base URL을 설정하면 변경 사항을 저장하고 필요한 경우 스테이징의 변경 사항을 프로덕션으로 승격합니다.

APIcast는 Public Base URL에 지정된 호스트 이름만 허용합니다. 예를 들어 위에서 사용된 Echo API 예제의 경우 https://echo-api.3scale.net:443 를 공개 기본 URL로 지정하면 올바른 호출은 다음과 같습니다.

curl "https://echo-api.3scale.net:443/hello?user_key=YOUR_USER_KEY"

curl "https://echo-api.3scale.net:443/hello?user_key=YOUR_USER_KEY"

API에 대한 공용 도메인이 없는 경우 요청에서 APIcast IP를 사용할 수도 있지만, 공개 기본 URL 필드에 값을 지정해야 합니다(도메인이 실제가 아니더라도) 이 경우 호스트 헤더에 호스트를 제공해야 합니다.

curl "http://192.0.2.12:80/hello?user_key=YOUR_USER_KEY" -H "Host: echo-api.3scale.net"

curl "http://192.0.2.12:80/hello?user_key=YOUR_USER_KEY" -H "Host: echo-api.3scale.net"

로컬 시스템에 배포하는 경우 도메인으로 "#189"을 사용할 수도 있으므로 Public Base URL은 http://localhost:80 과 같이 표시되므로 다음과 같이 요청할 수 있습니다.

curl "http://localhost:80/hello?user_key=YOUR_USER_KEY"

curl "http://localhost:80/hello?user_key=YOUR_USER_KEY"

API 서비스가 여러 개 있는 경우 각 서비스에 대해 이 공개 기본 URL을 적절하게 설정해야 합니다. APIcast는 호스트 이름을 기반으로 요청을 라우팅합니다.

프로덕션 환경에서 APIcast가 작동하면 인증 정보 없이 API 백엔드에 대한 직접 액세스를 제한할 수 있습니다. 이 작업을 수행하는 가장 쉬운 방법은 APIcast에서 설정한 Secret Token을 사용하는 것입니다. 설정하는 방법에 대한 자세한 내용은 Advanced APIcast 설정을 참조하십시오.

APIcast를 사용하면 인터넷에서 공개적으로 액세스할 수 없는 API를 보호할 수 있습니다. 요구 사항은 다음과 같습니다.

이 경우 Private Base URL 필드에서 내부 도메인 이름 또는 API의 IP 주소를 설정하고 나머지 단계를 정상적으로 수행할 수 있습니다. 그러나 Staging APIcast 인스턴스는 3scale에서 호스팅하므로 Staging 환경을 활용할 수 없으며 개인 API 백엔드에 액세스할 수 없습니다. 그러나 프로덕션 환경에 APIcast를 배포하면 구성이 올바르면 APIcast가 예상대로 작동합니다.

OpenTracing은 마이크로 서비스를 프로파일링 및 모니터링하는 데 사용되는 API 사양 및 방법입니다. 버전 3.3 이후부터 APIcast에는 OpenTracing libraries 및 Jaeger Tracer 라이브러리 가 포함되어 있습니다.

APIcast 개요에 따라 3scale 관리 포털에서 APIcast 를 구성해야 합니다.

이 가이드에서는 RHEL(Red Hat Enterprise Linux) 7에서 Docker 컨테이너화된 환경을 설정하는 단계를 설명합니다.

Red Hat에서 제공하는 Docker 형식의 컨테이너는 RHEL에서 Extras 채널의 일부로 릴리스됩니다. 추가 리포지토리를 활성화하려면 Subscription Manager 또는 yum config manager를 사용할 수 있습니다. 자세한 내용은 RHEL 제품 설명서를 참조하십시오.

AWS EC2 인스턴스에 RHEL 7을 배포하려면 다음 단계를 따르십시오.

다른 운영 체제의 경우 다음 Docker 설명서를 참조하십시오.

이 명령은 포트 8080 에서 "apicast" 라는 Docker 형식의 컨테이너를 실행하고 3scale 포털에서 JSON 구성 파일을 가져옵니다. 다른 구성 옵션은 APIcast 개요 가이드를 참조하십시오.

이전 단계에서는 Docker 형식의 컨테이너가 3scale 레지스트리에서 자체 구성 파일 및 Docker 형식의 이미지로 실행 중인지 확인합니다. 포트 8080 에서 APIcast를 통해 호출을 테스트하고 3scale 계정에서 가져올 수 있는 올바른 인증 정보를 제공할 수 있습니다.

테스트 호출은 APIcast가 올바르게 실행되고 있는지 확인할 뿐만 아니라 인증 및 보고가 성공적으로 처리되고 있는지도 확인합니다.

아래 튜토리얼 단계를 따르려면 먼저 3scale 관리 포털에서 APIcast를 APIcast 개요 에 따라 구성해야 합니다. 통합 설정에서 자체 관리 게이트웨이가 배포 옵션으로 선택되어 있는지 확인합니다. Staging 및 Production 환경을 계속 진행하도록 구성되어 있어야 합니다.

이미 실행 중인 OpenShift 클러스터가 있는 경우 이 단계를 건너뛸 수 있습니다. 그렇지 않은 경우 계속 읽으십시오.

프로덕션 배포의 경우 OpenShift 설치에 대한 지침을 따를 수 있습니다.

이 튜토리얼에서는 다음을 사용하여 OpenShift 클러스터를 설치합니다.

sudo systemctl status docker

sudo systemctl status docker

oc cluster up

oc cluster up

    -- Server Information ...
      OpenShift server started.
      The server is accessible via web console at:
      https://172.30.0.112:8443

      You are logged in as:
        User:     developer
        Password: developer

      To login as administrator:
        oc login -u system:admin

    -- Server Information ...
      OpenShift server started.
      The server is accessible via web console at:
      https://172.30.0.112:8443

      You are logged in as:
        User:     developer
        Password: developer

      To login as administrator:
        oc login -u system:admin

oc cluster up --public-hostname=ec2-54-321-67-89.compute-1.amazonaws.com --routing-suffix=54.321.67.89.xip.io

oc cluster up --public-hostname=ec2-54-321-67-89.compute-1.amazonaws.com --routing-suffix=54.321.67.89.xip.io

보안상의 이유로 3scale 게이트웨이에서 API 백엔드로의 모든 요청에는 X-3scale-proxy-secret-token 이라는 헤더가 포함됩니다. 통합 페이지의 인증 설정에서 이 헤더 값을 설정할 수 있습니다.

View larger image

시크릿 토큰을 설정하면 프록시와 API 간에 공유 시크릿 역할을 하므로 사용자가 필요하지 않은 경우 게이트웨이에서 가져오지 않는 모든 API 요청을 차단할 수 있습니다. 이렇게 하면 샌드박스 게이트웨이를 사용하여 트래픽 관리 정책을 설정하는 과정에서 공용 끝점을 보호할 수 있는 추가 보안 계층이 추가됩니다.

API 백엔드에는 게이트웨이가 작동할 수 있는 공개 확인 가능한 도메인이 있어야 하므로 API 백엔드를 알고 있는 모든 사용자가 인증 정보를 바이패스할 수 있습니다. 스테이징 환경의 API 게이트웨이는 프로덕션 사용을 위한 것이 아니라, 항상 펜싱을 사용할 수 있기 때문에 문제가 되지 않아야 합니다.

3scale 내의 API 인증 정보는 사용 중인 인증 모드에 따라 user_key 또는 app_id/app_key 입니다. OpenID Connect는 스테이징 환경의 API 게이트웨이에 적합하지만 통합 페이지에서 테스트할 수 없습니다.

그러나 API에서 다양한 자격 증명 이름을 사용할 수 있습니다. 이 경우 API 키 모드를 사용하는 경우 user_key 의 사용자 정의 이름을 설정해야 합니다.

View larger image

또는 app_id 및 app_key 의 경우:

View larger image

예를 들어 API에 더 적합한 경우 app_id 를 key 로 변경할 수 있습니다. 게이트웨이는 3scale 백엔드에 대한 권한 부여 호출을 수행하기 전에 name 키를 사용하여 app_id 로 변환합니다. 새 자격 증명 이름은 영숫자여야 합니다.

API가 쿼리 문자열(또는 GET이 아닌 경우 본문) 또는 헤더에서 인증 정보를 전달하는지 여부를 결정할 수 있습니다.

View larger image

완전한 구성을 위한 또 다른 중요한 요소는 사용자 정의 오류 메시지를 정의하는 것입니다.

스테이징 환경의 3scale API 게이트웨이는 API에서 생성한 오류 메시지를 전달합니다. 그러나 이제 API의 관리 계층을 게이트웨이에서 수행하므로 일부 요청이 게이트웨이에 의해 종료되므로 API에서 볼 수 없는 몇 가지 오류가 있습니다.

View larger image

다음은 몇 가지 오류입니다.

Update & Test Staging Configuration 버튼을 클릭하면 현재 구성이 JSON 파일에 저장됩니다. 스테이징 게이트웨이는 새 요청마다 최신 구성을 가져옵니다. 각 환경인 스테이징 또는 프로덕션 환경에 대해 이전의 모든 구성 파일의 기록을 볼 수 있습니다.

이전 버전으로 자동으로 롤백할 수 없습니다. 대신 관련 JSON 파일이 있는 모든 구성 버전의 기록이 제공됩니다. 이 파일을 사용하여 언제든지 배포한 구성을 확인합니다. 원하는 경우 배포를 수동으로 다시 생성할 수 있습니다.

게이트웨이 구성을 설정하는 것은 쉽지만 여전히 오류가 발생할 수 있습니다. 이러한 경우 게이트웨이는 유용한 디버그 정보를 반환하여 오류를 추적할 수 있습니다.

APIcast에서 디버깅 정보를 얻으려면 API 요청에 다음 헤더를 추가해야 합니다. X-3scale-debug: {SERVICE_TOKEN} 에 도달한 API 서비스에 해당하는 서비스 토큰이 있어야 합니다.

헤더가 있고 서비스 토큰이 유효하면 게이트웨이는 응답 헤더에 다음 정보를 추가합니다.

X-3scale-matched-rules: /v1/word/{word}.json, /v1
X-3scale-credentials: app_key=APP_KEY&app_id=APP_ID
X-3scale-usage: usage%5Bversion_1%5D=1&usage%5Bword%5D=1

X-3scale-matched-rules: /v1/word/{word}.json, /v1
X-3scale-credentials: app_key=APP_KEY&app_id=APP_ID
X-3scale-usage: usage%5Bversion_1%5D=1&usage%5Bword%5D=1

x-3scale-matched-rules 는 쉼표로 구분된 목록에서 요청에 일치하는 매핑 규칙을 나타냅니다.

X-3scale-credentials 헤더는 3scale 백엔드에 전달된 인증 정보를 반환합니다.

x-3scale-usage 는 3scale 백엔드에 보고된 사용량을 나타냅니다. usage%5Bversion_1%5%5D=1&usage%5B word %5D=1 은 URL로 인코딩된 사용 [version_1]=1&usage[word]=1 이며 API 요청이 각각 1개의 메서드(metrics) 버전_1 을 초과했음을 보여줍니다.

APIcast는 3scale 계정에 구성된 모든 API 서비스를 처리합니다(또는 APICAST_SERVICES_LIST 환경 변수가 구성된 경우 서비스의 하위 집합). 일반적으로 APIcast는 공용 기본 URL 과 일치하여 요청의 호스트 이름을 기반으로 API 요청을 적절한 API 서비스로 라우팅합니다. 일치 항목이 있는 첫 번째 서비스는 권한 부여에 사용됩니다.

경로 라우팅 기능을 사용하면 여러 서비스에서 동일한 공용 기본 URL 을 사용할 수 있으며 요청 경로를 사용하여 요청을 라우팅할 수 있습니다. 기능을 활성화하려면 APICAST_PATH_ROUTING 환경 변수를 true 또는 1 로 설정합니다. 이 기능을 활성화하면 APIcast는 호스트 이름과 경로를 기반으로 들어오는 요청을 서비스에 매핑합니다.

이 기능은 동일한 공용 기본 URL 을 사용하는 하나의 게이트웨이를 통해 다른 도메인에 호스팅되는 여러 백엔드 서비스를 노출하려는 경우에 사용할 수 있습니다. 이를 위해 각 API 백엔드(예: Private Base URL)에 대해 여러 API 서비스를 구성하고 경로 라우팅 기능을 활성화할 수 있습니다.

예를 들어 다음과 같은 방법으로 3개의 서비스가 구성되어 있습니다.

경로 라우팅이 비활성화되어 있는 경우(APICAST_PATH_ROUTING=false), api.example.com 에 대한 모든 호출은 서비스 A. 즉, api.example.com/c 및 api.example.com/b 호출이 "No Mapping Rule matched" 오류와 함께 실패합니다.

경로 라우팅이 활성화된 경우(APICAST_PATH_ROUTING=true) 호스트 및 경로와 모두 호출이 일치합니다. so:

경로 라우팅을 사용하는 경우 동일한 공개 기본 URL 을 사용하는 여러 서비스의 매핑 규칙 간에 충돌이 없는지 확인해야 합니다. 즉 메서드 + 경로 패턴의 각 조합은 하나의 서비스에서만 사용됩니다.

Red Hat 3scale은 다음과 같은 표준 정책을 제공합니다.

3scale API Management에서 표준 정책을 활성화하고 구성할 수 있습니다.

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

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

5.1.3. 익명 액세스 정책

링크 복사

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

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

참고

이 두 정책을 정책 체인에 함께 사용할 때 APIcast 정책 앞에 무명 액세스 정책을 배치해야합니다.

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

• auth_type: 아래 대안 중 하나에서 값을 선택하고 속성이 API에 대해 구성된 인증 옵션에 해당하는지 확인하십시오.

  • app_id_and_app_key: 앱 ID / 앱 키 인증 옵션입니다.
  • user_key: API 키 인증 옵션입니다.
• app_id ( app_id_and_app_key auth 유형 전용): API 호출을 통해 인증 정보가 제공되지 않는 경우 권한 부여에 사용되는 애플리케이션의 앱 Id입니다.
• app_key ( app_id_and_app_key auth 유형 전용): API 호출과 함께 자격 증명이 제공되지 않는 경우 권한 부여에 사용되는 애플리케이션의 앱 키입니다.
• user_key ( user_key auth_type 전용): API 호출이 제공된 인증 정보가 없는 경우 권한 부여에 사용할 애플리케이션의 API 키입니다.

그림 5.1. 익명 액세스 정책

View larger image

{
  "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"
  }
}

{
  "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"
  }
}

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

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

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

{
  "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"
    }
  ]
}

"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}}"
      }
    ]
  }
}

{
  "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}}"
      }
    ]
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

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

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

5.1.10. 로깅 정책

링크 복사

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

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

View larger image

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

5.1.11. OAuth 2.0 토큰 인트로스펙션 정책

링크 복사

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를 결정합니다.

use_3scale_oidc_issuer_endpoint

이 설정을 사용하면 APIcast에서 클라이언트 인증 정보(클라이언트 ID 및 클라이언트 시크릿)와 서비스 통합 페이지에 구성된 OpenID Connect Issuer 설정에서 Token Introspection Endpoint를 사용합니다.

APIcast는 token_introspection_endpoint 필드에서 OpenID Connect 발급자의 .well-known/openid-configuration 끝점을 반환합니다.

예 5.1. use_3scale_oidc_issuer_endpoint로 설정된 인증 유형

다음은 인증 유형이 use_3scale_oidc_issuer_endpoint 로 설정된 경우 설정 예제입니다.

"policy_chain": [
…​
  {
    "name": "apicast.policy.token_introspection",
    "configuration": {
      "auth_type": "use_3scale_oidc_issuer_endpoint"
    }
  }
…​
],

Copy to Clipboard Toggle word wrap

client_id+client_secret

이 옵션을 사용하면 다른 Token Introspection Endpoint 및 Client Secret APIcast를 지정하여 토큰 정보를 요청할 수 있습니다.

이 옵션을 사용하는 경우 다음 구성 매개변수를 설정합니다.

• client_id: Token Introspection Endpoint의 클라이언트 ID를 설정합니다.
• client_secret: Token Introspection Endpoint에 대한 클라이언트 보안을 설정합니다.

• introspection_url: Introspection Endpoint URL을 설정합니다.

  예 5.2. client_id+client_secret으로 설정된 인증 유형

  인증 유형이 client_id+client_secret 으로 설정된 경우 다음은 구성 예제입니다.

  "policy_chain": [
  …​
    {
      "name": "apicast.policy.token_introspection",
      "configuration": {
        "auth_type": "client_id+client_secret",
        "client_id": "myclient",
        "client_secret": "mysecret",
        "introspection_url": "http://red_hat_single_sign-on/token/introspection"
      }
    }
  …​
  ],

  Copy to Clipboard Toggle word wrap

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

View larger image

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

• True: 호출이 승인되었습니다.
• False: 호출이 Authentication Failed 오류와 함께 거부됨

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

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

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

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

      }
    ]
  }
}

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

      }
    ]
  }
}

{
  "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"
      }
    ]
  }

{
  "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.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

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

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

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

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

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

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

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

관리 포털에서 정책을 활성화하려면 다음 단계를 수행합니다.

사용자 정의 APIcast 정책을 완전히 만들거나 표준 정책을 수정할 수 있습니다.

사용자 지정 정책을 생성하려면 다음을 이해해야 합니다.

사용자 지정 정책을 생성한 경우 APIcast에 추가해야 합니다. 이 방법은 APIcast가 배포된 위치에 따라 다릅니다.

다음 APIcast 자체 관리 배포에 사용자 정의 정책을 추가할 수 있습니다.

사용자 정의 정책을 APIcast 호스팅에 추가할 수 없습니다.

APIcast 게이트웨이 구성의 일부로 AMP에 정책 체인을 만듭니다. 다음 단계에 따라 UI에서 정책 체인을 수정합니다.

APIcast 기본 배포를 사용하는 경우 JSON 구성 파일을 생성하여 AMP 외부에서 정책 체인을 제어할 수 있습니다.

JSON 구성 파일 정책 체인에는 다음 정보로 구성된 JSON 배열이 포함되어 있습니다.

다음은 사용자 정의 정책 sample_policy_1 및 API 인트로스펙션 표준 정책 token_introspection 에 대한 정책 체인의 예입니다.

{
  "services":[
    {
      "id":1,
      "proxy":{
        "policy_chain":[
          {
            "name":"sample_policy_1", "version": "1.0",
            "configuration":{
              "sample_config_param_1":["value_1"],
              "sample_config_param_2":["value_2"]
            }
          },
          {
            "name": "token_introspection", "version": "builtin",
            "configuration": {
              introspection_url:["https://tokenauthorityexample.com"],
              client_id:["exampleName"],
              client_secret:["secretexamplekey123"]
          },
          {
             "name": "apicast", "version": "builtin",
          }
        ]
      }
    }
  ]
}

{
  "services":[
    {
      "id":1,
      "proxy":{
        "policy_chain":[
          {
            "name":"sample_policy_1", "version": "1.0",
            "configuration":{
              "sample_config_param_1":["value_1"],
              "sample_config_param_2":["value_2"]
            }
          },
          {
            "name": "token_introspection", "version": "builtin",
            "configuration": {
              introspection_url:["https://tokenauthorityexample.com"],
              client_id:["exampleName"],
              client_secret:["secretexamplekey123"]
          },
          {
             "name": "apicast", "version": "builtin",
          }
        ]
      }
    }
  ]
}

모든 정책 체인에는 기본 제공 정책 API cast 가 포함되어야 합니다. 정책 체인에 APIcast를 배치하면 정책 동작에 영향을 미칩니다.

일부 5.1절. “APIcast 표준 정책” 에서는 일반 문자열 값뿐만 아니라 요청 컨텍스트에 있는 변수도 사용할 수 있는 Liquid templating을 지원합니다.

컨텍스트 변수를 사용하려면 해당 이름을 {{ and }} }}로 래핑합니다. 예: {{}} }}. 변수가 오브젝트인 경우 해당 속성(예: {{ somevar.attr }} }})에 액세스할 수도 있습니다.

다음은 모든 정책에서 사용할 수 있는 표준 변수입니다.

이 변수는 요청 컨텍스트에서 사용할 수 있습니다. 정책은 컨텍스트에 변수를 추가할 수 있습니다. 이러한 변수는 변수가 추가된 단계 이후에 실행되는 경우 정책 체인의 동일한 또는 기타 정책에서 사용할 수 있습니다. 변수가 추가된 정책 뒤에 표시되는 정책에 변수가 사용되는 경우 동일한 단계일 수도 있습니다.

다음은 표준 3scale APIcast 정책이 컨텍스트에 추가하는 변수의 몇 가지 예입니다.

컨텍스트에서 오브젝트 및 값의 전체 목록은 5.1.9절. “유동 컨텍스트 디버그 정책”을 참조하십시오.

변수는 Liquid 템플릿의 도움말과 함께 사용됩니다. 예: {{ remote_addr }} }}, {{ headers['Some-Header'] }}, {{ jwt.aud }} }}. 값의 변수를 지원하는 정책에는 일반적으로 _type 접미사(예: value_type,name_type 등)가 있는 특수 매개 변수가 있으며, 일반 텍스트에 대해 "plain"과 tier 템플릿에 "liquid"를 사용할 수 있습니다.

APIcast는 변수 값에 적용할 수 있는 Liquid 필터도 지원합니다. 필터는 Liquid 변수의 값에 NGINX 함수를 적용합니다.

필터는 변수 출력 태그 {{ }} }} 내에 배치되며, 변수 이름 또는 리터럴 값에 따라 파이프 문자 | 및 필터 이름으로 배치됩니다. 예: {{ 'username:password' | encode_base64 }}, {{ URI | escape_uri }} }}.

일부 필터에는 매개변수가 필요하지 않으므로 변수 대신 빈 문자열을 사용할 수 있습니다. 예: {{ '' | utctime }} 는 현재 시간을 UTC 표준 시간대로 반환합니다.

필터는 다음과 같이 연결할 수 있습니다. {{ variable | function1 | function2 }}. 예: {{ '' | utctime | escape_uri }}.

다음은 사용 가능한 함수 목록입니다.